@nakedev/nextjs-fsd 0.1.0

package/templates/init/eslint.fsd.mjs.hbs

@@ -0,0 +1,91 @@
+// The FSD import boundary, as ESLint sees it: one file at a time, in your
+// editor, on every save.
+//
+// Not a replacement for `steiger ./{{srcDir}}` and not redundant with it — the
+// two answer different questions at different moments. A single file can show
+// that this import points the wrong way; only a whole-tree pass can show that
+// a slice has no references at all, that a layer is sliced too finely, or that
+// a segment is named after its type instead of its purpose. ESLint catches the
+// mistake as you type it; steiger catches the shape the codebase drifted into.
+//
+// Zero new dependencies: `no-restricted-imports` is a core rule, and the layer
+// order is the whole of the boundary. Imports point downwards only —
+// _app -> _pages -> widgets -> features -> entities -> shared — and a slice is
+// always entered through its index.ts.
+
+const LAYERS = ["_app", "_pages", "widgets", "features", "entities", "shared"];
+
+// Layers divided into slices. `_app` and `shared` hold segments instead, so
+// they have no sibling slices to keep apart and no index.ts to enter through.
+const SLICED = ["_pages", "widgets", "features", "entities"];
+
+/**
+ * Anything below a slice's own directory, from anywhere.
+ *
+ * One segment past the layer is the slice itself, which is exactly what
+ * another layer should import; two or more is its insides, which nothing
+ * should. That includes a file reaching into its OWN slice through the alias —
+ * inside a slice the import is relative, which is what keeps a slice movable.
+ */
+const insideSlice = {
+  group: SLICED.map((layer) => `{{alias}}/${layer}/*/**`),
+  message: 'reaches inside a slice — import it through its index.ts, e.g. "{{alias}}/features/<slice>".',
+};
+
+/**
+ * One `no-restricted-imports` entry per group of files, never two.
+ *
+ * Flat config REPLACES a rule's options when a later block matches the same
+ * file; it does not merge them. So every pattern that applies to a layer has
+ * to live in that layer's single block — splitting them across blocks silently
+ * disables all but the last one to match, and the config still looks right.
+ */
+function boundaryFor(files, patterns) {
+  return {
+    files,
+    rules: { "no-restricted-imports": ["error", { patterns: [...patterns, insideSlice] }] },
+  };
+}
+
+const layerRules = LAYERS.map((layer) => {
+  const patterns = [];
+
+  const higher = LAYERS.slice(0, LAYERS.indexOf(layer));
+  if (higher.length > 0) {
+    patterns.push({
+      group: higher.map((name) => `{{alias}}/${name}/**`),
+      message:
+        `imports point downwards only, and this is a higher layer than ${layer}. ` +
+        "Move the shared code down a layer instead of reaching up.",
+    });
+  }
+
+  if (SLICED.includes(layer)) {
+    patterns.push({
+      group: [`{{alias}}/${layer}/*`],
+      message:
+        "two slices on the same layer never import each other. Move the shared code down a layer, " +
+        "or use a relative path if it really belongs to this slice.",
+    });
+  }
+
+  return boundaryFor([`{{srcDir}}/${layer}/**/*.{ts,tsx}`], patterns);
+});
+
+const fsdBoundary = [
+  ...layerRules,
+  // {{appDir}}/ is routing. A route file re-exports a page and its metadata;
+  // composing features straight into a route is how the routing layer starts
+  // growing logic that belongs in a slice.
+  boundaryFor(
+    ["{{appDir}}/**/*.{ts,tsx}"],
+    [
+      {
+        group: ["{{alias}}/widgets/**", "{{alias}}/features/**", "{{alias}}/entities/**"],
+        message: "{{appDir}}/ composes pages, not features — put it in a _pages slice and re-export that.",
+      },
+    ]
+  ),
+];
+
+export default fsdBoundary;

package/templates/init/fsd.md.hbs

