Nfs scaffold app

Scaffold a new fullstack back-office app

This skill bootstraps a brand-new project on the pure Next.js (App Router) fullstack stack — no tRPC, no separate API service, no SPA shell. It is the entry point for the nextjs-fullstack-starter plugin and is invoked either explicitly via /nfs-scaffold-app or when the user expresses intent to start a new back-office system on plain Next.js.

When to use this skill

Use this skill when the user is starting a brand-new project in one of these shapes:

• Internal admin dashboard / management system
• Back-office tool for staff
• Line-of-business app with CRUD over rich domain models
• Lightweight ERP / operational tool
• Solo or small-team SaaS where the main app is auth-walled
• Any "one Next.js app does everything" project

Do NOT use this skill for:

• Adding a feature to an existing project (those have their own skills — nfs-add-auth, nfs-add-cache, nfs-add-mcp).
• Projects where the user wants tRPC + SPA mode — use the sibling plugin nextjs-trpc-prisma-starter instead.
• Public-facing marketing sites or content sites where the patterns don't apply.
• Mobile-first products that need a typed HTTP API surface — Server Actions are web-only.

Why an interactive flow

The stack is opinionated but the project has variables (database, auth provider, whether to wire cache from day one, MCP, deploy target). Asking up front means the generated project is complete and consistent rather than half-configured. The user can always add things later via the nfs-add-* skills.

Use the AskUserQuestion tool for each step so the user gets a clean UI with options. Ask one question per call, not all at once — they shape later questions (e.g. answering "PostgreSQL" determines which Prisma adapter to install).

Conversation flow

Walk the user through these questions in this order. Stop and confirm before any file write.

1. Project name

Open-ended. Validate: lowercase, hyphens-only, no spaces, valid as both a folder name and an npm package name.

2. Project location

Options:

• New directory under current working directory (e.g. ./<project-name>/)
• Use current working directory (must be empty — check first with ls -A)
• Custom absolute path

If "current directory" is chosen, run ls -A and abort if anything other than .git/ is present. Don't overwrite the user's stuff.

3. Database

Options:

• PostgreSQL (recommended) — production default. Uses @prisma/adapter-pg driver.
• SQLite — for prototyping / very small deployments. No driver adapter needed.
• MySQL — if the team has existing MySQL infrastructure.

Skip MongoDB — Prisma supports it but the patterns in architecture-patterns assume relational. Tell the user that if they ask.

4. Auth

Options:

• Better Auth (recommended) — modern, RBAC built-in, MCP plugin available, credentials + magic-link + OAuth providers.
• Skip for now — generate without auth wiring; user can run /nfs-add-auth later.

Don't offer NextAuth here — Better Auth is the locked default for this stack because it integrates cleanly with the MCP plugin and has a simpler RBAC story. If the user pushes back, talk it through, but don't generate a NextAuth scaffold.

5. Cache

Options:

• Next.js default cache (recommended for start) — built-in cacheTag + cacheLife + updateTag. In-process. Fine until measurably not.
• Add Redis on top — wire ioredis + a Next.js cache handler from day one. Useful if multi-process / multi-deploy cache coherence matters.

6. MCP entry point

Options:

• Yes (recommended) — wires /api/mcp/route.ts with Better Auth's mcp plugin acting as OAuth provider. Adds one example tool. Requires Better Auth (from step 4) — if user skipped auth, warn and offer to enable both.
• Skip — easy to add later via /nfs-add-mcp.

7. Deployment target

Options:

• Self-hosted Docker (e.g. on EC2) — adds Dockerfile, docker-compose.yml, next.config.ts with output: 'standalone'.
• Vercel — adds vercel.ts config, no Dockerfile, adjusts a couple of patterns (e.g. cron via Vercel Crons instead of in-process node-cron).
• Both / undecided — adds the Docker bits but doesn't strip Vercel compat.

8. Email / templates (optional)

