home / skills / oscardrt / supastarter-nextjs-skill / supastarter-nextjs-skill

supastarter-nextjs-skill skill

needs review

This skill guides building supastarter Next.js apps end-to-end with Prisma, oRPC, and Better Auth, accelerating feature delivery and reliable deployment.

npx playbooks add skill oscardrt/supastarter-nextjs-skill --skill supastarter-nextjs-skill

Review the files below or copy the command above to add this skill to your agents.

Files (28)

SKILL.md

6.8 KB

---
name: supastarter-nextjs-skill
description: "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."
license: See LICENSE
metadata:
  author: supastarter
  version: "1.0"
  compatibility: "Designed for Cursor (or similar agents). Run scripts from supastarter monorepo root."
---

# 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](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](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).

| Topic | File |
|-------|------|
| **Coding conventions** (read first) | [references/coding-conventions.md](references/coding-conventions.md) |
| **Code patterns** (examples) | [references/code-patterns.md](references/code-patterns.md) |
| **Quick reference** (commands, paths) | [references/quick-reference.md](references/quick-reference.md) |
| Tech stack | [references/tech-stack.md](references/tech-stack.md) |
| Setup, install, deps | [references/setup.md](references/setup.md) |
| Env, config, feature flags | [references/configuration.md](references/configuration.md) |
| Debugging, common issues | [references/troubleshooting.md](references/troubleshooting.md) |
| Prisma schema, migrations, queries | [references/database-patterns.md](references/database-patterns.md) |
| Hono/oRPC, procedures, router | [references/api-patterns.md](references/api-patterns.md) |
| Better Auth, session, protected endpoints | [references/auth-patterns.md](references/auth-patterns.md) |
| Orgs, roles, multi-tenancy | [references/organization-patterns.md](references/organization-patterns.md) |
| Stripe, webhooks, subscriptions | [references/payments-patterns.md](references/payments-patterns.md) |
| AI features, models | [references/ai-patterns.md](references/ai-patterns.md) |
| UI, theming, extensions | [references/customization.md](references/customization.md) |
| S3-compatible, uploads | [references/storage-patterns.md](references/storage-patterns.md) |
| Emails, templates, providers | [references/mailing-patterns.md](references/mailing-patterns.md) |
| i18n, locales, translations | [references/internationalization.md](references/internationalization.md) |
| Meta, sitemap, structured data | [references/seo.md](references/seo.md) |
| Deploy, production | [references/deployment.md](references/deployment.md) |
| Cron, background jobs | [references/background-tasks.md](references/background-tasks.md) |
| Analytics integration | [references/analytics.md](references/analytics.md) |
| Monitoring, errors | [references/monitoring.md](references/monitoring.md) |
| E2E tests | [references/e2e-testing.md](references/e2e-testing.md) |

## Assets

- **Env template**: [assets/env.example](assets/env.example) – environment variable keys and short comments (no secrets).
- **Full recipe**: [assets/recipes/feedback-widget.md](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](scripts/README.md) or the Scripts section below.

**How to run** (from supastarter monorepo root):

```bash
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](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).

## Official Docs

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

Overview

This skill guides development with the supastarter Next.js starter kit, focused exclusively on Next.js (App Router) workflows and conventions. It helps you design database schemas, add API endpoints, implement auth, configure payments, and ship features end-to-end in the supastarter monorepo. Use it when building, extending, debugging, or deploying supastarter Next.js apps.

How this skill works

The skill inspects the typical monorepo layout (apps/web and packages/*) and prescribes a linear feature workflow: update Prisma schema, add query helpers, implement oRPC procedures, build React UI, and add i18n and tests. It points to specific files and scripts (like scripts/generate_module.py) and references coding conventions and code patterns to ensure consistent TypeScript, Prisma, and oRPC usage. It also maps integration guidance for auth (Better Auth), payments (Stripe), storage, mailing, AI, and deployment.

When to use it

Starting a new supastarter Next.js project or onboarding to the codebase
Adding or changing database models and running Prisma migrations
Creating new API modules or oRPC procedures
Implementing UI components, forms, or i18n strings in the Next.js app
Integrating Stripe, storage, mailing, analytics, or AI features
Debugging setup, configuration, or deployment issues for the monorepo

Best practices

Follow the prescribed feature order: schema → queries → API → UI → i18n to avoid breaking changes
Always read references/coding-conventions.md before coding to match style and exports
Use package exports (e.g. @repo/database) rather than deep relative imports
Add typed Prisma query helpers and export them from queries/index.ts for reuse
Keep server logic in API packages and prefer Server Components in Next.js; only use "use client" when needed
Run migrations and test web + API locally before pushing deployment changes

Example use cases

Create a new feature: add Prisma model, scaffold oRPC module, implement queries, build UI and translations
Add organization and role-based access to an existing endpoint using Better Auth patterns
Integrate Stripe billing and webhooks for subscription flows and map to Prisma models
Add S3-compatible file uploads with storage package and wire upload endpoints to UI
Add AI-powered feature via the ai package and expose a secured oRPC endpoint

FAQ

Do you support Vue/Nuxt templates?

No. This skill is strictly for the supastarter Next.js starter kit and App Router workflows.

How do I scaffold a new API module?

Use python scripts/generate_module.py <module-name> from the monorepo root, then mount the generated router in packages/api/orpc/router.ts.