@@ -0,0 +1,133 @@
+# Feature-Sliced Design in this project
+
+> Generated by `nextjs-fsd init`. Edit freely — this file is the convention,
+> not a lock file. Keep it in step with the code; a doc describing the
+> previous shape is worse than no doc.
+
+## Layout
+
+```text
+{{appDir}}/                        # Next.js App Router — routing only
+├── layout.tsx               # composition root: fonts, <Providers>, global CSS
+└── <route>/page.tsx         # re-exports an FSD page + its metadata, nothing else
+{{srcDir}}/
+├── _app/                    # FSD app layer — providers/, styles/
+├── _pages/<page>/           # one slice per route: ui/, index.ts (public API)
+├── features/<slice>/        # a whole user action, once two pages need it
+├── entities/<slice>/        # a business object, once two features need it
+└── shared/                  # infrastructure only — api/, auth/, config/, lib/, ui/
+```
+
+The FSD `app` and `pages` layers are named `_app` and `_pages` because
+Next.js owns those names at the root.
+
+**Add layers when a second consumer actually appears, not up front.**
+Duplicating a component across two pages is cheaper to undo than an
+`entities/` layer built for a reuse that never happens. FSD v2.1 discourages
+`widgets/` — UI blocks carry user-flow logic, which makes the
+widget/feature boundary arbitrary — so reach for `features/` first.
+
+## Import boundary
+
+Imports point downwards only: `_app → _pages → widgets → features → entities
+→ shared`. Two slices on the same layer never import each other, and a slice
+is always imported through its `index.ts`:
+
+```tsx
+import { LoginForm } from "{{alias}}/_pages/login";             // ✅ public API
+import { LoginForm } from "{{alias}}/_pages/login/ui/login-form"; // ❌ reaches inside
+```
+
+If two pages need the same thing, that is the signal it was never
+page-scoped: move it down a layer instead of importing sideways. Two copies
+in two pages while you are still unsure is the cheaper mistake.
+
+## Two linters, on purpose
+
+`{{lintCommand}}` runs both, and they are not redundant:
+
+| | catches | when |
+|---|---|---|
+| **ESLint** (`eslint.fsd.mjs`) | this import points the wrong way, or reaches past a slice's `index.ts` | as you type, per file, in the editor |
+| **steiger** (`steiger.config.ts`) | a slice with no references, a layer sliced too finely, a segment named after its type, inconsistent naming | on demand, whole tree |
+
+A single file is enough to see a bad import, so that check belongs where you
+get it instantly. Nothing in one file can show that a slice has no consumers
+or that a layer has thirty slices — that needs the whole tree, which is what
+steiger walks.
+
+`eslint.fsd.mjs` has no dependencies of its own: the boundary is expressed
+with the core `no-restricted-imports` rule, and the layer order above is the
+whole of it. One gotcha if you edit it — flat config **replaces** a rule's
+options when a later block matches the same file instead of merging them, so
+every pattern for a layer has to stay in that layer's single block. Split them
+across two blocks and the earlier one silently stops applying.
+
+When steiger says *"this slice has only one reference — consider merging
+them"*, that is the "add layers when a second consumer appears" rule talking,
+not a false positive. It is configured as a **warning** rather than an error,
+because every slice has one consumer on the day it is created and failing the
+build for that teaches people to delete the rule instead of the slice. Read it
+anyway: a slice that stays at one consumer for good probably belongs inside
+that consumer.
+
+## `{{appDir}}/` stays thin
+
+A route file re-exports an FSD page and nothing else:
+
+```tsx
+// {{appDir}}/login/page.tsx
+export { LoginPage as default, metadata } from "{{alias}}/_pages/login";
+```
+
+Export `metadata` alongside the component — a route file that only
+re-exports `default` silently drops the page's title.
+
+## Segments
+
+A slice gets only the segments it has code for. `ui/` alone is the common
+case; add `model/` (state, hooks), `api/` (requests) or `lib/` (helpers) when
+that slice actually has them. An empty segment folder is noise.
+
+Adding one later is the normal path, not a rewrite — re-run the same command
+with the extra segment and it writes only what is missing, appending the new
+exports to the slice's `index.ts` and leaving every existing file untouched:
+
+```bash
+nextjs-fsd generate slice features checkout --segments ui        # ui/ only
+nextjs-fsd generate slice features checkout --segments ui,model  # adds model/
+```
+
+```text
+{{srcDir}}/_pages/<page>/
+├── ui/<page>-page.tsx  # server component + `metadata`
+├── ui/<thing>.tsx      # "use client" only on the leaves that need it
+└── index.ts            # public API — the only thing {{appDir}}/ imports
+```
+
+## Server vs. client components
+
+Default to a Server Component. `"use client"` goes on the leaf that needs
+`useState`/`useEffect`/events — a page component stays a server component
+while its form does not.
+
+## Generating
+
+```bash
+nextjs-fsd generate page <name>            # slice + {{appDir}}/<name>/page.tsx
+nextjs-fsd generate slice features <name>  # a feature slice
+nextjs-fsd generate layout admin           # _app/layouts + {{appDir}}/(admin)/layout.tsx
+nextjs-fsd add error-handling              # shared/api: ApiError, catalogs, client
+nextjs-fsd add auth                        # shared/auth: session, guard, login page
+```
+
+Re-running a generate command extends what is there instead of refusing, so
+`--errors` or `--client` on a page built bare earlier just adds the file. It
+never rewrites one you already have — and it will not add a second route file
+for a page that is already routed from somewhere else, because two `page.tsx`
+resolving to the same URL is a Next.js build error.
+
+Layouts live in `_app/layouts`, not `_pages`: a layout is not one route's
+content, it is what several routes have in common, and `{{appDir}}/(group)/layout.tsx`
+re-exports it the same way a route file re-exports a page. `shadcn add <name>`
+writes into `{{srcDir}}/shared/ui` — `components.json` is already aimed there.

