@nakedev/nextjs-fsd 0.1.0

package/templates/add/errors/api-error.ts.hbs

@@ -0,0 +1,69 @@
+import axios from "axios";
+
+/**
+ * Error envelope the API uses on failure — one `error` object with a stable
+ * machine code. Adjust the field names here if your backend words them
+ * differently; this is the only place that reads the wire format.
+ */
+type ErrorEnvelope = {
+  error?: {
+    code?: string;
+    message?: string;
+    details?: unknown;
+    request_id?: string;
+  };
+};
+
+/**
+ * Normalised failure for anything crossing the API boundary. Callers branch on
+ * `code`/`status`, never on axios internals — that is the whole point of
+ * converting here, in the response interceptor, instead of leaking
+ * `AxiosError` into hooks and components.
+ */
+export class ApiError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status: number,
+    readonly details?: unknown,
+    readonly requestId?: string,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+
+  /**
+   * Per-field messages for a VALIDATION_ERROR. Many backends only send these
+   * outside production, so every caller has to cope with this being
+   * undefined — never build UI that depends on a field map being present.
+   */
+  get fieldErrors(): Record<string, string> | undefined {
+    if (this.code !== "VALIDATION_ERROR") return undefined;
+    const { details } = this;
+    if (!details || typeof details !== "object") return undefined;
+    const entries = Object.entries(details as Record<string, unknown>).filter(
+      ([, value]) => typeof value === "string",
+    );
+    return entries.length > 0 ? (Object.fromEntries(entries) as Record<string, string>) : undefined;
+  }
+}
+
+export function toApiError(error: unknown): ApiError {
+  if (error instanceof ApiError) return error;
+
+  if (axios.isAxiosError(error)) {
+    const status = error.response?.status ?? 0;
+    const envelope = (error.response?.data as ErrorEnvelope | undefined)?.error;
+    return new ApiError(
+      // status 0 means the request never got an answer — a dead API, DNS, or a
+      // CORS rejection all land here, and they read the same to the user.
+      envelope?.code ?? (status === 0 ? "NETWORK" : "UNKNOWN"),
+      envelope?.message ?? error.message,
+      status,
+      envelope?.details,
+      envelope?.request_id,
+    );
+  }
+
+  return new ApiError("UNKNOWN", error instanceof Error ? error.message : String(error), 0);
+}

package/templates/add/errors/client.test.ts.hbs

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import type { AxiosAdapter } from "axios";
+
+import { createApiClient } from "./client";
+import { ApiError } from "./api-error";
+import { setAccessToken } from "{{alias}}/shared/auth/access-token";
+
+/**
+ * The two rules in the response interceptor that fail silently in a browser:
+ * a refresh storm logs the user out mid-session, and refreshing a login 401
+ * spends the cookie of whoever is already signed in. Both are testable only
+ * because createApiClient takes config — the adapter below stands in for the
+ * network.
+ */
+function stubAdapter(handle: (url: string) => { status: number; data?: unknown }): {
+  adapter: AxiosAdapter;
+  calls: string[];
+} {
+  const calls: string[] = [];
+  const adapter: AxiosAdapter = async (config) => {
+    const url = config.url ?? "";
+    calls.push(url);
+    const { status, data } = handle(url);
+    const response = { data, status, statusText: "", headers: {}, config } as never;
+    if (status >= 400) throw Object.assign(new Error(`HTTP ${status}`), { isAxiosError: true, config, response });
+    return response;
+  };
+  return { adapter, calls };
+}
+
+describe("api client", () => {
+  test("refreshes once for concurrent 401s, then replays both", async () => {
+    setAccessToken("stale");
+    let refreshed = false;
+    const { adapter, calls } = stubAdapter((url) => {
+      if (url === "/auth/refresh") {
+        refreshed = true;
+        return { status: 200, data: { access_token: "fresh" } };
+      }
+      return refreshed ? { status: 200, data: { ok: true } } : { status: 401 };
+    });
+
+    const { api } = createApiClient({ adapter });
+    const results = await Promise.all([api.get("/a"), api.get("/b")]);
+
+    expect(results.every((response) => response.status === 200)).toBe(true);
+    expect(calls.filter((url) => url === "/auth/refresh")).toHaveLength(1);
+  });
+
+  test("does not refresh a 401 from /auth/*", async () => {
+    setAccessToken(null);
+    const { adapter, calls } = stubAdapter(() => ({ status: 401, data: { error: { code: "AUTH_INVALID_CREDENTIALS" } } }));
+
+    const { api } = createApiClient({ adapter });
+    const error = await api.post("/auth/login", {}).catch((thrown) => thrown);
+
+    expect(error).toBeInstanceOf(ApiError);
+    expect((error as ApiError).code).toBe("AUTH_INVALID_CREDENTIALS");
+    expect(calls).toEqual(["/auth/login"]);
+  });
+});

