@nakedev/nextjs-fsd 0.1.0

package/dist/utils/project.js

@@ -0,0 +1,288 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageJsonPath = packageJsonPath;
+exports.readPackageJson = readPackageJson;
+exports.detectPackageManager = detectPackageManager;
+exports.detectAppDir = detectAppDir;
+exports.addDependencies = addDependencies;
+exports.installDependencies = installDependencies;
+exports.runCommand = runCommand;
+exports.patchTsconfigPaths = patchTsconfigPaths;
+exports.appendScript = appendScript;
+exports.appendExport = appendExport;
+exports.appendEnvExample = appendEnvExample;
+exports.patchLayoutStyleImport = patchLayoutStyleImport;
+exports.patchLayoutProviders = patchLayoutProviders;
+exports.patchEslintConfig = patchEslintConfig;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const child_process_1 = require("child_process");
+const picocolors_1 = __importDefault(require("picocolors"));
+function packageJsonPath(projectDir) {
+    return path_1.default.join(projectDir, "package.json");
+}
+function readPackageJson(projectDir) {
+    const file = packageJsonPath(projectDir);
+    if (!fs_extra_1.default.existsSync(file)) {
+        throw new Error(`no package.json in ${projectDir} — run this inside a Next.js project`);
+    }
+    return fs_extra_1.default.readJsonSync(file);
+}
+// Lockfile, not the `packageManager` field: the field is often absent and the
+// lockfile is what actually decided which client installed node_modules.
+function detectPackageManager(projectDir) {
+    const lockfiles = [
+        ["bun.lock", "bun"],
+        ["bun.lockb", "bun"],
+        ["pnpm-lock.yaml", "pnpm"],
+        ["yarn.lock", "yarn"],
+        ["package-lock.json", "npm"],
+    ];
+    for (const [lockfile, manager] of lockfiles) {
+        if (fs_extra_1.default.existsSync(path_1.default.join(projectDir, lockfile)))
+            return manager;
+    }
+    return "npm";
+}
+/**
+ * Locates the Next.js App Router directory.
+ *
+ * Both layouts create-next-app can produce are supported as-is: `app/` at the
+ * root, and `src/app/` when "use src directory" was chosen. FSD's own app
+ * layer is `src/_app`, so it never collides with either — which is why this
+ * detects rather than moves anything.
+ */
+function detectAppDir(projectDir) {
+    const pkg = readPackageJson(projectDir);
+    const hasNext = Boolean(pkg.dependencies?.next ?? pkg.devDependencies?.next);
+    if (!hasNext) {
+        throw new Error("this package.json has no `next` dependency — create the app first (`bunx create-next-app@latest`), then run `nextjs-fsd init` inside it");
+    }
+    // Posix separators, deliberately, even on Windows: this value is not only a
+    // path. It is interpolated into ESLint `files` globs, Tailwind `@source`
+    // lines and the generated docs, and a glob with a backslash matches nothing
+    // — so a project initialised on Windows would silently lose the rule that
+    // keeps features out of the routing layer. `path.join` normalises it back
+    // for the filesystem calls that need it.
+    for (const candidate of ["app", "src/app"]) {
+        if (fs_extra_1.default.existsSync(path_1.default.join(projectDir, candidate, "layout.tsx")))
+            return candidate;
+    }
+    throw new Error("no App Router layout found at app/layout.tsx or src/app/layout.tsx — this CLI only supports the App Router, not the legacy pages/ router");
+}
+/**
+ * Adds dependencies that are missing, leaving any already-declared version
+ * alone — a project pinned to axios ^1.5 should not get silently bumped
+ * because a template happened to be written against a newer one.
+ * Returns the names actually added.
+ */
+function addDependencies(projectDir, deps, kind = "dependencies") {
+    const file = packageJsonPath(projectDir);
+    const pkg = fs_extra_1.default.readJsonSync(file);
+    const target = { ...(pkg[kind] ?? {}) };
+    const declared = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    const added = [];
+    for (const [name, range] of Object.entries(deps)) {
+        if (declared[name])
+            continue;
+        target[name] = range;
+        added.push(name);
+    }
+    if (added.length === 0)
+        return [];
+    // Sorted so a diff of package.json stays reviewable instead of appending in
+    // whatever order a template listed its dependencies.
+    pkg[kind] = Object.fromEntries(Object.entries(target).sort(([a], [b]) => a.localeCompare(b)));
+    fs_extra_1.default.writeJsonSync(file, pkg, { spaces: 2 });
+    return added;
+}
+function installDependencies(projectDir, manager) {
+    const command = manager === "npm" ? ["npm", "install"] : [manager, "install"];
+    console.log(picocolors_1.default.dim(`> ${command.join(" ")}`));
+    (0, child_process_1.execFileSync)(command[0], command.slice(1), { cwd: projectDir, stdio: "inherit" });
+}
+function runCommand(projectDir, manager, args) {
+    const runner = manager === "npm" ? "npx" : manager === "yarn" ? "yarn" : manager === "pnpm" ? "pnpm" : "bunx";
+    console.log(picocolors_1.default.dim(`> ${runner} ${args.join(" ")}`));
+    (0, child_process_1.execFileSync)(runner, args, { cwd: projectDir, stdio: "inherit" });
+}
+/**
+ * Puts `srcDir` first in the tsconfig `alias/*` path, keeping whatever was
+ * mapped there as a fallback.
+ *
+ * create-next-app maps `@/*` to `./*` (the project root) when it does not use
+ * a src directory, and TypeScript tries a paths array in order — so prepending
+ * makes `@/_pages/login` resolve while an existing `@/app/thing` import in the
+ * project keeps resolving too. Replacing the array outright would break those
+ * silently, in files this CLI never looked at.
+ *
+ * Returns false if srcDir was already first.
+ */
+function patchTsconfigPaths(projectDir, alias, srcDir) {
+    const file = path_1.default.join(projectDir, "tsconfig.json");
+    if (!fs_extra_1.default.existsSync(file))
+        throw new Error("no tsconfig.json — expected one in a Next.js TypeScript project");
+    // Read as text and parse leniently: create-next-app writes strict JSON, but
+    // a hand-edited tsconfig with comments is normal and JSON5 is not worth a
+    // dependency here. A parse failure is reported, not swallowed.
+    let config;
+    try {
+        config = fs_extra_1.default.readJsonSync(file);
+    }
+    catch {
+        throw new Error("could not parse tsconfig.json as JSON (comments?) — add this by hand instead:\n" +
+            `  "paths": { "${alias}/*": ["./${srcDir}/*"] }`);
+    }
+    const key = `${alias}/*`;
+    const first = `./${srcDir}/*`;
+    const options = (config.compilerOptions ??= {});
+    const paths = (options.paths ??= {});
+    const existing = Array.isArray(paths[key]) ? paths[key] : [];
+    if (existing[0] === first)
+        return false;
+    paths[key] = [first, ...existing.filter((entry) => entry !== first)];
+    fs_extra_1.default.writeJsonSync(file, config, { spaces: 2 });
+    return true;
+}
+/**
+ * Adds a step to an npm script, or creates it. Appended with `&&` rather than
+ * replaced: `lint` already runs eslint in a fresh Next.js project and both
+ * checks matter.
+ */
+function appendScript(projectDir, name, step) {
+    const file = packageJsonPath(projectDir);
+    const pkg = fs_extra_1.default.readJsonSync(file);
+    const scripts = (pkg.scripts ??= {});
+    const existing = scripts[name];
+    if (existing?.includes(step))
+        return false;
+    scripts[name] = existing ? `${existing} && ${step}` : step;
+    fs_extra_1.default.writeJsonSync(file, pkg, { spaces: 2 });
+    return true;
+}
+/** Appends an export line to a barrel, creating it if absent. */
+function appendExport(projectDir, barrel, line) {
+    const file = path_1.default.join(projectDir, barrel);
+    if (!fs_extra_1.default.existsSync(file)) {
+        fs_extra_1.default.ensureDirSync(path_1.default.dirname(file));
+        fs_extra_1.default.writeFileSync(file, `${line}\n`);
+        return true;
+    }
+    const current = fs_extra_1.default.readFileSync(file, "utf8");
+    if (current.includes(line))
+        return false;
+    fs_extra_1.default.writeFileSync(file, current.replace(/\n*$/, "\n") + `${line}\n`);
+    return true;
+}
+/** Appends a block to .env.example, skipping it if the key is already there. */
+function appendEnvExample(projectDir, key, block) {
+    const file = path_1.default.join(projectDir, ".env.example");
+    const current = fs_extra_1.default.existsSync(file) ? fs_extra_1.default.readFileSync(file, "utf8") : "";
+    if (current.includes(key))
+        return false;
+    fs_extra_1.default.writeFileSync(file, current === "" ? block : current.replace(/\n*$/, "\n\n") + block);
+    return true;
+}
+/**
+ * Repoints the root layout's stylesheet import at the FSD app layer.
+ *
+ * The CSS file moves because Tailwind v4's `@theme` is project-wide
+ * configuration, which is app-layer, not route-adjacent — and the import in
+ * layout.tsx is the only reference to its old path.
+ */
+function patchLayoutStyleImport(projectDir, appDir, alias) {
+    const file = path_1.default.join(projectDir, appDir, "layout.tsx");
+    const source = fs_extra_1.default.readFileSync(file, "utf8");
+    const target = `import "${alias}/_app/styles/globals.css";`;
+    if (source.includes(target))
+        return false;
+    const patched = source.replace(/^import\s+["']\.\/globals\.css["'];?[ \t]*$/m, target);
+    if (patched === source)
+        return false;
+    fs_extra_1.default.writeFileSync(file, patched);
+    return true;
+}
+/**
+ * Wraps the root layout's JSX `{children}` in `<Providers>`.
+ *
+ * Anchored on `<body`, because `{ children }` appears twice in every App
+ * Router layout and the first one is the destructured parameter —
+ * `RootLayout({ children }: LayoutProps<"/">)`. Patching that one produces
+ * `RootLayout(<Providers>{children}</Providers>: ...)`, a file that no longer
+ * parses, which is why the search starts after the opening body tag instead of
+ * at the top of the file.
+ *
+ * Regex, not an AST: this runs once on a file whose shape create-next-app
+ * fixes, and every way it can miss — already wrapped, no <body>, no children —
+ * returns without touching the file so the caller can print instructions.
+ */
+function patchLayoutProviders(projectDir, appDir, alias) {
+    const file = path_1.default.join(projectDir, appDir, "layout.tsx");
+    const source = fs_extra_1.default.readFileSync(file, "utf8");
+    if (/<Providers[\s>]/.test(source))
+        return "already";
+    const bodyAt = source.indexOf("<body");
+    if (bodyAt === -1)
+        return "manual";
+    const children = /\{\s*children\s*\}/.exec(source.slice(bodyAt));
+    if (!children)
+        return "manual";
+    const imports = [...source.matchAll(/^import .*$/gm)];
+    const lastImport = imports[imports.length - 1];
+    // index 0 is a real position: a layout whose first line is an import.
+    if (lastImport?.index === undefined)
+        return "manual";
+    const importAt = source.indexOf("\n", lastImport.index) + 1;
+    // Children first, then the import: both edits are index-based, and the
+    // import sits earlier in the file, so doing the later one first keeps the
+    // earlier offset valid.
+    const childrenAt = bodyAt + children.index;
+    const withProvider = source.slice(0, childrenAt) +
+        "<Providers>" +
+        children[0] +
+        "</Providers>" +
+        source.slice(childrenAt + children[0].length);
+    const importLine = `import { Providers } from "${alias}/_app/providers";\n`;
+    fs_extra_1.default.writeFileSync(file, withProvider.slice(0, importAt) + importLine + withProvider.slice(importAt));
+    return "patched";
+}
+const ESLINT_CONFIG_FILES = ["eslint.config.mjs", "eslint.config.js", "eslint.config.ts", "eslint.config.cjs"];
+/**
+ * Spreads the generated FSD boundary config into the project's flat ESLint
+ * config.
+ *
+ * A separate `eslint.fsd.mjs` plus a two-line patch, rather than injecting the
+ * rules into the array literal: create-next-app's config is
+ * `export default eslintConfig;` over a `defineConfig([...])` call, and
+ * splicing rules into that call means parsing JS to find the right closing
+ * bracket. Two anchors — the last import, and the default export — are all
+ * this needs, and a config someone has restructured falls through to printed
+ * instructions instead of a wrong edit.
+ */
+function patchEslintConfig(projectDir) {
+    const file = ESLINT_CONFIG_FILES.map((name) => path_1.default.join(projectDir, name)).find((candidate) => fs_extra_1.default.existsSync(candidate));
+    if (!file)
+        return "missing";
+    const source = fs_extra_1.default.readFileSync(file, "utf8");
+    if (source.includes("eslint.fsd.mjs"))
+        return "already";
+    // `export default <identifier>;` is the shape every create-next-app config
+    // has had. An inline array or call expression is left alone.
+    const exported = /^export default (\w+);?[ \t]*$/m.exec(source);
+    const imports = [...source.matchAll(/^import .*$/gm)];
+    const lastImport = imports[imports.length - 1];
+    if (!exported || lastImport?.index === undefined)
+        return "manual";
+    // The export sits after the imports, so replacing it first keeps the
+    // import offset computed from the original source valid.
+    const importAt = source.indexOf("\n", lastImport.index) + 1;
+    // A named const rather than `export default [...]`: eslint-config-next
+    // warns on an anonymous default export, and init should not hand someone a
+    // config file that lints with a warning.
+    const withExport = source.replace(exported[0], `const fsdEslintConfig = [...${exported[1]}, ...fsdBoundary];\nexport default fsdEslintConfig;`);
+    fs_extra_1.default.writeFileSync(file, withExport.slice(0, importAt) + 'import fsdBoundary from "./eslint.fsd.mjs";\n' + withExport.slice(importAt));
+    return "patched";
+}

package/dist/utils/render.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTemplatesRoot = getTemplatesRoot;
+exports.renderString = renderString;
+exports.renderTemplate = renderTemplate;
+exports.applyTemplates = applyTemplates;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const handlebars_1 = __importDefault(require("handlebars"));
+handlebars_1.default.registerHelper("eq", (a, b) => a === b);
+handlebars_1.default.registerHelper("includes", (list, value) => Array.isArray(list) && list.includes(value));
+function getTemplatesRoot() {
+    const candidates = [
+        path_1.default.join(__dirname, "..", "..", "templates"),
+        path_1.default.join(__dirname, "..", "..", "..", "templates"),
+    ];
+    const resolved = candidates.find((candidate) => fs_1.default.existsSync(path_1.default.join(candidate, "init", "steiger.config.ts.hbs")));
+    if (!resolved)
+        throw new Error("unable to locate templates directory");
+    return resolved;
+}
+function renderString(source, context) {
+    return handlebars_1.default.compile(source, { noEscape: true })(context);
+}
+function renderTemplate(template, context) {
+    const source = fs_1.default.readFileSync(path_1.default.join(getTemplatesRoot(), template), "utf8");
+    return renderString(source, context);
+}
+/**
+ * Renders a set of templates, refusing the whole batch if any output already
+ * exists.
+ *
+ * All-or-nothing on purpose: a partial write leaves a slice with two of its
+ * four files rendered against a name the other two never saw, and the second
+ * run then refuses because of the files the first run made. Reporting every
+ * collision up front also means one message instead of one per re-run.
+ */
+async function applyTemplates(projectRoot, entries, context, opts = {}) {
+    const root = getTemplatesRoot();
+    let planned = entries.filter((entry) => !entry.when || entry.when(context));
+    const exists = (entry) => fs_extra_1.default.existsSync(path_1.default.join(projectRoot, entry.output));
+    if (opts.skipExisting) {
+        planned = planned.filter((entry) => entry.overwrite || !exists(entry));
+    }
+    else {
+        const collisions = planned.filter((entry) => !entry.overwrite && exists(entry)).map((entry) => entry.output);
+        if (collisions.length > 0) {
+            throw new Error(`refusing to overwrite existing file${collisions.length > 1 ? "s" : ""}:\n` +
+                collisions.map((file) => `  ${file}`).join("\n") +
+                "\nDelete them first, or generate under a different name.");
+        }
+    }
+    const written = [];
+    for (const entry of planned) {
+        const source = await fs_extra_1.default.readFile(path_1.default.join(root, entry.template), "utf8");
+        const outputPath = path_1.default.join(projectRoot, entry.output);
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(outputPath));
+        await fs_extra_1.default.writeFile(outputPath, renderString(source, context));
+        written.push(entry.output);
+    }
+    return written;
+}

package/dist/utils/version.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cliVersion = cliVersion;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+// cliVersion reads this CLI's own version out of its package.json — one source
+// of truth for `--version` and for the stamp written into a project's
+// nextjs-fsd.config.json. Two candidates because __dirname is dist/utils when
+// installed and src/utils when running from a checkout.
+function cliVersion() {
+    const candidates = [
+        path_1.default.join(__dirname, "..", "..", "package.json"),
+        path_1.default.join(__dirname, "..", "..", "..", "package.json"),
+    ];
+    const resolved = candidates.find((candidate) => fs_1.default.existsSync(candidate));
+    if (!resolved)
+        throw new Error("unable to locate package.json");
+    return fs_extra_1.default.readJsonSync(resolved).version;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@nakedev/nextjs-fsd",
+  "version": "0.1.0",
+  "description": "Keep a Next.js App Router project on Feature-Sliced Design: init the layout, generate slices, add auth and API error handling",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NakePranob/nextjs-fsd.git"
+  },
+  "bin": {
+    "nextjs-fsd": "bin/nextjs-fsd.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "bin",
+    "LICENSE"
+  ],
+  "type": "commonjs",
+  "packageManager": "pnpm@11.10.0",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test tests/*.test.mjs && node scripts/smoke-test.mjs",
+    "verify": "pnpm run build && pnpm run test",
+    "prepack": "rm -rf dist && pnpm run build",
+    "test:smoke": "node scripts/smoke-test.mjs",
+    "test:integration": "node scripts/integration-test.mjs",
+    "prepublishOnly": "pnpm run verify"
+  },
+  "keywords": [
+    "nextjs",
+    "feature-sliced",
+    "fsd",
+    "scaffold",
+    "cli",
+    "generator"
+  ],
+  "author": "nakedev",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.5.1",
+    "commander": "^15.0.0",
+    "fs-extra": "^11.3.0",
+    "handlebars": "^4.7.8",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.101.4",
+    "@types/bun": "^1.3.14",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "axios": "^1.19.0",
+    "next": "16.3.4",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.9"
+  }
+}

package/templates/add/auth/auth-errors.ts.hbs

@@ -0,0 +1,22 @@
+import { commonErrorCatalog, resolveApiError, type ErrorCatalog } from "{{alias}}/shared/api";
+
+/**
+ * Codes the auth surface owns. TODO: match the codes your API actually raises
+ * — these are the common ones, and an unmapped code falls through to the
+ * caller's fallback sentence rather than breaking anything.
+ */
+export const authErrorCatalog: ErrorCatalog = {
+{{authCatalogEntries}}
+};
+
+/**
+ * Pass this to `<FormError catalogs={...}>` on an auth screen. Auth first,
+ * then the codes every endpoint shares — a screen that needs to reword one
+ * code puts its own catalog in front.
+ */
+export const authErrorCatalogs: readonly ErrorCatalog[] = [authErrorCatalog, commonErrorCatalog];
+
+/** For auth copy outside a `<FormError>` — a toast, a heading, a redirect reason. */
+export function resolveAuthError(error: unknown, fallback = "{{copy.genericError}}"): string {
+  return resolveApiError(error, { catalogs: authErrorCatalogs, fallback });
+}

package/templates/add/auth/index.ts.hbs

@@ -0,0 +1,4 @@
+export { getAccessToken, setAccessToken } from "./access-token";
+export { authErrorCatalog, authErrorCatalogs, resolveAuthError } from "./auth-errors";
+export { sessionKey, useLogin, useLogout, useSession, type LoginInput, type Session } from "./session";
+export { useRequireSession } from "./require-session";

package/templates/add/auth/login-form.tsx.hbs

@@ -0,0 +1,48 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { type FormEvent } from "react";
+
+import { authErrorCatalogs, useLogin } from "{{alias}}/shared/auth";
+import { FormError } from "{{alias}}/shared/ui";
+
+const field = "rounded-md border border-black/15 px-3 py-2 text-sm dark:border-white/20";
+
+export function LoginForm() {
+  const login = useLogin();
+  const router = useRouter();
+
+  function onSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const form = new FormData(event.currentTarget);
+    login.mutate(
+      { email: String(form.get("email") ?? ""), password: String(form.get("password") ?? "") },
+      { onSuccess: () => router.replace("/") },
+    );
+  }
+
+  return (
+    // Native HTML validation only: `required`/`type="email"` catch the obvious
+    // mistakes before a round trip, and the API re-validates every field
+    // anyway. Swap in a schema library once a form here has rules the browser
+    // cannot express.
+    <form onSubmit={onSubmit} className="flex flex-col gap-4">
+      <FormError error={login.error} catalogs={authErrorCatalogs} fallback="{{copy.signInFailed}}" />
+      <label className="flex flex-col gap-1.5 text-sm">
+        {{copy.email}}
+        <input name="email" type="email" required autoComplete="email" className={field} />
+      </label>
+      <label className="flex flex-col gap-1.5 text-sm">
+        {{copy.password}}
+        <input name="password" type="password" required autoComplete="current-password" className={field} />
+      </label>
+      <button
+        type="submit"
+        disabled={login.isPending}
+        className="mt-2 rounded-md bg-foreground px-3 py-2 text-sm text-background disabled:opacity-60"
+      >
+        {login.isPending ? "{{copy.signingIn}}" : "{{copy.signIn}}"}
+      </button>
+    </form>
+  );
+}