Options:

• Skip
• Resend + Handlebars — wires src/server/integrations/resend/, outbox pattern, retry cron.

9. PDF generation (optional)

Options:

• Skip
• Gotenberg — adds src/server/integrations/gotenberg/ + docker-compose.yml service.

10. Confirm

Show a summary of all choices and the file/folder list that will be generated. User confirms or backs up.

Generated structure

Files generated are derived from the answers plus the templates in assets/. The canonical layout is documented in references/folder-structure.md — read it before writing.

Top level:

<project-name>/
├── src/
│   ├── app/
│   │   ├── (auth)/login/page.tsx
│   │   ├── (dashboard)/
│   │   │   ├── layout.tsx                # sidebar + requireSession()
│   │   │   ├── page.tsx                  # placeholder home
│   │   │   └── _example/                 # sample CRUD page (list + new + [id])
│   │   ├── (mcp)/mcp/route.ts            # if MCP=yes
│   │   ├── api/
│   │   │   ├── auth/[...all]/route.ts    # if Better Auth
│   │   │   ├── health/route.ts
│   │   │   └── webhooks/                 # placeholder folder
│   │   ├── layout.tsx
│   │   └── globals.css
│   ├── server/
│   │   ├── db/client.ts
│   │   ├── auth/
│   │   │   ├── index.ts
│   │   │   ├── session.ts                # requireSession()
│   │   │   └── permissions.ts            # requirePermission()
│   │   ├── modules/
│   │   │   └── _example/                 # sample service + schema
│   │   │       ├── _example.service.ts
│   │   │       └── _example.schema.ts
│   │   ├── actions/
│   │   │   └── _example.actions.ts       # sample Server Action
│   │   ├── jobs/                         # cron registration
│   │   │   └── index.ts
│   │   ├── lib/
│   │   │   ├── logger.ts
│   │   │   ├── errors.ts
│   │   │   └── cache.ts                  # if cache=Redis
│   │   ├── mcp/                          # if MCP=yes
│   │   │   ├── registry.ts
│   │   │   └── tools/_example.ts
│   │   └── integrations/                 # placeholder folder
│   ├── components/ui/                    # shadcn primitives (added as needed)
│   ├── lib/utils.ts
│   ├── hooks/
│   └── env.ts                            # @t3-oss/env-nextjs
├── prisma/
│   ├── schema.prisma
│   ├── migrations/
│   └── seed.ts
├── tests/
│   └── e2e/                              # Playwright placeholder
├── public/
├── docs/
│   ├── handoff.md                        # session-handoff doc (start-here for Claude)
│   └── architecture.md                   # link to plugin's docs/
├── instrumentation.ts                    # boots cron in production
├── .env.example
├── .gitignore
├── CLAUDE.md                             # generated, reflects choices
├── Dockerfile                            # if deploy=docker
├── docker-compose.yml                    # postgres + (gotenberg + redis if enabled)
├── next.config.ts
├── tsconfig.json
├── package.json
├── jest.config.js
└── README.md

Generation steps in order

Execute these steps sequentially. After each step, briefly confirm completion before moving on.