package/templates/add/errors/client.ts.hbs

@@ -0,0 +1,91 @@
+import axios, { type CreateAxiosDefaults, type InternalAxiosRequestConfig } from "axios";
+
+import { getAccessToken, setAccessToken } from "{{alias}}/shared/auth/access-token";
+import { API_URL } from "{{alias}}/shared/config";
+
+import { toApiError } from "./api-error";
+
+const REFRESH_PATH = "/auth/refresh";
+
+type RetriableConfig = InternalAxiosRequestConfig & { _retried?: boolean };
+
+type AccessTokenResponse = { access_token: string };
+
+/**
+ * Builds the API client: bearer token in, normalised {@link ApiError} out, and
+ * one silent refresh attempt per failed request.
+ *
+ * A factory rather than a bare module instance so a test can pass its own
+ * adapter — the refresh handling below is the part worth pinning down.
+ */
+export function createApiClient(defaults: CreateAxiosDefaults = {}) {
+  // withCredentials so the browser attaches an httpOnly refresh cookie on the
+  // /auth/refresh call. Cross-origin by default (:3000 -> the API), which the
+  // API has to allow explicitly in its CORS config.
+  const config: CreateAxiosDefaults = { withCredentials: true, ...defaults };
+  const api = axios.create(config);
+  // Separate instance for the refresh call itself: on `api` it would hit the
+  // interceptor below and try to refresh its own 401, recursively.
+  const bare = axios.create(config);
+
+  let inFlight: Promise<string | null> | null = null;
+
+  /**
+   * Trades the refresh cookie for a new access token. Single-flight: every
+   * request that 401s while one refresh is running awaits that same promise.
+   * A backend that rotates the refresh token on use would otherwise see two
+   * concurrent calls race, and one would invalidate the other's cookie —
+   * logging the user out mid-session.
+   */
+  function refreshAccessToken(): Promise<string | null> {
+    inFlight ??= bare
+      .post<AccessTokenResponse>(REFRESH_PATH)
+      .then(
+        (response) => {
+          const token = response.data.access_token;
+          setAccessToken(token);
+          return token;
+        },
+        () => {
+          // No usable cookie: drop the stale token so the next request goes
+          // out unauthenticated instead of retrying a dead one forever.
+          setAccessToken(null);
+          return null;
+        },
+      )
+      .finally(() => {
+        inFlight = null;
+      });
+    return inFlight;
+  }
+
+  api.interceptors.request.use((request) => {
+    const token = getAccessToken();
+    if (token) request.headers.Authorization = `Bearer ${token}`;
+    return request;
+  });
+
+  api.interceptors.response.use(undefined, async (error: unknown) => {
+    const failed = axios.isAxiosError(error) ? (error.config as RetriableConfig | undefined) : undefined;
+    // A 401 from /auth/* is an answer, not an expired token: wrong password, a
+    // spent challenge, a dead reset link. Refreshing on those would spend the
+    // cookie of whoever is already signed in on this browser and still
+    // surface the same error.
+    const fromAuthEndpoint = failed?.url?.startsWith("/auth/") ?? false;
+
+    if (axios.isAxiosError(error) && error.response?.status === 401 && failed && !failed._retried && !fromAuthEndpoint) {
+      failed._retried = true;
+      const token = await refreshAccessToken();
+      if (token) {
+        failed.headers.Authorization = `Bearer ${token}`;
+        return api.request(failed);
+      }
+    }
+
+    throw toApiError(error);
+  });
+
+  return { api, refreshAccessToken };
+}
+
+export const { api, refreshAccessToken } = createApiClient({ baseURL: API_URL });

package/templates/add/errors/config-index.ts.hbs

@@ -0,0 +1 @@
+export { API_URL } from "./env";