package/templates/init/globals.css.hbs

@@ -0,0 +1,31 @@
+@import "tailwindcss";
+
+/* This file lives in the FSD app layer, not next to the routes, so name the
+   trees Tailwind has to scan for class names explicitly instead of relying on
+   where auto-detection decides the project root is. */
+@source "{{cssSourceApp}}";
+@source "{{cssSourceSrc}}";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+}
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+  }
+}

package/templates/init/skill.md.hbs

@@ -0,0 +1,167 @@
+---
+name: nextjs-fsd
+description: >
+  Use whenever the user asks to add, create, scaffold, or wire up a new page,
+  screen, route, feature, entity, layout, or shared route shell in THIS
+  project — including indirect requests such as "add a settings screen", "let
+  staff approve loans", "put the dashboard behind login", or "show a proper
+  message when the API fails". This project is organized with Feature-Sliced
+  Design and has a nextjs-fsd.config.json at its root; check for that file
+  before assuming this applies. Also use when adding API error handling or
+  authentication for the first time. Do NOT use for business logic or markup
+  inside a file the CLI already generated, for styling, for a bug fix or
+  refactor, or for a project without nextjs-fsd.config.json.
+---
+
+# nextjs-fsd
+
+Use this skill for the FSD surface only: which directory a new thing goes in,
+and how it is imported. Once a slice exists, its content — markup, business
+rules, request shapes — is the engineer's work.
+
+Create slices with the CLI rather than by hand, so the route file, the
+`index.ts` public API, the `"use client"` placement, and the segment layout
+stay consistent. Hand-written slices are exactly what the two linters then
+report.
+
+This file is emitted at `.claude/skills/nextjs-fsd/SKILL.md`. Agents that do
+not load `.claude/skills` should follow the root `AGENTS.md`, which points at
+[docs/fsd.md](../../../docs/fsd.md) — the fuller convention, and the source of
+truth if this file and it ever disagree.
+
+**FSD methodology questions are not this skill's job.** Whether a thing should
+be an entity at all, when to extract from a page, cross-import and `@x`
+patterns, how strict to be — that is the `feature-sliced-design` skill
+(fsd.how). This one only covers driving the generator in this repo.
+
+## When to use this skill
+
+- A new page, screen or route is requested, even without the word "page".
+- A new reusable feature or business object is requested, even without the
+  words "feature" or "entity".
+- Several routes need shared chrome (a sidebar, an auth card) → a layout.
+- The project needs API error handling or auth for the first time.
+- An existing slice needs a segment it does not have yet (state, requests,
+  helpers, an error catalog).
+
+Examples that all use this skill:
+
+- "add a settings screen" → `generate page settings`
+- "the dashboard should require login" → `generate page dashboard --auth`
+- "admin pages need a shared sidebar" → `generate layout admin`
+- "loans need to be reusable across screens" → `generate slice entities loan`
+- "show a real message when saving fails" → `add error-handling`, then
+  `--errors` on the slice that owns the failing call
+
+## When not to use it
+
+- Writing the actual markup, state, or request body inside a generated file
+- Styling, Tailwind theme edits, or shadcn component customisation
+- Bug fixes, refactors, or dependency work
+- Deciding whether a layer *should* exist — that is the FSD skill
+- Any repository without nextjs-fsd.config.json at its root
+
+## Before running the CLI
+
+1. Read `nextjs-fsd.config.json`. `features.errorHandling` and `features.auth`
+   decide which flags are even legal, `appDir` says whether routes live in
+   `app/` or `src/app/`, and `locale` says which language generated copy is
+   written in.
+2. Look for the slice first. `{{srcDir}}/_pages/`, `{{srcDir}}/features/`,
+   `{{srcDir}}/entities/` — a name that already exists means you are extending,
+   not creating, and the flags differ.
+3. Check `{{appDir}}/` for an existing route before choosing `--route`. A page
+   routed from a group is not where the default would look.
+4. Confirm the work is on a branch you may commit to (`git status -sb`) and
+   preserve unrelated changes.
+
+## Commands
+
+Run from the project root. **Pass every value as a flag** — an omitted value
+opens a prompt, and in a non-interactive shell that exits 1 without writing
+anything.
+
+~~~bash
+nextjs-fsd generate page <name> [--route <path>] [--no-route] [--client] [--auth] [--errors] [--defaults]
+nextjs-fsd generate slice <features|entities|widgets> <name> [--segments ui,model,api,lib] [--errors] [--defaults]
+nextjs-fsd generate layout <name> [--route <path>] [--no-route] [--defaults]
+nextjs-fsd add error-handling [-y] [--no-install]
+nextjs-fsd add auth [-y] [--no-install]
+nextjs-fsd config show
+~~~
+
+`--defaults` answers every remaining question, so scripted and agent use needs
+`--defaults` (or the full set of flags) on every generate command.
+
+Feature gates, which fail loudly rather than generating something broken:
+
+- `--auth` requires `features.auth` → run `add auth` first
+- `--errors` and the `api` segment require `features.errorHandling` →
+  run `add error-handling` first
+- `add auth` installs error handling itself if it is missing; do not run both
+
+## Extending, not rewriting
+
+**Re-run the same command to add to something that exists.** Do not hand-write
+the file, and do not delete the slice to regenerate it.
+
+~~~bash
+nextjs-fsd generate slice features checkout --segments ui           # ui/ only
+nextjs-fsd generate slice features checkout --segments ui,model     # adds model/
+nextjs-fsd generate page dashboard --errors --defaults              # adds the catalog
+~~~
+
+Only the missing files are written; new exports are appended to the slice's
+`index.ts`; every existing file is left exactly as it is. If there is nothing
+to add, the command says so and writes nothing — that is the expected answer,
+not a failure to work around.
+
+Two consequences worth knowing:
+
+- The page component is an existing file, so a leaf added later is not rendered
+  by anything yet. The command prints the one import line to add; add it.
+- A page already routed from elsewhere does not get a second route file. Two
+  `page.tsx` resolving to one URL is a Next.js build error.
+
+## Contracts the generated code relies on
+
+Breaking one of these is silent — the build passes and the app is wrong.
+
+- **A route file re-exports the page *and* its `metadata`.** `export { X as
+  default } from "..."` alone drops the page title with no error.
+- **`"use client"` goes on the leaf, not the page.** A page component stays a
+  server component; state, effects and events live in a `ui/<thing>.tsx`.
+- **Imports point downwards, and a slice is entered through its `index.ts`.**
+  `{{alias}}/features/x`, never `{{alias}}/features/x/ui/x`. Inside a slice the
+  import is relative.
+- **Never render `error.message` as UI copy.** Add the code to the domain's own
+  catalog (`model/<name>-errors.ts`) and let the fallback name the action that
+  failed. A backend message is written for a log.
+- **One catalog per domain, never one global map.** `generate ... --errors`
+  creates it in the right place.
+- **The access token stays in the module variable** in
+  `{{srcDir}}/shared/auth/access-token.ts`. Never move it to `localStorage`, and
+  never remove the single-flight guard in `shared/api/client.ts` — a backend
+  that rotates refresh tokens logs the user out mid-session without it.
+- **`{{appDir}}/` composes pages, not features.** ESLint enforces this one.
+
+## Verification
+
+After generating and filling in a slice:
+
+~~~bash
+{{lintCommand}}      # eslint (per-file boundary) + steiger (whole-tree)
+{{packageManager}} run build
+~~~
+
+ESLint reports a wrong-way or slice-internal import at the file. steiger
+reports what one file cannot show. `fsd/insignificant-slice` on a brand-new
+slice means nothing imports it yet — either wire it up or inline it back into
+its single consumer; it is the linter working, not a false positive.
+
+Where the CLI wrote a `client.test.ts`, run the project's test command too. Do
+not delete that test to make a change pass: the single-flight 401 refresh and
+the no-refresh-on-`/auth/*` rule are the two things in this codebase that fail
+silently in a browser.
+
+Report the exact output, and say plainly which generated TODOs are still TODOs.