package/templates/add/auth/login-index.ts.hbs

@@ -0,0 +1 @@
+export { LoginPage, metadata } from "./ui/login-page";

package/templates/add/auth/login-page.tsx.hbs

@@ -0,0 +1,18 @@
+import type { Metadata } from "next";
+
+import { LoginForm } from "./login-form";
+
+export const metadata: Metadata = { title: "{{copy.signIn}}" };
+
+// Server component — the form below is the only part that needs the browser.
+export function LoginPage() {
+  return (
+    <main className="mx-auto flex min-h-svh w-full max-w-sm flex-col justify-center gap-6 p-6">
+      <div className="flex flex-col gap-1">
+        <h1 className="text-2xl font-semibold">{{copy.signIn}}</h1>
+        <p className="text-sm opacity-70">{{copy.signInSubtitle}}</p>
+      </div>
+      <LoginForm />
+    </main>
+  );
+}

package/templates/add/auth/require-session.ts.hbs

@@ -0,0 +1,29 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useEffect } from "react";
+
+import { useSession } from "./session";
+
+/**
+ * Session for a page that needs one, sending anonymous visitors to /login.
+ *
+ * UX only — the real gate is the API's own auth middleware, which every
+ * request passes through regardless of what the browser rendered. It cannot
+ * move into `proxy.ts` (Next 16's renamed middleware) either: the refresh
+ * cookie belongs to the API's origin, so the Next server never sees it and
+ * has nothing to check.
+ *
+ * No return-to-url: add a `?next=` round trip when deep links into protected
+ * pages start mattering.
+ */
+export function useRequireSession() {
+  const session = useSession();
+  const router = useRouter();
+
+  useEffect(() => {
+    if (session.isError) router.replace("/login");
+  }, [session.isError, router]);
+
+  return session;
+}

