KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #cli #codex #claude-code #dsh-plugin #mcp #react #agent #dsh #deepseek-harness

web-app-template

★ 170 Open GitHub ↗

A minimal web service template 🎃 "npx create-app-foundation@latest" !

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <h1>️️A minimal template for web app 🎃</h1>
  <img src=".internal/site/src/public/images/icon.png" alt="icon" width="120">
  <p>From Zero to Service, Build with Best Practices, Minimal Code, and Essential Tools</p>
  <br />
  <a href="https://hiroppy.github.io/web-app-template/"target="_blank" >📜 Read The Docs 📜</a>
  <br />
  <br />
</div>

Installing this template automatically sets up the following libraries/tools. By saving you significant effort, it allows you to focus entirely on writing your product code.🤗

|             |                                                                                                                                            |                                                                                                                                                      |                                                                                                                                       |                                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **App**     | <div align="center"><img src=".internal/site/src/public/images/libs/nextjs.png" alt="nextjs" width="44"><br>Next.js</div>                  | <div align="center"><img src=".internal/site/src/public/images/libs/tailwind.png" alt="tailwind" width="44"><br>Tailwind CSS</div>                   | <div align="center"><img src=".internal/site/src/public/images/libs/next-auth.png" alt="next-auth" width="44"><br>NextAuth.js</div>   | <div align="center"><img src=".internal/site/src/public/images/libs/react-hook-form.png" alt="react-hook-form" width="44"><br>React Hook Form</div> |
|             | <div align="center"><img src=".internal/site/src/public/images/libs/zod.svg" alt="zod" width="44"><br>Zod </div>                           | <div align="center"><img src=".internal/site/src/public/images/libs/otel.png" alt="otel" width="44"><br>OpenTelemetry</div>                          | <div align="center"><img src=".internal/site/src/public/images/libs/prisma.png" alt="prisma" width="44"><br>Prisma</div>              | <div align="center"><img src=".internal/site/src/public/images/libs/postgresql.png" alt="postgresql" width="44"><br>PostgreSQL</div>                |
|             | <div align="center"><img src=".internal/site/src/public/images/libs/stripe.png" alt="stripe" width="44"><br>Stripe</div>                   |                                                                                                                                                      |                                                                                                                                       |
|             |                                                                                                                                            |                                                                                                                                                      |                                                                                                                                       |
| **Tools**   | <div align="center"><img src=".internal/site/src/public/images/libs/typescript.png" alt="typescirpt" width="44"><br>TypeScript</div>       | <div align="center"><img src=".internal/site/src/public/images/libs/pnpm.svg" alt="pnpm" width="44"><br>pnpm</div>                                   | <div align="center"><img src=".internal/site/src/public/images/libs/biome.png" alt="biome" width="44"><br>Biome </div>                | <div align="center"><img src=".internal/site/src/public/images/libs/prettier.png" alt="prettier" width="44"><br> Prettier</div>                     |
|             | <div align="center"><img src=".internal/site/src/public/images/libs/knip.png" alt="knip" width="44"><br>Knip</div>                         | <div align="center"><img src=".internal/site/src/public/images/libs/editorconfig.png" alt="editorconfig" width="44"><br> EditorConfig </div>         | <div align="center"><img src=".internal/site/src/public/images/libs/lefthook.png" alt="lefthook" width="44"><br> lefthook</div>       | <div align="center"><img src=".internal/site/src/public/images/libs/docker.png" alt="docker" width="44"><br> Docker </div>                          |
|             |                                                                                                                                            |                                                                                                                                                      |                                                                                                                                       |
| **Testing** | <div align="center"><img src=".internal/site/src/public/images/libs/vitest.png" alt="vitest" width="44"><br> Vitest</div>                  | <div align="center"><img src=".internal/site/src/public/images/libs/testing-library.png" alt="testing-library" width="44"><br> Testing Library</div> | <div align="center"><img src=".internal/site/src/public/images/libs/playwright.png" alt="playwright" width="44"><br> Playwright</div> | <div align="center"><img src=".internal/site/src/public/images/libs/testcontainers.png" alt="testcontainers" width="44"><br> Testcontainers</div>   |
|             |                                                                                                                                            |                                                                                                                                                      |
| **Others**  | <div align="center"><img src=".internal/site/src/public/images/libs/github-actions.png" alt="actions" width="44"><br> GitHub Actions</div> | <div align="center"><img src=".internal/site/src/public/images/libs/renovate.png" alt="renovate" width="44"><br> Renovate</div>                      | <div align="center"><img src=".internal/site/src/public/images/libs/vscode.png" alt="vscode" width="44"><br> VSCode</div>             |

Please read the features provided by this template first! 👉
[Challenges Solved](https://hiroppy.github.io/web-app-template/introduction/challenges-solved.html)

## Prerequisites

- Node.js v20 or higher
- [Docker](https://docs.docker.com/engine/install/)

## Installation

When installing the repository, you can skip the setup section, as the init script will do the equivalent of setup.

### Using CLI (recommended)

```sh
$ npx create-app-foundation@latest
```

The CLI creates a project directory and run internal/init script so it's easy to get started.

### Using GitHub Template

This repo is a GitHub template, so click the ["Use this template"](https://github.com/new?template_owner=hiroppy&template_name=web-app-template) button to create your repo. Then, you need to execute the below to finish setting it up.

```sh
$ node .internal/setup/init.mjs
```

### Opt-out

The following items will be asked whether they are required when the project is initialized:

- Sample Application Code
- Dockerfile
- E2E Testing
- Observability feature
- Stripe

## Setup

```sh
# enable corepack
$ npm run setup
# install deps
$ pnpm i
# create ".env" and modify environment variables
$ cp .env.sample .env
```

## Development

```sh
$ pnpm dev
```

### Debugging Stripe

1. Create a subscription [here](https://dashboard.stripe.com/test/products?active=true&create=product&source=product_list) and get `price_id`.

2. Modify the environment variables. The test API key is [here](https://dashboard.stripe.com/test/apikeys).

```sh
STRIPE_SECRET_KEY=
STRIPE_PRICE_ID=
```

3. [Install stripe CLI](https://docs.stripe.com/stripe-cli) to bypass the webhook.

4. Execute the following command in another terminal.

```sh
$ pnpm dev:stripe
```

5. Add webhook signing secret like `whsec_...` from the cli output to env file

```
STRIPE_WEBHOOK_SECRET=whsec_...
```

6. After signing in, you can go to the `http://localhost:3000/me/payment` page to see how to make a payment.

## Production

```sh
$ pnpm db:up
$ pnpm build
$ pnpm start
```

### Observability

This template uses Jaeger as a tracing platform. The local environment doesn't require `TRACE_EXPORTER_URL` environment value.

```sh
# open Jaeger
$ open http://localhost:16686/
```

## Test

### Unit Test

```sh
$ pnpm test
$ pnpm test:watch
```

### E2E Test

A build task must be executed before running tests to bypass JWT logic.

```sh
# install chrome
$ pnpm exec playwright install chrome

$ pnpm build

$ pnpm test:e2e
$ pnpm test:e2e:ui
```

## Database

```sh
$ pnpm db:migrate
$ pnpm db:reset
# view the database items
$ pnpm db:studio
```

## Links

- [Web App Template](https://hiroppy.github.io/web-app-template/)

web-app-template

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README