oscardrt/supastarter-nextjs-skill

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