supastarter for Next.js – Skill
Expert guidance for building production-ready SaaS applications with the supastarter Next.js starter kit. Next.js only; no Vue/Nuxt content.
When to Use This Skill
Use this skill when:
- Building or modifying a supastarter Next.js app
- Adding features (new entities, API endpoints, UI, i18n)
- Working with Prisma, oRPC, Better Auth, Stripe, or the monorepo structure
- Debugging setup, configuration, deployment, or troubleshooting
- The user mentions supastarter Next.js, Prisma, oRPC, Better Auth, or related stack topics
High-Level Workflow: New Feature
Follow this order when adding a feature:
- Schema – Add or update Prisma models in
packages/database/prisma/schema.prisma; run migrations.
- Queries – Add query functions in
packages/database/prisma/queries/ and export from queries/index.ts.
- API – Add oRPC procedures in
packages/api/modules/<name>/ (types, procedures, router); mount router in packages/api/orpc/router.ts.
- UI – Add React components in
apps/web/ (e.g. modules/shared/components/); use shadcn, TanStack Query, session hooks.
- i18n – Add translation keys in
packages/i18n/translations/{en,de}.json.
Full walkthrough: assets/recipes/feedback-widget.md.
Project Structure (Next.js Monorepo)
apps/web/ # Next.js app (App Router, app/, components/, config/, lib/)
packages/
api/ # Hono + oRPC (modules/, orpc/router.ts)
auth/ # Better Auth config
database/ # Prisma schema, migrations, queries
i18n/ # Translations
mail/ # React Email templates, providers
storage/ # S3-compatible storage
ui/ # Shared UI (shadcn)
config/ # Shared config
Use package exports (e.g. @repo/api, @repo/database) instead of deep relative imports.
References (Progressive Disclosure)
Load only the reference files you need. All paths are from the skill root, one level deep.
Before writing code, read references/coding-conventions.md. For copy-paste patterns and commands, use references/code-patterns.md and references/quick-reference.md.
| Topic |
File |
| Coding conventions (read first) |
references/coding-conventions.md |
| Code patterns (examples) |
references/code-patterns.md |
| Quick reference (commands, paths) |
references/quick-reference.md |
| Tech stack |
references/tech-stack.md |
| Setup, install, deps |
references/setup.md |
| Env, config, feature flags |
references/configuration.md |
| Debugging, common issues |
references/troubleshooting.md |
| Prisma schema, migrations, queries |
references/database-patterns.md |
| Hono/oRPC, procedures, router |
references/api-patterns.md |
| Better Auth, session, protected endpoints |
references/auth-patterns.md |
| Orgs, roles, multi-tenancy |
references/organization-patterns.md |
| Stripe, webhooks, subscriptions |
references/payments-patterns.md |
| AI features, models |
references/ai-patterns.md |
| UI, theming, extensions |
references/customization.md |
| S3-compatible, uploads |
references/storage-patterns.md |
| Emails, templates, providers |
references/mailing-patterns.md |
| i18n, locales, translations |
references/internationalization.md |
| Meta, sitemap, structured data |
references/seo.md |
| Deploy, production |
references/deployment.md |
| Cron, background jobs |
references/background-tasks.md |
| Analytics integration |
references/analytics.md |
| Monitoring, errors |
references/monitoring.md |
| E2E tests |
references/e2e-testing.md |
Assets
- Env template: assets/env.example – environment variable keys and short comments (no secrets).
- Full recipe: assets/recipes/feedback-widget.md – build a feature from DB → API → UI → i18n (feedback widget example).
Scripts
- generate_module.py – Scaffolds a new API module (types, procedures, router). See scripts/README.md or the Scripts section below.
How to run (from supastarter monorepo root):
python scripts/generate_module.py <module-name>
Example: python scripts/generate_module.py feedback creates packages/api/modules/feedback/ with types.ts, procedures/create.ts, and router.ts. Mount the router in packages/api/orpc/router.ts manually.
Conventions (Summary)
- TypeScript everywhere; interfaces for object shapes.
- Named function exports for React components; prefer Server Components; use
"use client" only when needed.
- Forms: react-hook-form + zod; API: oRPC procedures in
packages/api/modules/.
- Use
@repo/* package imports; do not instantiate Prisma/Drizzle in app code.
- pnpm, Biome (format/lint), Turbo; Node.js ≥ 20.
Before writing code, read references/coding-conventions.md. For examples and commands: references/code-patterns.md, references/quick-reference.md, references/customization.md, references/api-patterns.md.
Official Docs
1---2name: supastarter-nextjs-skill3description: "Guides development with supastarter for Next.js only (not Vue/Nuxt): tech stack, setup, configuration, database (Prisma), API (Hono/oRPC), auth (Better Auth), organizations, payments (Stripe), AI, customization, storage, mailing, i18n, SEO, deployment, background tasks, analytics, monitoring, E2E. Use when building or modifying supastarter Next.js apps, adding features, or when the user mentions supastarter Next.js, Prisma, oRPC, Better Auth, or related Next.js stack topics."4license: See LICENSE5metadata:6 source: https://skillmd.com/skills/diegosouzapw/supastarter-nextjs-skill7 author: supastarter8 version: "1.0"9 compatibility: "Designed for Cursor (or similar agents). Run scripts from supastarter monorepo root."10---1112# supastarter for Next.js – Skill1314Expert guidance for building production-ready SaaS applications with the supastarter Next.js starter kit. **Next.js only**; no Vue/Nuxt content.1516## When to Use This Skill1718Use this skill when:1920- Building or modifying a supastarter Next.js app21- Adding features (new entities, API endpoints, UI, i18n)22- Working with Prisma, oRPC, Better Auth, Stripe, or the monorepo structure23- Debugging setup, configuration, deployment, or troubleshooting24- The user mentions supastarter Next.js, Prisma, oRPC, Better Auth, or related stack topics2526## High-Level Workflow: New Feature2728Follow this order when adding a feature:29301. **Schema** – Add or update Prisma models in `packages/database/prisma/schema.prisma`; run migrations.312. **Queries** – Add query functions in `packages/database/prisma/queries/` and export from `queries/index.ts`.323. **API** – Add oRPC procedures in `packages/api/modules/<name>/` (types, procedures, router); mount router in `packages/api/orpc/router.ts`.334. **UI** – Add React components in `apps/web/` (e.g. `modules/shared/components/`); use shadcn, TanStack Query, session hooks.345. **i18n** – Add translation keys in `packages/i18n/translations/{en,de}.json`.3536Full walkthrough: [assets/recipes/feedback-widget.md](assets/recipes/feedback-widget.md).3738## Project Structure (Next.js Monorepo)3940```41apps/web/ # Next.js app (App Router, app/, components/, config/, lib/)42packages/43 api/ # Hono + oRPC (modules/, orpc/router.ts)44 auth/ # Better Auth config45 database/ # Prisma schema, migrations, queries46 i18n/ # Translations47 mail/ # React Email templates, providers48 storage/ # S3-compatible storage49 ui/ # Shared UI (shadcn)50 config/ # Shared config51```5253Use package exports (e.g. `@repo/api`, `@repo/database`) instead of deep relative imports.5455## References (Progressive Disclosure)5657Load only the reference files you need. All paths are from the skill root, one level deep.5859**Before writing code**, read [references/coding-conventions.md](references/coding-conventions.md). For copy-paste patterns and commands, use [references/code-patterns.md](references/code-patterns.md) and [references/quick-reference.md](references/quick-reference.md).6061| Topic | File |62|-------|------|63| **Coding conventions** (read first) | [references/coding-conventions.md](references/coding-conventions.md) |64| **Code patterns** (examples) | [references/code-patterns.md](references/code-patterns.md) |65| **Quick reference** (commands, paths) | [references/quick-reference.md](references/quick-reference.md) |66| Tech stack | [references/tech-stack.md](references/tech-stack.md) |67| Setup, install, deps | [references/setup.md](references/setup.md) |68| Env, config, feature flags | [references/configuration.md](references/configuration.md) |69| Debugging, common issues | [references/troubleshooting.md](references/troubleshooting.md) |70| Prisma schema, migrations, queries | [references/database-patterns.md](references/database-patterns.md) |71| Hono/oRPC, procedures, router | [references/api-patterns.md](references/api-patterns.md) |72| Better Auth, session, protected endpoints | [references/auth-patterns.md](references/auth-patterns.md) |73| Orgs, roles, multi-tenancy | [references/organization-patterns.md](references/organization-patterns.md) |74| Stripe, webhooks, subscriptions | [references/payments-patterns.md](references/payments-patterns.md) |75| AI features, models | [references/ai-patterns.md](references/ai-patterns.md) |76| UI, theming, extensions | [references/customization.md](references/customization.md) |77| S3-compatible, uploads | [references/storage-patterns.md](references/storage-patterns.md) |78| Emails, templates, providers | [references/mailing-patterns.md](references/mailing-patterns.md) |79| i18n, locales, translations | [references/internationalization.md](references/internationalization.md) |80| Meta, sitemap, structured data | [references/seo.md](references/seo.md) |81| Deploy, production | [references/deployment.md](references/deployment.md) |82| Cron, background jobs | [references/background-tasks.md](references/background-tasks.md) |83| Analytics integration | [references/analytics.md](references/analytics.md) |84| Monitoring, errors | [references/monitoring.md](references/monitoring.md) |85| E2E tests | [references/e2e-testing.md](references/e2e-testing.md) |8687## Assets8889- **Env template**: [assets/env.example](assets/env.example) – environment variable keys and short comments (no secrets).90- **Full recipe**: [assets/recipes/feedback-widget.md](assets/recipes/feedback-widget.md) – build a feature from DB → API → UI → i18n (feedback widget example).9192## Scripts9394- **generate_module.py** – Scaffolds a new API module (types, procedures, router). See [scripts/README.md](scripts/README.md) or the Scripts section below.9596**How to run** (from supastarter monorepo root):9798```bash99python scripts/generate_module.py <module-name>100```101102Example: `python scripts/generate_module.py feedback` creates `packages/api/modules/feedback/` with `types.ts`, `procedures/create.ts`, and `router.ts`. Mount the router in `packages/api/orpc/router.ts` manually.103104## Conventions (Summary)105106- TypeScript everywhere; interfaces for object shapes.107- Named function exports for React components; prefer Server Components; use `"use client"` only when needed.108- Forms: react-hook-form + zod; API: oRPC procedures in `packages/api/modules/`.109- Use `@repo/*` package imports; do not instantiate Prisma/Drizzle in app code.110- pnpm, Biome (format/lint), Turbo; Node.js ≥ 20.111112**Before writing code**, read [references/coding-conventions.md](references/coding-conventions.md). For examples and commands: [references/code-patterns.md](references/code-patterns.md), [references/quick-reference.md](references/quick-reference.md), [references/customization.md](references/customization.md), [references/api-patterns.md](references/api-patterns.md).113114## Official Docs115116- Next.js docs (only): <https://supastarter.dev/docs/nextjs>117- Download docs as .md: <https://supastarter.dev/nextjs-docs.zip>