# Nfs Scaffold App

> Scaffold a brand-new fullstack back-office app on pure Next.js (App Router) — Server Components for reads, Server Actions for writes, services in src/server/modules/. Use this whenever the user wants to start a new internal tool, admin dashboard, back-office app, line-of-business system, lightweight ERP, or CRUD app on Next.js without a separate API service — even if they don't name the stack. Walks the user through an interactive Q&A (project name, location, database, auth, cache, MCP, deployment target), then generates the canonical folder structure, dependencies, sample Server Action, sample service, Prisma schema starter, .env.example, and CLAUDE.md. Always trigger when the user wants a Next.js fullstack starter without tRPC, when they describe building a back office with Server Components, or when they say 'one Next.js app does everything'.

- Skill: `juncoding/nfs-scaffold-app` (Agent Skill, multi-file: 44 files)
- Install (CLI): `npx skillmds@latest add juncoding/nfs-scaffold-app`
- Raw SKILL.md: https://api.skillmd.com/api/skills/juncoding/nfs-scaffold-app/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: juncoding (https://skillmd.com/u/juncoding)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/juncoding/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.