Adopting This Boilerplate

Purpose

Use this checklist when you create a real project from this boilerplate. It explains what you should change, what you should keep, and what must be configured before local development, staging, and production.

1. Rename the Project

Update the boilerplate identity first so generated metadata, package names, Docker images, and release notes match your app.

After renaming, search for the old name:

rg -n "Next.js-Boilerplate-PostgresQL-Drizzle|next-js-boilerplate-postgresql-drizzle|Next.js Boilerplate" .

Keep only intentional references, such as historical changelog entries.

2. Configure Environment Variables

Start from `.env.example` and create `.env.local`:

cp .env.example .env.local

Use the env files this way:

Do not put real production credentials in `.env.example` or `.env`.

You can skip `.env` entirely if it creates confusion. `.env.local` is enough for local development.

Use `.env` only for team-wide non-secret defaults:

NEXT_PUBLIC_BACKEND_MODE=internal
NEXT_PUBLIC_AUTH_PROVIDER=better-auth
NEXT_PUBLIC_FEATURE_ADMIN=true

Keep personal values in `.env.local`:

DATABASE_URL=postgresql://your-local-db
AUTH_SESSION_SECRET=your-local-secret

Avoid committing `.env` if it contains real credentials or machine-specific values.

For a normal self-contained app, use internal backend + built-in auth:

NEXT_PUBLIC_APP_NAME=Your App Name
APP_PROTOCOL=http
APP_HOST=localhost
PORT=3000
NEXT_PUBLIC_SITE_URL=
NEXT_PUBLIC_API_BASE_URL=

NEXT_PUBLIC_BACKEND_MODE=internal
NEXT_PUBLIC_AUTH_PROVIDER=better-auth

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/your_app_db
AUTH_SESSION_SECRET=<generate-with-openssl-rand-hex-32>

Generate a strong secret:

openssl rand -hex 32

For production, set the same variables in your hosting provider dashboard. Use your deployed HTTPS domain:

NEXT_PUBLIC_SITE_URL=https://your-app.com
NEXT_PUBLIC_API_BASE_URL=

Do not commit real production secrets.

First-time values to change:

Production services to configure when launching:

3. Choose Your Auth Path

Option A: Built-In Auth

Use this when your app should own login, registration, and sessions.

Required:

• `NEXT_PUBLIC_AUTH_PROVIDER=better-auth`
• `NEXT_PUBLIC_BACKEND_MODE=internal`
• `DATABASE_URL`
• `AUTH_SESSION_SECRET`

Then verify:

1. register a real account
2. sign out
3. sign in again
4. open `/docs` or your protected destination
5. check cookies are secure in production

Option B: Custom Auth Provider

Use this when you already have an external auth service or IdP.

Required:

NEXT_PUBLIC_AUTH_PROVIDER=custom-auth
NEXT_PUBLIC_CUSTOM_AUTH_BASE_URL=https://auth.your-company.com

Then update the adapter in `src/modules/optional/auth/custom-auth.adapter.ts` to match your provider's response format.

4. Set Up PostgreSQL and Drizzle

Create a PostgreSQL database locally or with a managed provider such as Neon or Supabase Postgres.

Recommended first-time flow:

pnpm run db:migrate
pnpm run dev

If you change the schema:

1. edit files under `src/db/`
2. generate a migration:

pnpm run db:generate

3. review the generated SQL under `drizzle/`
4. apply it locally:

pnpm run db:migrate

5. commit schema and migration files together

Never run `db:generate` directly in production.

5. Replace Branding and Visual Assets

Update the public-facing assets before launch.

After editing, verify:

pnpm run build

Then open:

• `/icon.svg`
• `/apple-icon.svg`
• `/manifest.webmanifest`
• `/opengraph-image`
• `/twitter-image`

6. Decide What to Keep or Remove

This boilerplate includes useful starter surfaces. Keep only what your product needs.

If you remove a route, also update:

• `src/app/sitemap.ts`
• `src/lib/docs/content.ts` if it was a docs article
• README and docs links
• Playwright tests that visit that route

7. Customize App Routes and Domain Logic

Use the existing structure instead of putting everything in one folder.

Recommended ownership:

When adding a new feature:

1. define the route
2. define data model and migration if needed
3. add API route or server action
4. add UI module
5. add tests for risky behavior
6. update docs if behavior is user-facing

8. Update Documentation

At minimum, update:

• `README.md`
• `docs/how-to-use.md`
• `docs/guides/deployment.md`
• `docs/auth-flow.md` if auth behavior changes
• `docs/architecture.md` if module boundaries change
• `docs/folder-structure.md` if folders change

If you add or remove docs articles, update:

• `src/lib/docs/content.ts`
• `src/app/sitemap.ts`

Run:

pnpm run docs:check

9. Configure GitHub and Releases

Before working with a team:

1. enable branch protection on `main`
2. require CI checks
3. configure repository secrets: - `DATABASE_URL` - `MIGRATION_DATABASE_URL` if migrations use a separate direct DB URL - `AUTH_SESSION_SECRET` - deployment provider secrets if needed
4. create the `production` GitHub environment with required reviewers
5. verify `.github/workflows/migrate-production.yml`
6. decide whether to use Release Please
7. update `.release-please-config.json` package name
8. review `.github/workflows/`

If you do not want automated releases, remove or disable `.github/workflows/release-please.yml` and update README/docs so contributors do not expect release PRs.

10. Production Readiness Checklist

Before public launch:

• app name, metadata, icons, OG/Twitter images are project-specific
• `NEXT_PUBLIC_SITE_URL` is the real HTTPS domain
• `NEXT_PUBLIC_API_BASE_URL` is correct
• `DATABASE_URL` points to production database
• `AUTH_SESSION_SECRET` is strong and private
• migrations have been applied
• production migration workflow has been tested from GitHub Actions
• Sentry receives a test error or smoke-test issue
• Upstash Redis is configured for production auth rate limiting
• Resend sender domain is verified before email-dependent flows are enabled
• login/register/logout/me flows work on deployed URL
• `/docs` article links work
• `/manifest.webmanifest`, `/icon.svg`, and `/apple-icon.svg` return 200
• `pnpm run lint` passes
• `pnpm run typecheck` passes
• `pnpm run test` passes
• `pnpm run build` passes
• provider runtime logs are clean after a smoke test

11. Useful Search Commands

Find remaining boilerplate naming:

rg -n "boilerplate|starter|template|Next.js Boilerplate|azmarif" .

Find environment usage:

rg -n "process\\.env|NEXT_PUBLIC_|DATABASE_URL|AUTH_SESSION_SECRET" src docs .env.example

Find routes to update after removing pages:

rg -n "\"/docs|\"/features|\"/login|\"/register|sitemap" src

Related Docs

• [How to Use](../how-to-use.md)
• [Architecture](../architecture.md)
• [Folder Structure](../folder-structure.md)
• [Auth Setup and Migration](auth-setup-and-migration.md)
• [Database Setup](database-setup.md)
• [Deployment Guide](deployment.md)