1. Create root + directory tree. mkdir -p the full tree.
2. Write package.json from assets/package.json.template, filling in dependencies based on choices. (Drop ioredis if cache=skip; drop resend if email=skip; etc.)
3. Write tsconfig.json (assets/tsconfig.json.template), next.config.ts (assets/next.config.ts.template), jest.config.js (assets/jest.config.js.template).
4. Write .eslintrc.json (assets/eslintrc.template) and .prettierrc.json (assets/prettierrc.template) — the verification gate uses both.
5. Write .gitignore from assets/gitignore.template.
6. Write prisma/schema.prisma from assets/prisma-schema.starter.prisma, swapping the datasource provider per the DB choice. Includes User / Session / Account / Verification / Role / Permission / RolePermission / UserRole / AuditLog / Example models out of the box.
7. Write src/env.ts from assets/env.ts.template, only including the env keys the project's enabled features need (drop REDIS_URL if cache=skip, etc.).
8. Write .env.example using references/env-example-template.md — block-assembled from feature flags.
9. Write src/server/db/client.ts from assets/db-client.ts.template.
10. Write the auth scaffolding (if not skipped):
    • src/server/auth/index.ts from assets/auth-index.ts.template
    • src/server/auth/session.ts from assets/auth-session.ts.template
    • src/server/auth/permissions.ts from assets/auth-permissions.ts.template
    • src/lib/auth-client.ts from assets/auth-client.ts.template
    • src/app/(auth)/login/page.tsx from assets/login-page.tsx.template
    • src/app/api/auth/[...all]/route.ts from assets/api-auth-route.ts.template
11. Write src/server/lib/logger.ts (assets/logger.ts.template) and src/server/lib/errors.ts (assets/errors.ts.template).
12. Write src/server/modules/audit/audit.service.ts from assets/audit-service.ts.template so the example service's audit calls actually resolve.
13. Write the service-layer scaffolding — src/server/modules/_example/_example.service.ts (assets/example-service.ts.template) + _example.schema.ts (assets/example-schema.ts.template). Shows userId-first, permission check, audit-inside-transaction.
14. Write the Server Action scaffolding — src/server/actions/_example.actions.ts from assets/example-action.ts.template. Shows 'use server' + safeParse + revalidatePath + updateTag + redirect.
15. Write the styling roots:
    • src/app/globals.css from assets/globals.css.template
    • postcss.config.mjs from assets/postcss.config.template
    • (No tailwind.config needed — Tailwind v4 reads @theme blocks from globals.css.)
16. Write the root layout — src/app/layout.tsx from assets/root-layout.tsx.template (imports globals.css, renders <html>/<body>, wires <Toaster />).
17. Write the dashboard layout + home —
    • src/app/(dashboard)/layout.tsx from assets/dashboard-layout.tsx.template (calls requireSession(), renders sidebar)
    • src/app/(dashboard)/page.tsx from assets/dashboard-home-page.tsx.template
