Skip to content

Latest commit

 

History

History
223 lines (154 loc) · 5.95 KB

README.md

File metadata and controls

223 lines (154 loc) · 5.95 KB
Raw
️️A minimal template for web app 🎃


This template is based on create-next-app but has below new tech and configs.

Kind
App Next.js (Framework) Tailwind CSS (CSS)
React Hook Form (Form) Zod (Schema Validator)
Prisma (ORM) NextAuth.js (Auth) OpenTelemetry (Observability)
Tools TypeScript (Language) pnpm (Package Manager) NVM (Node Version manager)
Biome (Linter, Formatter) Prettier (Formatter)
lint-staged (Pre Commit) Docker Compose (Docker)
Testing Vitest (Test Runner) Testing Library (React) Playwright (E2E Testing)
Others GitHub Workflows (CI) Renovate (Deps Manager) .vscode (Editor)

Just running create-next-app does not satisfy the dependencies, development environment, and CI environment to create a web application. In addition, many dependencies require setting configs for example, @next-auth/prisma-adapter requires adding many schemas to schema.prisma but we don't know what we add so always need to check the docs every time. This project is created as a template with minimal code in advance so that you can focus on development.

🐕 What does this project support?

Next.js
  • introducing parallel route and intercepting route
  • introducing server actions using Zod
  • setting common files like robots, opengraph-image, etc
  • supporting Docker
  • supporting observability using OpenTelemetry
Prisma
  • introducing dev/test env using Docker Compose and PostgreSQL
  • fixing well-known Next.js issue
  • generating ERD automatically
  • running migration on github actions
NextAuth.js
  • introducing Google Oauth provider
  • defining Prisma schema and connecting database
  • setting Next.js api route using app router
Biome, Prettier
  • introducing how to control these when pre-commit
  • assigning Prisma, Biome, Prettier to each language for vscode
Playwright
  • introducing Page object models for e2e to make it resistant to change code
  • introducing how to avoid OAuth Providers with NextAuth.js
CI
  • CI tasks: lint, build, unit test, e2e test
  • Prod tasks: migrating DB when main branch

Install

GitHub Template

This repo is a github template so click the "Use this template" button and you will create your repo.

CLI

create-app-foundation creates a directory based on this template and skips the setup section automatically.

npx create-app-foundation

Setup

1. Installing Docker Compose

Please check Installation scenarios section.

2. Enabling git hook and corepack

npm run setup

3. Installing Deps

pnpm i

4. Creating .env.local and modifying environment variables

cp .env.sample .env.local

Set the following environment variables in .env.local.

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

If you don't use Google OAuth, you can remove a provider from _clients/NextAuth.ts.

5. Running init.mjs

  • generating DB migration files
  • removing unnecessary code
  • updating name in package.json using directory name
node init.mjs

Dev

# start docker-compose, migrations(generating the client), and next dev
pnpm dev
# create new migration
pnpm dev:db:migrate
# reset the DB
pnpm dev:db:reset
# view the contents
pnpm dev:db:studio

📙 Database ER diagram

Test

Test uses also DB so need to start DB first.

# unit test

# run the DB and generate the client
pnpm test:db:setup
# execute
pnpm test
# watch the unit test
pnpm test:watch
# reset the DB
pnpm test:db:reset

# e2e

# install chrome
pnpm exec playwright install chrome
# run the DB and generate the client
pnpm test:db:setup
# test uses a built app since next.js has different cache behavior between development and production
pnpm build
# execute
pnpm test:e2e

💁‍♀️ This template recommends using a real database but when you face not keeping idempotency, you might consider using mock.

Prod

pnpm db:start
pnpm build
pnpm start

If you set POSTGRESQL_URL as GitHub secrets, you will be able to execute migration for database on GitHub actions(.github/workflows/migration.yml).

Observability

This project has OpenTelemetry and it works only production environment.

Local

pnpm db:start
pnpm build
pnpm start
# open Jaeger
open http://localhost:16686/

jaeger

Server

Please add a url to process.env.TRACE_EXPORTER_URL.