package/templates/init/steiger.config.ts.hbs

@@ -0,0 +1,28 @@
+import fsd from "@feature-sliced/steiger-plugin";
+import { defineConfig } from "steiger";
+
+export default defineConfig([
+  ...fsd.configs.recommended,
+  {
+    // `app/` and `pages/` are Next.js' own directory names, so the FSD layers
+    // take an `_` prefix. Scoped off, not global — a typo in a future layer
+    // name still gets flagged.
+    files: ["./{{srcDir}}/_app/**", "./{{srcDir}}/_pages/**"],
+    rules: { "fsd/typo-in-layer-name": "off" },
+  },
+  {
+    // The Next.js FSD convention names this segment `providers`.
+    files: ["./{{srcDir}}/_app/providers/**"],
+    rules: { "fsd/segments-by-purpose": "off" },
+  },
+  {
+    // A warning, not an error, because at default severity this fails `lint`
+    // on the structure FSD's own guidance calls the normal starting point: a
+    // slice extracted for its first consumer, before the second one exists.
+    // The message is still worth reading — a slice that stays at one consumer
+    // for good probably belongs inside it — but a fresh slice failing CI
+    // teaches people to delete the linter rather than the slice.
+    files: ["./{{srcDir}}/**"],
+    rules: { "fsd/insignificant-slice": "warn" },
+  },
+]);