18. Write the sample page tree — src/app/(dashboard)/_example/page.tsx from assets/example-list-page.tsx.template and new/page.tsx from assets/example-new-page.tsx.template.
19. Write the health route — src/app/api/health/route.ts from assets/api-health-route.ts.template. This is the documented exception to Rule 1 (the route does a direct DB call — necessary for ALB / Caddy probes).
20. Write the MCP route + registry + one example tool (if requested) — inline the code blocks from nfs-add-mcp/SKILL.md into src/app/(mcp)/mcp/route.ts, src/server/mcp/registry.ts, src/server/mcp/tools/_example.ts, plus the two .well-known OAuth discovery routes. Add the three OAuth tables to prisma/schema.prisma. (The MCP files don't have assets/ templates — they live in the add-mcp skill as the canonical reference.)
21. Write instrumentation.ts (assets/instrumentation.ts.template) + src/server/jobs/index.ts (assets/jobs-index.ts.template) so cron registers once at boot.
22. Write the seed + admin-bootstrap scripts —
    • prisma/seed.ts from assets/seed.ts.template (seeds default roles + permissions + role-permission joins)
    • prisma/grant-sysadmin.ts from assets/grant-sysadmin.ts.template (one-shot CLI to grant sysadmin after a user signs up)
23. Write Dockerfile (assets/dockerfile.template) + docker-compose.yml (assets/docker-compose.yml.template) if Docker deploy.
24. Write CLAUDE.md from assets/claude-md.template, substituting {{PROJECT_NAME}}, {{ONE_LINE_DESCRIPTION}}, {{DB_NAME}}, {{AUTH_BLOCK}}, {{DEPLOY_NOTE}}, {{DEPLOY_BLOCK}}. This is the contract for future Claude sessions.
25. Write docs/handoff.md from assets/handoff.md.template, substituting today's date and the per-feature state lines.
26. Write docs/architecture.md — copy from <plugin-root>/docs/architecture.md (at the plugin's root, not under any skill folder).
27. Write README.md from assets/readme.template.
28. git init + first commit chore: initial scaffold from nextjs-fullstack-starter. Tell the user explicitly: "I'm creating a nested independent git repo here — it's not a submodule of any outer repo."
29. Verification step — run pnpm install, pnpm prisma generate, pnpm tsc --noEmit, pnpm lint. Report results. Do not try to run migrations (no DB yet); the user owns that.

{{VARIABLE}} substitution reference

Many templates carry {{...}} slots. The full table:

Variable	Source / value
{{PROJECT_NAME}}	Q1 answer (e.g. inventory-tracker)
{{PROJECT_NAME_SNAKE}}	{{PROJECT_NAME}} with - → _ (e.g. inventory_tracker); used for DB names
{{ONE_LINE_DESCRIPTION}}	Asked separately or defaulted to "An internal back-office app."
{{DB_NAME}}	PostgreSQL / SQLite / MySQL (Q3)
{{PRISMA_PROVIDER}}	postgresql / sqlite / mysql (lowercase form for datasource db)
{{AUTH_BLOCK}}	Better Auth if enabled, (no auth wired yet — run /nfs-add-auth to add) if skipped
{{AUTH_DEP}}	better-auth if auth enabled, else removed from package.json
{{AUTH_DEP_VERSION}}	^1.0.0 (current major as of this plugin's release)
{{DEPLOY_NOTE}}	Self-hosted in Docker. / Deployed to Vercel. / empty
{{DEPLOY_BLOCK}}	Short paragraph describing the deploy setup matching the choice
{{TODAY_ISO_DATE}}	YYYY-MM-DD
{{AUTH_STATE_LINE}}	E.g. Better Auth wired. Credentials login at /login. or Auth skipped — run /nfs-add-auth to add.
{{MCP_STATE_LINE}}	E.g. MCP route at /mcp with one example tool. or MCP skipped.
{{CACHE_STATE_LINE}}	E.g. Using Next.js default cache. or Redis wired via src/server/lib/cache.ts.

Key templates and references

The work is data-driven from the answers + these files:

• references/stack-rationale.md — explains why this stack (read if user asks "why not X").
• references/folder-structure.md — the canonical layout, expanded with comments.
• references/claude-md-template.md — the CLAUDE.md template with variable slots.
• references/env-example-template.md — the .env.example template, keyed by which optional features were enabled.
• assets/*.template — actual file bodies to drop in, with {{VARIABLE}} slots.

When writing a file, read the corresponding template, substitute variables, then write. Don't generate from scratch — the templates carry hard-won decisions.

Post-scaffold

After the scaffold lands, point the user at the next moves:

• pnpm dev to start the dev server.
• Edit prisma/schema.prisma to add their first real model.
• pnpm prisma migrate dev --name init to apply.
• Replace _example with their first real business module — copy the shape verbatim.
• /nfs-add-cache, /nfs-add-mcp, /nfs-add-auth to retrofit later.
• See docs/architecture.md in the project for ongoing patterns.

Sanity guards

• Never overwrite an existing file without explicit confirmation. Always ls the target directory first.
• Never run pnpm install in the user's current directory if the project location is "new subdirectory" — cd into the new dir first.
• Never push to a remote automatically. The user owns that.
• Never invent dependencies — every dep in package.json.template exists and is on a real version.
• Never skip the CLAUDE.md step — it's the most load-bearing file in the project's future, since every future Claude session reads it first.
• Never wire Server Actions without revalidatePath or updateTag — the cache won't refresh and the user will think the action did nothing. The example action template demonstrates the right pattern; preserve it.