supastarter-nextjs-skill

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:

1. Schema – Add or update Prisma models in packages/database/prisma/schema.prisma; run migrations.
2. Queries – Add query functions in packages/database/prisma/queries/ and export from queries/index.ts.
3. API – Add oRPC procedures in packages/api/modules/<name>/ (types, procedures, router); mount router in packages/api/orpc/router.ts.
4. UI – Add React components in apps/web/ (e.g. modules/shared/components/); use shadcn, TanStack Query, session hooks.
5. 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

• Next.js docs (only): https://supastarter.dev/docs/nextjs
• Download docs as .md: https://supastarter.dev/nextjs-docs.zip