@nakedev/nextjs-fsd 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nakedev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @nakedev/nextjs-fsd
+
+Keep a Next.js App Router project on [Feature-Sliced Design](https://feature-sliced.design/).
+
+Next.js already creates the app, so this CLI does not. It shapes what is
+inside one: `init` once, then `generate` for slices and `add` for the two
+pieces of wiring every project rewrites by hand — API error handling and auth.
+
+Sibling to [`go-scaffold`](https://github.com/NakePranob/go-scaffold), which
+generates the Go backend these templates are written against.
+
+```bash
+bunx create-next-app@latest my-app --ts --app --tailwind
+cd my-app
+
+bunx @nakedev/nextjs-fsd init
+bunx @nakedev/nextjs-fsd add auth
+bunx @nakedev/nextjs-fsd generate page dashboard --auth
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `nextjs-fsd` | menu — asks what to do, then delegates |
+| `init` | FSD layers in `src/`, the `@/*` alias, steiger + its config, `docs/fsd.md` |
+| `generate page [name]` | a `_pages` slice plus the thin `app/<route>/page.tsx` that re-exports it |
+| `generate slice [layer] [name]` | a `features`/`entities`/`widgets` slice with only the segments it needs |
+| `generate layout [name]` | a shared route shell in `_app/layouts` plus the `layout.tsx` that re-exports it |
+| `add error-handling` | `shared/api` — `ApiError`, per-domain error catalogs, axios client, `QueryClient` |
+| `add auth` | `shared/auth` — in-memory access token, session hooks, route guard, login page |
+| `config show` | the resolved config and which features are installed |
+| `config set locale <th\|en>` | the language future generated copy is written in |
+
+Every command asks for what you leave out. `--defaults` answers every
+question, for CI.
+
+**Nothing is ever overwritten.** Re-running a generate command on something
+that exists *extends* it — `--segments ui,model` on a ui-only slice writes
+`model/` and appends its exports to `index.ts`, leaving every existing file
+alone. If there is nothing new to add, it says so rather than writing. Adding
+a segment later is the normal path, which is the whole point of "a slice gets
+only the segments it has code for".
+
+It also will not add a second route file for a page that is already routed
+from somewhere else — two `page.tsx` resolving to the same URL is a Next.js
+build error, and a page generated with `--route "(admin)/dashboard"` is not
+where the default would look.
+
+## What `init` does to an existing project
+
+- moves `app/globals.css` to `src/_app/styles/globals.css` and names the
+  `@source` trees Tailwind now has to scan, then repoints the import in
+  `layout.tsx`
+- puts `./src/*` first in the tsconfig `@/*` alias, keeping whatever was there
+  as a fallback so existing `@/…` imports keep resolving
+- writes `eslint.fsd.mjs` and spreads it into `eslint.config.mjs`, so a
+  wrong-way or slice-internal import is flagged per file in the editor — the
+  core `no-restricted-imports` rule, no new dependency
+- adds `steiger` and `steiger.config.ts` (with the `_app`/`_pages` layer-name
+  rule turned off) and chains both into the `lint` script
+- writes `components.json` so `shadcn add <name>` lands in `src/shared/ui`
+  and its `utils.ts` in `src/shared/lib` — `shadcn init`'s own defaults put
+  them in `./components/ui` and the project root, outside the layers entirely
+- writes `docs/fsd.md`, a `.claude/skills/nextjs-fsd/SKILL.md` skill, and
+  appends a section to `AGENTS.md` pointing at both — so an agent asked to "add
+  a settings screen" reaches for the generator instead of hand-writing the
+  files the linters then report
+
+It creates no empty layer directories — `features/` and `entities/` appear
+when a slice actually needs them, which is the FSD advice, not a shortcut.
+
+## Two linters, on purpose
+
+ESLint and steiger overlap on paper and not in practice:
+
+| | catches | when |
+|---|---|---|
+| ESLint | this import points the wrong way, or reaches past a slice's `index.ts` | as you type, per file |
+| steiger | a slice with no references, a layer sliced too finely, a segment named after its type | on demand, whole tree |
+
+A bad import is visible in one file, so that check belongs where it is
+instant. Nothing in one file shows that a slice has no consumers — that needs
+the whole tree. `init` sets up both and chains them into `lint`.
+
+The generated ESLint block has one trap worth knowing if you edit it: flat
+config **replaces** a rule's options when a later block matches the same file
+rather than merging them, so all of a layer's `no-restricted-imports` patterns
+have to stay in that layer's single block. A test pins this down, because a
+split config still reads as though both halves applied.
+
+## The two `add` targets
+
+`add error-handling` is the pattern rather than a library: one `ApiError` at
+the boundary, an axios client whose 401 refresh is **single-flight** (a
+backend that rotates refresh tokens logs the user out mid-session otherwise),
+and error copy that lives in a per-domain catalog instead of one global map.
+`error.message` is never rendered — a backend message is written for a log,
+and an unmapped code falls through to a fallback that names the action that
+failed.
+
+Give each domain its own catalog with `--errors` on either generate command.
+
+`add auth` needs that client, so it installs it first if it is missing. It
+scaffolds password login only: access token in a module variable (never
+`localStorage`), refresh token left to the API's httpOnly cookie,
+`useRequireSession` as UX with the real gate still on the server. MFA, OAuth
+providers and RBAC are not scaffolded.
+
+Both assume the shape `go-scaffold` produces — `POST /auth/login`,
+`POST /auth/refresh`, `GET /users/me`, and an `{ error: { code, message } }`
+envelope. Adjust the paths and the `Session` type if yours differ; they are
+one file each.
+
+## Generated copy
+
+`init` asks whether the user-facing strings should be Thai or English
+(`--locale th|en`, Thai by default) and records it. It only decides what the
+first draft reads like — the catalogs are meant to be edited, and
+`config set locale` changes the setting for future generation without
+rewriting anything already on disk.
+
+For a Thai project, `generate page` also asks for the page title, because the
+Title Case of a kebab name is the right answer in English and the wrong one in
+Thai. `--title` skips the question.
+
+Thai copy also needs a Thai face: `init` warns that create-next-app leaves
+`font-family: Arial, Helvetica, sans-serif` on `body`, which has no Thai
+coverage at all, and names the `next/font` fix. It does not rewrite your font
+stack — that choice is yours.
+
+## Requirements
+
+Node 20.9+, a Next.js 15/16 App Router project in TypeScript. Both
+create-next-app layouts work as-is (`app/` and `src/app/`) — FSD's own app
+layer is `src/_app`, so it never collides with either.
+
+The generated `client.test.ts` is written only for bun projects: `bun test`
+resolves the `@/` alias with no config, while node and vitest need a runner
+set up first, which is not this CLI's business.
+
+## Development
+
+```bash
+pnpm install
+pnpm run verify            # build + unit tests + smoke test — fast, offline
+pnpm run test:integration  # real create-next-app + install + next build — slow, networked
+```
+
+`scripts/smoke-test.mjs` drives the actual binary through
+init → add → generate → extend against three fixtures (root `app/`, `src/app/`,
+and a bun-shaped one), checks what came out, asserts no `{{…}}` template
+syntax leaked, and **type-checks the generated project** by symlinking this
+repo's `node_modules` into the fixture. That last step is why `next` and
+`react` are devDependencies here; they are never shipped.
+
+`scripts/integration-test.mjs` is the layer that catches what the smoke test
+structurally cannot — a dependency range that does not resolve (the fixture
+borrows packages it never installed) and Next.js behaviour drift. It costs
+minutes and a network, so it runs on demand and in CI.
+
+The unit tests in `tests/` cover the file patchers in isolation, where the
+fiddly cases live.
+
+MIT.

package/bin/nextjs-fsd.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/index.js");

package/dist/commands/add.js

@@ -0,0 +1,182 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addErrorHandling = addErrorHandling;
+exports.addAuth = addAuth;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const prompts_1 = require("../prompts");
+const config_1 = require("../utils/config");
+const copy_1 = require("../utils/copy");
+const render_1 = require("../utils/render");
+const project_1 = require("../utils/project");
+const init_1 = require("./init");
+const API_DEPS = {
+    "@tanstack/react-query": "^5.101.4",
+    axios: "^1.19.0",
+};
+// confirmAdd prints what an add is about to do and asks before it happens: it
+// writes a dozen files and patches the root layout, and there is no `undo` to
+// walk that back. Defaults to yes here (unlike a delete) because getting to
+// this prompt already required typing the command.
+async function confirmAdd(lines, opts) {
+    if (opts.yes)
+        return;
+    console.log(picocolors_1.default.bold("\nThis will:"));
+    for (const line of lines)
+        console.log(`  ${picocolors_1.default.dim("•")} ${line}`);
+    console.log();
+    if (!(await (0, prompts_1.confirm)({ message: "Proceed?", default: true }))) {
+        throw new Error("cancelled — nothing was written");
+    }
+}
+/** Returns the dependencies added to package.json, so a caller that chains
+ *  another add can install once at the end instead of twice. */
+async function addErrorHandling(opts) {
+    const projectDir = process.cwd();
+    const config = (0, config_1.readConfig)(projectDir);
+    if (config.features.errorHandling) {
+        throw new Error(`error handling is already installed (${config.srcDir}/shared/api/client.ts exists) — edit the catalogs there, or delete the directory to reinstall`);
+    }
+    const providersFile = `${config.srcDir}/_app/providers/index.tsx`;
+    const ownsProviders = !fs_extra_1.default.existsSync(path_1.default.join(projectDir, providersFile));
+    await confirmAdd([
+        `add ${picocolors_1.default.cyan(`${config.srcDir}/shared/api/`)} — ApiError, the error catalog + resolver, an axios client with a single-flight 401 refresh, and a QueryClient`,
+        `add ${picocolors_1.default.cyan(`${config.srcDir}/shared/ui/form-error.tsx`)} and ${picocolors_1.default.cyan(`${config.srcDir}/shared/config/env.ts`)}`,
+        `add ${picocolors_1.default.cyan(`${config.srcDir}/shared/auth/access-token.ts`)} — the in-memory token the request interceptor reads (\`add auth\` fills in the rest)`,
+        ownsProviders
+            ? `add ${picocolors_1.default.cyan(providersFile)} and wrap ${config.appDir}/layout.tsx in <Providers>`
+            : picocolors_1.default.yellow(`leave your existing ${providersFile} alone — you add <QueryClientProvider> to it yourself`),
+        `add ${Object.keys(API_DEPS).join(" + ")} to package.json`,
+    ], opts);
+    // The refresh rules are the part that fails silently in a browser, so they
+    // get the one test — but only where it runs with no extra setup. `bun test`
+    // resolves the tsconfig alias on its own; node:test and vitest both need
+    // config this CLI has no business writing into someone's project.
+    const writesTest = config.packageManager === "bun";
+    const context = errorContext(config);
+    const entries = [
+        { template: "add/errors/api-error.ts.hbs", output: `${config.srcDir}/shared/api/api-error.ts` },
+        { template: "add/errors/error-catalog.ts.hbs", output: `${config.srcDir}/shared/api/error-catalog.ts` },
+        { template: "add/errors/error-resolver.ts.hbs", output: `${config.srcDir}/shared/api/error-resolver.ts` },
+        { template: "add/errors/client.ts.hbs", output: `${config.srcDir}/shared/api/client.ts` },
+        { template: "add/errors/query-client.ts.hbs", output: `${config.srcDir}/shared/api/query-client.ts` },
+        { template: "add/errors/index.ts.hbs", output: `${config.srcDir}/shared/api/index.ts` },
+        { template: "add/errors/access-token.ts.hbs", output: `${config.srcDir}/shared/auth/access-token.ts` },
+        { template: "add/errors/env.ts.hbs", output: `${config.srcDir}/shared/config/env.ts` },
+        { template: "add/errors/config-index.ts.hbs", output: `${config.srcDir}/shared/config/index.ts` },
+        { template: "add/errors/form-error.tsx.hbs", output: `${config.srcDir}/shared/ui/form-error.tsx` },
+        { template: "add/errors/providers.tsx.hbs", output: providersFile, when: () => ownsProviders },
+        {
+            template: "add/errors/client.test.ts.hbs",
+            output: `${config.srcDir}/shared/api/client.test.ts`,
+            when: () => writesTest,
+        },
+    ];
+    const written = await (0, render_1.applyTemplates)(projectDir, entries, context);
+    if ((0, project_1.appendExport)(projectDir, `${config.srcDir}/shared/ui/index.ts`, 'export { FormError } from "./form-error";')) {
+        written.push(`${config.srcDir}/shared/ui/index.ts`);
+    }
+    if ((0, project_1.appendEnvExample)(projectDir, "NEXT_PUBLIC_API_URL", "# Base URL of the API, including whatever prefix it mounts its routes under.\n" +
+        "# Whatever origin this app runs on must also be allowed by the API's CORS\n" +
+        "# config, or the browser drops the refresh cookie.\n" +
+        "NEXT_PUBLIC_API_URL=http://localhost:8080/api\n")) {
+        written.push(".env.example");
+    }
+    const layoutPatch = ownsProviders ? (0, project_1.patchLayoutProviders)(projectDir, config.appDir, config.alias) : "already";
+    if (layoutPatch === "patched")
+        written.push(`${config.appDir}/layout.tsx (<Providers>)`);
+    const added = (0, project_1.addDependencies)(projectDir, API_DEPS);
+    if (writesTest) {
+        // next build type-checks every file under the project, the generated test
+        // included — without these types `bun:test` is an unresolved module and
+        // the production build fails on a file that only ever runs in bun.
+        added.push(...(0, project_1.addDependencies)(projectDir, { "@types/bun": "^1.3.14" }, "devDependencies"));
+        if ((0, project_1.appendScript)(projectDir, "test", "bun test"))
+            written.push("package.json (test script)");
+    }
+    (0, config_1.setFeature)(projectDir, "errorHandling", true);
+    (0, init_1.report)(written, added);
+    if (!ownsProviders) {
+        console.log(picocolors_1.default.yellow(`\n${providersFile} already exists — wrap its children yourself:`) +
+            `\n  import { QueryClientProvider } from "@tanstack/react-query";` +
+            `\n  import { makeQueryClient } from "${config.alias}/shared/api";` +
+            `\n  const [queryClient] = useState(makeQueryClient);   // not a module constant` +
+            `\n  <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>`);
+    }
+    else if (layoutPatch === "manual") {
+        console.log(picocolors_1.default.yellow(`\ncould not find {children} in ${config.appDir}/layout.tsx — wrap it in <Providers> by hand:`) +
+            `\n  import { Providers } from "${config.alias}/_app/providers";`);
+    }
+    if (!writesTest) {
+        console.log(picocolors_1.default.dim(`\nno client.test.ts written: \`bun test\` resolves the ${config.alias}/ alias with no config, ` +
+            `${config.packageManager} needs a runner set up first. The single-flight refresh is the part worth pinning down when you add one.`));
+    }
+    finish(projectDir, config, added, opts);
+    console.log(`\n${picocolors_1.default.bold("Next:")} render a failure with ${picocolors_1.default.cyan("<FormError error={mutation.error} />")}, ` +
+        `and give each domain its own catalog with ${picocolors_1.default.cyan("nextjs-fsd generate page <name> --errors")}`);
+    return added;
+}
+async function addAuth(opts) {
+    const projectDir = process.cwd();
+    let config = (0, config_1.readConfig)(projectDir);
+    if (config.features.auth) {
+        throw new Error(`auth is already installed (${config.srcDir}/shared/auth/session.ts exists) — edit it there, or delete the directory to reinstall`);
+    }
+    // Not an error like `add rbac`'s "run add auth first": auth cannot work
+    // without the client at all — every hook below goes through it — so there is
+    // no choice to offer, only a step to take first.
+    let added = [];
+    if (!config.features.errorHandling) {
+        console.log(picocolors_1.default.dim("auth needs the API client, which `add error-handling` installs — doing that first.\n"));
+        // install: false so the two adds share one install run at the end.
+        added = await addErrorHandling({ ...opts, install: false });
+        config = (0, config_1.readConfig)(projectDir);
+        console.log();
+    }
+    await confirmAdd([
+        `add ${picocolors_1.default.cyan(`${config.srcDir}/shared/auth/`)} — session hooks (useSession/useLogin/useLogout), useRequireSession, and an auth error catalog`,
+        `add ${picocolors_1.default.cyan(`${config.srcDir}/_pages/login/`)} and ${picocolors_1.default.cyan(`${config.appDir}/login/page.tsx`)}`,
+        picocolors_1.default.yellow("assumes the API answers POST /auth/login with an access token, keeps the refresh token in an httpOnly cookie, and serves GET /users/me — adjust the paths and the Session type if yours differ"),
+        picocolors_1.default.dim("password login only: MFA, OAuth providers and RBAC are not scaffolded"),
+    ], opts);
+    const context = errorContext(config);
+    const auth = `${config.srcDir}/shared/auth`;
+    const slice = `${config.srcDir}/_pages/login`;
+    const written = await (0, render_1.applyTemplates)(projectDir, [
+        { template: "add/auth/session.ts.hbs", output: `${auth}/session.ts` },
+        { template: "add/auth/require-session.ts.hbs", output: `${auth}/require-session.ts` },
+        { template: "add/auth/auth-errors.ts.hbs", output: `${auth}/auth-errors.ts` },
+        { template: "add/auth/index.ts.hbs", output: `${auth}/index.ts` },
+        { template: "add/auth/login-index.ts.hbs", output: `${slice}/index.ts` },
+        { template: "add/auth/login-page.tsx.hbs", output: `${slice}/ui/login-page.tsx` },
+        { template: "add/auth/login-form.tsx.hbs", output: `${slice}/ui/login-form.tsx` },
+        { template: "generate/page/route.tsx.hbs", output: path_1.default.posix.join(config.appDir, "login", "page.tsx") },
+    ], { ...context, name: "login", pascal: "Login" });
+    (0, config_1.setFeature)(projectDir, "auth", true);
+    (0, init_1.report)(written);
+    finish(projectDir, config, added, opts);
+    console.log(`\n${picocolors_1.default.bold("Next:")} put a page behind the session guard with ` +
+        picocolors_1.default.cyan("nextjs-fsd generate page dashboard --auth"));
+}
+function errorContext(config) {
+    const copy = (0, copy_1.copyFor)(config.locale);
+    return {
+        ...config,
+        copy,
+        commonCatalogEntries: (0, copy_1.asCatalogEntries)(copy.common),
+        authCatalogEntries: (0, copy_1.asCatalogEntries)(copy.auth),
+    };
+}
+function finish(projectDir, config, added, opts) {
+    if (added.length === 0)
+        return;
+    if (opts.install === false) {
+        console.log(picocolors_1.default.yellow(`\nrun \`${config.packageManager} install\` to install: ${added.join(", ")}`));
+        return;
+    }
+    (0, project_1.installDependencies)(projectDir, config.packageManager);
+}

package/dist/commands/config.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.showProjectConfig = showProjectConfig;
+exports.setProjectLocale = setProjectLocale;
+const picocolors_1 = __importDefault(require("picocolors"));
+const config_1 = require("../utils/config");
+const copy_1 = require("../utils/copy");
+const version_1 = require("../utils/version");
+function showProjectConfig() {
+    const config = (0, config_1.readConfig)(process.cwd());
+    const rows = [
+        ["FSD layers", `${config.srcDir}/ (_app, _pages, features, entities, shared)`],
+        ["App Router", `${config.appDir}/`],
+        ["import alias", `${config.alias}/* -> ./${config.srcDir}/*`],
+        ["copy language", config.locale],
+        ["package manager", config.packageManager],
+        ["error handling", config.features.errorHandling ? picocolors_1.default.green("installed") : picocolors_1.default.dim("not installed")],
+        ["auth", config.features.auth ? picocolors_1.default.green("installed") : picocolors_1.default.dim("not installed")],
+    ];
+    console.log();
+    for (const [label, value] of rows)
+        console.log(`  ${label.padEnd(16)} ${value}`);
+    const stamped = config.scaffoldVersion;
+    const current = (0, version_1.cliVersion)();
+    if (stamped && stamped !== current) {
+        console.log(picocolors_1.default.dim(`\n  scaffolded with nextjs-fsd ${stamped}, running ${current} — templates may have moved on since.`));
+    }
+    console.log();
+}
+/**
+ * Changes the language future generated copy is written in.
+ *
+ * Future only, and deliberately so: the catalogs and page titles already on
+ * disk are meant to be edited, and rewriting them would throw away the wording
+ * someone chose. The setting decides what the next draft reads like, nothing
+ * more.
+ */
+function setProjectLocale(value) {
+    const locale = (0, copy_1.parseLocale)(value);
+    if (locale === undefined)
+        throw new Error('`config set locale` needs a value — "th" or "en"');
+    const config = (0, config_1.readConfig)(process.cwd());
+    if (config.locale === locale) {
+        console.log(picocolors_1.default.dim(`\nalready ${locale} — nothing to change.\n`));
+        return;
+    }
+    (0, config_1.writeConfig)(process.cwd(), { ...config, locale });
+    console.log(`\n  ${picocolors_1.default.green("~")} nextjs-fsd.config.json: locale ${picocolors_1.default.dim(config.locale)} -> ${picocolors_1.default.green(locale)}\n` +
+        picocolors_1.default.dim("  Applies to what gets generated from now on. Catalogs and titles already written are left as they are.\n"));
+}