package/templates/add/errors/env.ts.hbs

@@ -0,0 +1,3 @@
+// Base URL of the API, including whatever prefix it mounts its routes under —
+// the prefix belongs here rather than in every request path.
+export const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:8080/api";

package/templates/add/errors/error-catalog.ts.hbs

@@ -0,0 +1,19 @@
+/**
+ * A catalog maps the API's stable machine codes onto UI copy. One catalog per
+ * domain that owns those codes, never one global map: the domain that raises a
+ * code is the only place that knows what it means to a user, and a single map
+ * turns into a merge conflict magnet the moment two features grow at once.
+ */
+export type ErrorCatalog = Readonly<Record<string, string>>;
+
+/**
+ * Codes any endpoint can answer with, plus the two `toApiError` mints
+ * client-side when the request never reached an answer at all.
+ *
+ * Every other catalog composes on top of this one, so a domain catalog only
+ * has to carry what is genuinely its own — generate one with
+ * `nextjs-fsd generate page <name> --errors`.
+ */
+export const commonErrorCatalog: ErrorCatalog = {
+{{commonCatalogEntries}}
+};

package/templates/add/errors/error-resolver.ts.hbs

@@ -0,0 +1,30 @@
+import { ApiError } from "./api-error";
+import type { ErrorCatalog } from "./error-catalog";
+
+export type ResolveApiErrorOptions = {
+  /** Searched in order — first hit wins, so put the most specific first. */
+  catalogs?: readonly ErrorCatalog[];
+  fallback: string;
+};
+
+/**
+ * Turns anything a failed call can throw into one sentence, resolved from the
+ * catalogs the calling domain owns.
+ *
+ * `error.message` is deliberately never used as UI copy: the wording is a
+ * backend implementation detail that changes without anyone here noticing, and
+ * it is written for a developer reading a log. An unmapped code is a gap in a
+ * catalog, and a fallback that names the action that failed
+ * ("{{copy.saveFailed}}") is more useful to the user than a literal backend
+ * message would have been anyway.
+ */
+export function resolveApiError(error: unknown, { catalogs = [], fallback }: ResolveApiErrorOptions): string {
+  if (!(error instanceof ApiError)) return fallback;
+
+  for (const catalog of catalogs) {
+    const message = catalog[error.code];
+    if (message) return message;
+  }
+
+  return fallback;
+}

package/templates/add/errors/form-error.tsx.hbs

