next-foundry Docs
Learn what is Foundation, what is Example, what is Optional, and what is Coming Soon so product expectations stay accurate.
Browse Documentation
Follow this order on your first pass
If you're new to the project, use this flow: setup first, then API routes, deployment, and testing.
- Pick Core (default) or Advanced (opt-in) during setup.
- Complete Clerk + DB values in the setup UI; only edit .env.local when setup explicitly instructs you.
- Generate + push Prisma schema, then seed starter data.
- Boot the app and validate sign-in flow locally.
npm run setup
npm run db:generate && npm run db:push && npm run db:seed- Route handlers live in src/app/api/**/route.ts.
- Clerk middleware protects private API surfaces.
- Start from uptime + GitHub integration examples.
- Import repo in Vercel and assign environment variables.
- Use pooled DATABASE_URL in runtime and direct URL for Prisma.
- Run one production sanity test after first deployment.
- Unit tests run with Vitest and React Testing Library.
- Playwright covers core user flows end-to-end.
- Run lint + typecheck before every PR to catch drift early.
npm run lint && npm run typecheck && npm run testUp and running in minutes
Follow these steps to get a fully working local development environment.
Clone the repository
git clone https://github.com/brandonperfetti/next-foundry
cd next-foundryInstall dependencies
npm installRun setup + configure environment
npm run setup
# The setup wizard generates .env.local — add your Clerk keys and DATABASE_URL when promptedSet up the database
npm run db:generate
npm run db:push
npm run db:seedStart the dev server
npm run dev
# Visit http://localhost:3000Environment Variables
Copy .env.example to .env.local and fill in these values.
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYRequiredClerk publishable key from your Clerk dashboard.
CLERK_SECRET_KEYRequiredClerk secret key — never expose to the client.
NEXT_PUBLIC_CLERK_SIGN_IN_URLRequiredSign-in URL, typically /sign-in.
NEXT_PUBLIC_CLERK_SIGN_UP_URLRequiredSign-up URL, typically /sign-up.
CLERK_WEBHOOK_SECRETOptionalWebhook signing secret for Svix signature validation.
DATABASE_URLRequiredPrisma database connection string (PostgreSQL recommended). When using a connection pooler (Vercel Postgres, Supabase), set this to the pooled URL.
PRISMA_DATABASE_URLOptionalDirect (non-pooled) Prisma connection string. Required when using a connection pooler — Prisma uses this for migrations and introspection. Automatically set by Vercel Postgres as POSTGRES_URL_NON_POOLING.
| Variable | Required | Description |
|---|---|---|
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Required | Clerk publishable key from your Clerk dashboard. |
CLERK_SECRET_KEY | Required | Clerk secret key — never expose to the client. |
NEXT_PUBLIC_CLERK_SIGN_IN_URL | Required | Sign-in URL, typically /sign-in. |
NEXT_PUBLIC_CLERK_SIGN_UP_URL | Required | Sign-up URL, typically /sign-up. |
CLERK_WEBHOOK_SECRET | Optional | Webhook signing secret for Svix signature validation. |
DATABASE_URL | Required | Prisma database connection string (PostgreSQL recommended). When using a connection pooler (Vercel Postgres, Supabase), set this to the pooled URL. |
PRISMA_DATABASE_URL | Optional | Direct (non-pooled) Prisma connection string. Required when using a connection pooler — Prisma uses this for migrations and introspection. Automatically set by Vercel Postgres as POSTGRES_URL_NON_POOLING. |
Useful commands while onboarding
npm run dev\nnpm run lint\nnpm run typechecknpm run test\nnpm run test:e2eFrequently Asked Questions
Common questions from developers getting started with the boilerplate.
Ready to build?
All the documentation lives in the README and source code — it's designed to be self-documenting. Clone it and explore.