package/templates/add/auth/session.ts.hbs

@@ -0,0 +1,75 @@
+"use client";
+
+import { useMutation, useQuery, useQueryClient, type QueryClient, type UseQueryResult } from "@tanstack/react-query";
+
+import { ApiError, api } from "{{alias}}/shared/api";
+
+import { setAccessToken } from "./access-token";
+
+/** GET /users/me. TODO: match the fields your API actually returns. */
+export type Session = {
+  id: string;
+  email: string;
+  name: string;
+  role: string;
+};
+
+export type LoginInput = { email: string; password: string };
+
+/** Body of login/refresh — the refresh token is an httpOnly cookie, not here. */
+type AuthTokens = { access_token: string; token_type: string; expires_in: number };
+
+export const sessionKey = ["session"] as const;
+
+/**
+ * The signed-in user, or an error when there is none.
+ *
+ * On a fresh page load there is no access token yet, so this 401s once and the
+ * client's response interceptor spends the refresh cookie before retrying —
+ * meaning this hook doubles as the session bootstrap. `retry: false` because
+ * that recovery already happened one layer down: a 401 that reaches here means
+ * the cookie is gone too, and asking again will not help.
+ */
+export function useSession(): UseQueryResult<Session, ApiError> {
+  return useQuery<Session, ApiError>({
+    queryKey: sessionKey,
+    queryFn: () => api.get<Session>("/users/me").then((response) => response.data),
+    retry: false,
+    staleTime: 5 * 60_000,
+  });
+}
+
+export function useLogin() {
+  const queryClient = useQueryClient();
+  return useMutation<void, ApiError, LoginInput>({
+    mutationFn: async (input) => {
+      const { data } = await api.post<AuthTokens>("/auth/login", input);
+      setAccessToken(data.access_token);
+      // Refetch rather than write a session object we do not have: the
+      // response carries tokens only, so /users/me stays the single source of
+      // the user's name and role.
+      await queryClient.invalidateQueries({ queryKey: sessionKey });
+    },
+  });
+}
+
+export function useLogout() {
+  const queryClient = useQueryClient();
+  return useMutation<void, ApiError, void>({
+    // Server-side too, not just locally: /auth/logout revokes the refresh
+    // token and clears the cookie, otherwise the next reload silently signs
+    // the user back in.
+    mutationFn: () => api.post("/auth/logout").then(() => undefined),
+    onSettled: () => endSessionLocally(queryClient),
+  });
+}
+
+/**
+ * Ends the session on this device even when the server call failed — the user
+ * asked to leave. `clear()`, not `remove(sessionKey)`: every other cached
+ * query holds the previous user's data.
+ */
+function endSessionLocally(queryClient: QueryClient): void {
+  setAccessToken(null);
+  queryClient.clear();
+}

package/templates/add/errors/access-token.ts.hbs

@@ -0,0 +1,19 @@
+// The access token lives in a module variable and nowhere else.
+//
+// The API returns it in the login/refresh response body and should keep the
+// refresh token in an httpOnly cookie, so there is nothing to persist here: a
+// reload starts with no token and the first 401 spends the cookie on a new
+// one. localStorage would only make the token readable by any injected script.
+//
+// This file imports nothing on purpose — shared/api reads it inside the
+// request interceptor and shared/auth writes it after login, so keeping it
+// dependency-free is what stops those two from importing each other.
+let accessToken: string | null = null;
+
+export function getAccessToken(): string | null {
+  return accessToken;
+}
+
+export function setAccessToken(token: string | null): void {
+  accessToken = token;
+}