@@ -0,0 +1,50 @@
+import { ApiError, commonErrorCatalog, resolveApiError, type ErrorCatalog } from "{{alias}}/shared/api";
+
+/**
+ * Renders a failed API call: one sentence resolved from the caller's catalogs,
+ * plus per-field details when the API sent them (usually dev only, which is
+ * why those stay untranslated).
+ *
+ * This component owns no copy of its own. The domain that raises a code owns
+ * the sentence for it — `authErrorCatalogs` from `{{alias}}/shared/auth`, or a
+ * `_pages/<page>/model/<page>-errors.ts` — so adding a feature never means
+ * editing a component in shared/ui.
+ */
+export function FormError({
+  error,
+  // Searched in order, so a screen that reads one code differently from the
+  // rest of its domain puts its own map first.
+  catalogs = [commonErrorCatalog],
+  fallback = "{{copy.genericError}}",
+  className,
+}: {
+  error: unknown;
+  catalogs?: readonly ErrorCatalog[];
+  fallback?: string;
+  className?: string;
+}) {
+  if (!error) return null;
+
+  const fields = error instanceof ApiError ? error.fieldErrors : undefined;
+  const message = resolveApiError(error, { catalogs, fallback });
+
+  return (
+    <div
+      role="alert"
+      className={["rounded-md border border-red-500/40 bg-red-500/10 px-3 py-2 text-sm text-red-700 dark:text-red-400", className]
+        .filter(Boolean)
+        .join(" ")}
+    >
+      <p>{message}</p>
+      {fields && (
+        <ul className="mt-1 list-inside list-disc">
+          {Object.entries(fields).map(([field, rule]) => (
+            <li key={field}>
+              {field}: {rule}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,5 @@
+export { ApiError, toApiError } from "./api-error";
+export { commonErrorCatalog, type ErrorCatalog } from "./error-catalog";
+export { resolveApiError, type ResolveApiErrorOptions } from "./error-resolver";
+export { api, createApiClient, refreshAccessToken } from "./client";
+export { makeQueryClient } from "./query-client";

package/templates/add/errors/providers.tsx.hbs

@@ -0,0 +1,14 @@
+"use client";
+
+import { QueryClientProvider } from "@tanstack/react-query";
+import { useState, type ReactNode } from "react";
+
+import { makeQueryClient } from "{{alias}}/shared/api";
+
+export function Providers({ children }: { children: ReactNode }) {
+  // useState, not a module constant: one client per mount keeps a server
+  // render from sharing cache across requests.
+  const [queryClient] = useState(makeQueryClient);
+
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+}

package/templates/add/errors/query-client.ts.hbs

@@ -0,0 +1,25 @@
+import { QueryClient } from "@tanstack/react-query";
+
+import { ApiError } from "./api-error";
+
+/**
+ * One QueryClient per browser session (see _app/providers) — created through a
+ * function, not as a module constant, so a server render never shares cache
+ * between two users' requests.
+ */
+export function makeQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 30_000,
+        // A 4xx is an answer, not a hiccup: retrying a 401/403/404 just delays
+        // the error the UI already has to handle. 5xx and network failures
+        // (status 0) are worth one more shot.
+        retry: (failureCount, error) => {
+          const retriable = !(error instanceof ApiError) || error.status === 0 || error.status >= 500;
+          return retriable && failureCount < 2;
+        },
+      },
+    },
+  });
+}

package/templates/generate/layout/layout.tsx.hbs

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+
+/**
+ * Shell for the {{name}} routes.
+ *
+ * Takes a plain `{ children }` rather than `LayoutProps<...>`: Next emits no
+ * route-props type for a route group, since a group contributes nothing to the
+ * URL. Change it to `LayoutProps<"/{{name}}">` if you point this at a real path
+ * segment instead.
+ *
+ * A layout is composition, not a page — put anything with its own state or
+ * data in a slice and render that here.
+ */
+export function {{pascal}}Layout({ children }: { children: ReactNode }) {
+  return (
+    <div className="flex min-h-svh flex-col">
+      <main className="flex-1 p-6">{children}</main>
+    </div>
+  );
+}

package/templates/generate/layout/route.tsx.hbs

@@ -0,0 +1 @@
+export { {{pascal}}Layout as default } from "{{alias}}/_app/layouts";

package/templates/generate/page/content.tsx.hbs

@@ -0,0 +1,17 @@
+"use client";
+{{#if auth}}
+
+import { useRequireSession } from "{{alias}}/shared/auth";
+{{/if}}
+
+export function {{pascal}}Content() {
+{{#if auth}}
+  // UX only. The API's own auth middleware is the real gate and it runs on
+  // every request no matter what the browser rendered, so never treat a
+  // rendered page as proof of a session.
+  const session = useRequireSession();
+  if (session.isPending || session.isError) return <p className="text-sm">{{copy.loading}}</p>;
+
+{{/if}}
+  return <p className="text-sm">{{copy.todo}}</p>;
+}

package/templates/generate/page/errors.ts.hbs

@@ -0,0 +1,22 @@
+import { commonErrorCatalog, resolveApiError, type ErrorCatalog } from "{{alias}}/shared/api";
+
+/**
+ * Machine codes this page's own endpoints answer with, mapped to the sentence
+ * a user should read.
+ *
+ * One catalog per domain that owns the codes, never one global map: the domain
+ * that raises a code is the only place that knows what it means to a user, and
+ * a single map turns into a merge conflict magnet the moment two features grow
+ * at once.
+ */
+export const {{camel}}ErrorCatalog: ErrorCatalog = {
+  // "{{screaming}}_NOT_FOUND": "…",
+};
+
+/** Pass to `<FormError catalogs={...}>`. Most specific first. */
+export const {{camel}}ErrorCatalogs: readonly ErrorCatalog[] = [{{camel}}ErrorCatalog, commonErrorCatalog];
+
+/** For copy outside a `<FormError>` — a toast, a heading, a redirect reason. */
+export function resolve{{pascal}}Error(error: unknown, fallback = "{{copy.genericError}}"): string {
+  return resolveApiError(error, { catalogs: {{camel}}ErrorCatalogs, fallback });
+}

package/templates/generate/page/index.ts.hbs

@@ -0,0 +1 @@
+export { {{pascal}}Page, metadata } from "./ui/{{name}}-page";

package/templates/generate/page/page.tsx.hbs

@@ -0,0 +1,22 @@
+import type { Metadata } from "next";
+{{#if hasContent}}
+import { {{pascal}}Content } from "./{{name}}-content";
+{{/if}}
+
+export const metadata: Metadata = { title: "{{title}}" };
+
+// Server component: no state, no effects, no browser API. Anything that needs
+// those goes in a "use client" leaf under ui/ so this page's whole tree does
+// not ship to the browser.
+export function {{pascal}}Page() {
+  return (
+    <div className="flex flex-col gap-6">
+      <h1 className="text-2xl font-semibold">{{title}}</h1>
+{{#if hasContent}}
+      <{{pascal}}Content />
+{{else}}
+      <p className="text-sm">{{copy.todo}}</p>
+{{/if}}
+    </div>
+  );
+}

package/templates/generate/page/route.tsx.hbs

@@ -0,0 +1,3 @@
+// Routing only — `metadata` travels with the component, because a route file
+// that re-exports `default` alone silently drops the page's title.
+export { {{pascal}}Page as default, metadata } from "{{alias}}/_pages/{{name}}";

package/templates/generate/slice/api.ts.hbs

@@ -0,0 +1,42 @@
+"use client";
+
+import { useMutation, useQuery, useQueryClient, type UseQueryResult } from "@tanstack/react-query";
+
+import { ApiError, api } from "{{alias}}/shared/api";
+
+/**
+ * The record this slice is about. TODO: replace with the shape the API
+ * actually answers.
+ *
+ * Named `{{pascal}}Record` rather than `{{pascal}}` so it can share a public API
+ * with the `{{pascal}}` component in ui/ — one `index.ts` cannot re-export two
+ * different things under one name, and a type nobody can import through the
+ * slice's public API is a type nobody can annotate against without breaking
+ * the import boundary.
+ */
+export type {{pascal}}Record = { id: string };
+
+export const {{camel}}Key = ["{{name}}"] as const;
+
+// Always through `api` — a bare fetch skips the bearer token, the
+// single-flight 401 refresh, and the conversion into ApiError.
+export function use{{pascal}}Query(): UseQueryResult<{{pascal}}Record[], ApiError> {
+  return useQuery<{{pascal}}Record[], ApiError>({
+    queryKey: {{camel}}Key,
+    queryFn: () => api.get<{{pascal}}Record[]>("/{{name}}").then((response) => response.data),
+  });
+}
+
+/**
+ * A write invalidates the keys it affected rather than writing the new value
+ * into the cache by hand — unless the response actually carries the whole
+ * object, the server is still the only thing that knows what got stored
+ * (generated ids, defaults, computed fields).
+ */
+export function useCreate{{pascal}}() {
+  const queryClient = useQueryClient();
+  return useMutation<{{pascal}}Record, ApiError, Omit<{{pascal}}Record, "id">>({
+    mutationFn: (input) => api.post<{{pascal}}Record>("/{{name}}", input).then((response) => response.data),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: {{camel}}Key }),
+  });
+}

package/templates/generate/slice/errors.ts.hbs

@@ -0,0 +1,22 @@
+import { commonErrorCatalog, resolveApiError, type ErrorCatalog } from "{{alias}}/shared/api";
+
+/**
+ * Machine codes this page's own endpoints answer with, mapped to the sentence
+ * a user should read.
+ *
+ * One catalog per domain that owns the codes, never one global map: the domain
+ * that raises a code is the only place that knows what it means to a user, and
+ * a single map turns into a merge conflict magnet the moment two features grow
+ * at once.
+ */
+export const {{camel}}ErrorCatalog: ErrorCatalog = {
+  // "{{screaming}}_NOT_FOUND": "…",
+};
+
+/** Pass to `<FormError catalogs={...}>`. Most specific first. */
+export const {{camel}}ErrorCatalogs: readonly ErrorCatalog[] = [{{camel}}ErrorCatalog, commonErrorCatalog];
+
+/** For copy outside a `<FormError>` — a toast, a heading, a redirect reason. */
+export function resolve{{pascal}}Error(error: unknown, fallback = "{{copy.genericError}}"): string {
+  return resolveApiError(error, { catalogs: {{camel}}ErrorCatalogs, fallback });
+}

package/templates/generate/slice/index.ts.hbs

@@ -0,0 +1,15 @@
+{{#if segments.ui}}
+export { {{pascal}} } from "./ui/{{name}}";
+{{/if}}
+{{#if segments.model}}
+export { use{{pascal}} } from "./model/{{name}}";
+{{/if}}
+{{#if segments.api}}
+export { {{camel}}Key, useCreate{{pascal}}, use{{pascal}}Query, type {{pascal}}Record } from "./api/{{name}}";
+{{/if}}
+{{#if segments.lib}}
+export { format{{pascal}} } from "./lib/{{name}}";
+{{/if}}
+{{#if segments.errors}}
+export { {{camel}}ErrorCatalog, {{camel}}ErrorCatalogs, resolve{{pascal}}Error } from "./model/{{name}}-errors";
+{{/if}}

package/templates/generate/slice/lib.ts.hbs

@@ -0,0 +1,4 @@
+/** Pure helpers for this slice. No React, no requests — those are ui/ and api/. */
+export function format{{pascal}}(value: string): string {
+  return value;
+}

package/templates/generate/slice/model.ts.hbs

@@ -0,0 +1,10 @@
+"use client";
+
+import { useState } from "react";
+
+/** State this slice owns and that never leaves the browser. Anything that
+ *  comes from the API belongs in api/ as a TanStack Query hook instead. */
+export function use{{pascal}}() {
+  const [state, setState] = useState<string | null>(null);
+  return { state, setState };
+}

package/templates/generate/slice/ui.tsx.hbs

@@ -0,0 +1,17 @@
+{{#if needsClient}}
+"use client";
+
+{{/if}}
+{{#if segments.model}}
+import { use{{pascal}} } from "../model/{{name}}";
+
+{{/if}}
+export function {{pascal}}() {
+{{#if segments.model}}
+  const {{camel}} = use{{pascal}}();
+
+  return <p className="text-sm">{JSON.stringify({{camel}})}</p>;
+{{else}}
+  return <p className="text-sm">{{copy.todo}}</p>;
+{{/if}}
+}

package/templates/init/agents-section.md.hbs

@@ -0,0 +1,25 @@
+
+## Frontend architecture — Feature-Sliced Design
+
+`{{srcDir}}/` uses FSD v2.1 with the layers `_app`, `_pages`, `shared`
+(`features`/`entities` are added when a second consumer appears). Read
+[docs/fsd.md](docs/fsd.md) before adding a file under `{{srcDir}}/` — it has the
+import boundary, the segment rules, and why `{{appDir}}/` only ever re-exports.
+
+Rules that are easy to break without noticing:
+
+- imports point downwards only, and a slice is imported through its `index.ts`
+- `{{appDir}}/<route>/page.tsx` re-exports the FSD page **and its `metadata`** — nothing else
+- `"use client"` goes on the leaf that needs it, not on the page
+- `{{lintCommand}}` runs both linters: ESLint (`eslint.fsd.mjs`) flags a wrong-way or slice-internal import per file, steiger (`steiger.config.ts`) flags whole-tree problems like a slice with no consumers
+- editing `eslint.fsd.mjs`: flat config replaces a rule's options when a later block matches the same file, so all of a layer's `no-restricted-imports` patterns must stay in that layer's one block
+
+Claude Code also loads this as a skill at
+`.claude/skills/nextjs-fsd/SKILL.md`, which carries the same contract in the
+form it reads first. `docs/fsd.md` is the source of truth if the two disagree.
+
+Scaffold with `nextjs-fsd generate page|slice|layout` rather than by hand, so
+slices keep the same shape. Re-running one extends what exists (adds a
+segment, a leaf, an error catalog) and never rewrites a file you already have.
+`shadcn add <name>` is already aimed at `{{srcDir}}/shared/ui` by
+`components.json`.

package/templates/init/claude.md.hbs

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/init/components.json.hbs

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "{{srcDir}}/_app/styles/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "{{alias}}/shared",
+    "ui": "{{alias}}/shared/ui",
+    "lib": "{{alias}}/shared/lib",
+    "utils": "{{alias}}/shared/lib/utils",
+    "hooks": "{{alias}}/shared/lib"
+  }
+}