domain-driver 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # domain-driver 🚀
 
-A CLI scaffolding tool for domain-driven feature folders. Like Laravel's `php artisan make`, but for Next.js, React, Node, and NestJS projects. It detects your stack and generates only the layers that stack needs, one file per action.
+A CLI scaffolding tool for domain-driven feature folders. Like Laravel's `php artisan make`, but for Next.js, React, Node, NestJS, and TanStack Start projects. It detects your stack and generates only the layers that stack needs, one file per action.
 
 ---
 
@@ -29,6 +29,7 @@ Stack: next-fullstack (detected)
 | Stack | Detected when | Features live in |
 |---|---|---|
 | `nest` | `@nestjs/core` is a dependency | `src/<feature>` |
+| `tanstack-start` | `@tanstack/react-start` is a dependency | `src/routes/<feature>` or `routes/<feature>` |
 | `next-fullstack` | `next` is a dependency and `app/api`, `src/app/api`, `pages/api`, or `src/pages/api` exists | `app/<feature>` or `src/app/<feature>` |
 | `next-frontend` | `next` is a dependency, no api directory | `app/<feature>` or `src/app/<feature>` |
 | `react` | `react` is a dependency, `next` is not | `src/features/<feature>` or `features/<feature>` |
@@ -46,19 +47,19 @@ domain-driver --stack nest make:feature cat -a
 
 ## What each stack generates
 
-| Layer | next-fullstack | next-frontend | react | node | nest |
-|---|---|---|---|---|---|
-| `page.tsx` | yes | yes | | | |
-| components | client + server | client + server | flat | | |
-| containers, hooks | yes | yes | yes | | |
-| client services + repositories (fetch) | `client/` | top level | top level | | |
-| server services + repositories (database stubs) | `server/` | | | yes | yes |
-| controllers | `app/api/<feature>/` route handlers | | | five files + routes file | five files |
-| module | | | | | yes |
-| DTOs (`nestjs-zod`) | | | | | yes |
-| schemas (Zod), types | yes | yes | yes | yes | yes |
+| Layer | next-fullstack | next-frontend | react | node | nest | tanstack-start |
+|---|---|---|---|---|---|---|
+| entry file (`page.tsx`; `index.tsx` on tanstack-start) | yes | yes | | | | yes |
+| components | client + server | client + server | flat | | | flat |
+| containers, hooks | yes | yes | yes | | | yes (Query hooks) |
+| client services + repositories | `client/` (fetch) | top level (fetch) | top level (fetch) | | | `-client/` (calls server functions, no fetch) |
+| server services + repositories (database stubs) | `server/` | | | yes | yes | `-server/` |
+| controllers | `app/api/<feature>/` route handlers | | | five files + routes file | five files | server functions (`-server/functions/*.fn.ts`) |
+| module | | | | | yes | |
+| DTOs (`nestjs-zod`) | | | | | yes | |
+| schemas (Zod), types | yes | yes | yes | yes | yes | yes |
 
-Every layer that has actions gets one file per action: `List`, `Show`, `Create`, `Update`, `Delete`. Saving a cat means `CreateCat.controller.ts`, `CreateCat.service.ts`, `CreateCat.repository.ts`, and `CreateCat.schema.ts`.
+Every layer that has actions gets one file per action: `List`, `Show`, `Create`, `Update`, `Delete`. Saving a cat means `CreateCat.controller.ts`, `CreateCat.service.ts`, `CreateCat.repository.ts`, `CreateCat.schema.ts`, and, on stacks with a hook layer, `CreateCat.hook.ts` exporting `useCreateCat`.
 
 ---
 
@@ -69,7 +70,7 @@ Every layer command takes one target, `<feature>/<Name>`: the feature folder on
 ### `make:feature`
 
 ```bash
-domain-driver make:feature users            # folders + .gitkeep, plus page.tsx (Next) or the module (Nest)
+domain-driver make:feature users            # folders + .gitkeep, plus page.tsx (Next), index.tsx (TanStack Start), or the module (Nest)
 domain-driver make:feature users/User -a    # every layer for the detected stack, entity User
 ```
 
@@ -95,8 +96,9 @@ Scaffolds a bespoke operation as its own files, so it never lands inside `ShowUs
 |---|---|
 | `node` | service, repository, controller for the detected framework, plus the line to add above the `/:id` routes in `<feature>.routes.ts` printed |
 | `nest` | injectable service and repository, `@Controller` class, DTO with input, plus the classes to register printed, with the controller listed before `Show<Entity>Controller` |
-| `next-fullstack` | server service and repository, client service and repository, `app/api/<feature>/<slug>/route.ts` |
-| `next-frontend`, `react` | client service and repository calling `/api/<feature>/<slug>` |
+| `next-fullstack` | server service and repository, client service and repository, a hook, `app/api/<feature>/<slug>/route.ts` |
+| `next-frontend`, `react` | client service and repository calling `/api/<feature>/<slug>`, and a hook |
+| `tanstack-start` | server service and repository, client service and repository, a hook, and a server function (`<Name>.fn.ts`) in place of a route handler |
 
 ### `make:controller`
 
@@ -104,7 +106,7 @@ Scaffolds a bespoke operation as its own files, so it never lands inside `ShowUs
 domain-driver make:controller users/User
 ```
 
-Node: five controllers plus `<feature>.routes.ts` for Express, Fastify, or Hono. Nest: five single-action controllers. Next.js fullstack: `app/api/<feature>/route.ts` and `app/api/<feature>/[id]/route.ts`. Not available on frontend-only stacks.
+Node: five controllers plus `<feature>.routes.ts` for Express, Fastify, or Hono. Nest: five single-action controllers. Next.js fullstack: `app/api/<feature>/route.ts` and `app/api/<feature>/[id]/route.ts`. TanStack Start: five server functions (`<Name>.fn.ts`, built with `createServerFn`) under `-server/functions/`. Not available on frontend-only stacks (`next-frontend`, `react`).
 
 ### `make:service` and `make:repository`
 
@@ -113,7 +115,7 @@ domain-driver make:service users/User [--side client|server|both]
 domain-driver make:repository users/User [--side client|server|both]
 ```
 
-`--side` matters on `next-fullstack`, where both sides exist. Default is `both`.
+`--side` matters on `next-fullstack` and `tanstack-start`, where both sides exist. Default is `both`.
 
 ### `make:schema`
 
@@ -129,11 +131,27 @@ Writes `CreateUser.schema.ts` and `UpdateUser.schema.ts`. On Nest it also writes
 domain-driver make:types users/User
 domain-driver make:component users/UserCard [client|server]
 domain-driver make:container users/UserContainer
-domain-driver make:hook users/useUser
+domain-driver make:hook users/User
 ```
 
 Component, container, and hook commands fail with a clear message on backend stacks, and `server` components are rejected on React.
 
+`make:hook` writes one file per action instead of a combined hook: `ListUser.hook.ts`, `ShowUser.hook.ts`, `CreateUser.hook.ts`, `UpdateUser.hook.ts`, `DeleteUser.hook.ts`, each exporting one hook (`useListUser`, `useShowUser`, `useCreateUser`, `useUpdateUser`, `useDeleteUser`). There is no combined `useUser.ts`. On `react`, `next-frontend`, and `next-fullstack` these hold plain React state; on `tanstack-start` they are TanStack Query hooks backed by a generated `<feature>.keys.ts` cache-key module. Generating hooks on this profile prints a one-time reminder to install `@tanstack/react-query`, since TanStack Start does not bundle it.
+
+Because the five hooks no longer share state, containers wire them together. On `react`, `next-frontend`, and `next-fullstack`, where hooks hold plain state:
+
+```tsx
+const { data, loading, error, refetch } = useListCat();
+const { createCat } = useCreateCat({ onSuccess: refetch });
+```
+
+On `tanstack-start`, `useListCat()` returns the `useQuery` result (`data`, `isPending`, `error`, ...) and `useCreateCat()` returns the `useMutation` result (`mutate`, `mutateAsync`, `isPending`, ...) directly — there is no `createCat` property and no `onSuccess` option; the hook invalidates the query cache internally on success:
+
+```tsx
+const { data, isPending, error } = useListCat();
+const { mutate: createCat } = useCreateCat();
+```
+
 ### `init`
 
 ```bash
@@ -192,14 +210,42 @@ Install `nestjs-zod` and register `ZodValidationPipe` as `APP_PIPE` once in your
 
 ---
 
+## Example: `make:feature coffee-type -a` on TanStack Start
+
+```
+src/routes/coffee-type/
+├── index.tsx                    createFileRoute route — the entry, not page.tsx
+├── -components/
+│   └── CoffeeType.tsx
+├── -containers/
+│   └── CoffeeTypeContainer.tsx
+├── -hooks/                      coffee-type.keys.ts, plus five hook files (one per action)
+├── -client/
+│   ├── services/                (five files)
+│   └── repositories/            (five files, call the server functions directly)
+├── -server/
+│   ├── functions/               (five *.fn.ts files, built with createServerFn)
+│   ├── services/                (five files)
+│   └── repositories/            (five files, database-agnostic stubs)
+├── -schemas/
+│   ├── CreateCoffeeType.schema.ts
+│   └── UpdateCoffeeType.schema.ts
+└── -types/
+    └── CoffeeType.types.ts
+```
+
+Every layer directory carries a `-` prefix so TanStack Router excludes it from routing. The controller layer is server functions — `<Name>.fn.ts` built with `createServerFn` — and client repositories import and call them directly, so there is no `fetch` and no `Response.json`. Hooks are TanStack Query, backed by the generated `coffee-type.keys.ts`. Generating hooks on this profile prints a one-time reminder to install `@tanstack/react-query`, since TanStack Start does not bundle it.
+
+---
+
 ## Philosophy
 
 Everything for a feature lives in one folder, and every file does one thing.
 
-- **repositories** — data access only. Client-side repositories call your API; server-side repositories call your database.
+- **repositories** — data access only. Client-side repositories call your API (on TanStack Start, the server function directly); server-side repositories call your database.
 - **services** — business logic, one class per action.
-- **controllers** — HTTP in, service call, HTTP out, one file per action.
-- **hooks** — React state and side effects, calls services.
+- **controllers** — HTTP in, service call, HTTP out, one file per action (server functions on TanStack Start).
+- **hooks** — state and side effects, one hook per action, calls services (TanStack Query on TanStack Start, plain React state elsewhere).
 - **containers** — wire hooks into UI.
 - **components** — presentational UI.
 - **schemas** — Zod validation for create and update; the update body never carries the id, it comes from the path.
@@ -231,6 +277,19 @@ The cache lives in `~/.cache/domain-driver` (or `$XDG_CACHE_HOME/domain-driver`)
 
 ---
 
+## Upgrading from 0.3.x
+
+Hooks are now one file per action — `<Action><Entity>.hook.ts` exporting `use<Action><Entity>` (`useListCat`, `useCreateCat`, ...) — instead of a single combined `use<Entity>.ts`, which is no longer generated. `make:hook` now takes `<feature>/<Entity>`, not `<feature>/use<Entity>`. `make:action` writes a matching hook alongside the service and repository on any stack that has a hook layer.
+
+domain-driver never overwrites a file that already exists, so this only changes new scaffolding: a `use<Entity>.ts` written by an older version is left alone and keeps working. New features and new actions get the per-action hooks; wire them together in the container, since they no longer share state:
+
+```tsx
+const { data, loading, error, refetch } = useListCat();
+const { createCat } = useCreateCat({ onSuccess: refetch });
+```
+
+This release also adds a sixth stack, `tanstack-start`, detected from `@tanstack/react-start` — see the TanStack Start example above.
+
 ## Upgrading from 0.1.0
 
 Every layer command now takes a single `<feature>/<Name>` target instead of separate feature and name arguments, for example `make:schema users User` becomes `make:schema users/User`. `make:feature users -a` still works and names the entity `Users`; write `users/User` if you want a different entity name.
@@ -239,7 +298,7 @@ Every layer command now takes a single `<feature>/<Name>` target instead of sepa
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 20+
 
 ---
 
@@ -255,6 +314,8 @@ npm test
 npm run test:coverage
 ```
 
+`npm run typecheck:tanstack-fixture` compiles a generated TanStack Start feature against the real `@tanstack/react-start` and `@tanstack/react-query` packages to catch drift between the templates and the real APIs. It is network-dependent and slow, so it is not part of `npm test` — run it locally after touching the `tanstack-start` profile or its templates.
+
 ---
 
 ## Roadmap
@@ -264,6 +325,8 @@ npm run test:coverage
 - [x] Per-action files in every layer
 - [x] Bespoke actions with make:action
 - [x] Agent guidance with init and a guarded postinstall
+- [x] TanStack Start stack, with server functions and per-action query hooks
+- [x] Per-action hooks on every stack that has them, replacing the single combined hook
 - [ ] Config file — override stack and feature root per project
 - [ ] Configurable API base URL for client repositories
 - [ ] ORM-aware server repositories

package/dist/cli.js

@@ -126,7 +126,7 @@ function createProgram(deps) {
     });
     program
         .command('make:hook <target>')
-        .description('Scaffold a custom hook inside an existing feature (<feature>/<useName>)')
+        .description('Scaffold single-responsibility hook files inside an existing feature (<feature>/<Entity>)')
         .action((target) => {
         const { feature, name } = (0, target_1.parseTarget)(target);
         (0, hook_1.makeHook)(feature, name);

package/dist/commands/action.js

@@ -39,17 +39,18 @@ const path = __importStar(require("path"));
 const registry_1 = require("../stack/registry");
 const actions_1 = require("../templates/actions");
 const server_repository_1 = require("../templates/backend/server-repository");
-const nest_1 = require("../templates/controllers/nest");
 const next_action_route_1 = require("../templates/controllers/next-action-route");
 const node_1 = require("../templates/controllers/node");
-const client_repository_1 = require("../templates/frontend/client-repository");
 const dto_1 = require("../templates/nest/dto");
 const service_1 = require("../templates/service");
 const schema_1 = require("../templates/shared/schema");
 const fs_1 = require("../utils/fs");
 const naming_1 = require("../utils/naming");
 const paths_1 = require("../utils/paths");
+const controller_renderer_1 = require("./controller-renderer");
 const hints_1 = require("./hints");
+const hook_renderer_1 = require("./hook-renderer");
+const repository_1 = require("./repository");
 const resolve_1 = require("./resolve");
 const write_1 = require("./write");
 function parseReturns(value) {
@@ -70,6 +71,8 @@ function makeAction(feature, entity, actionName, options) {
         wroteAny = writeController(ctx, spec, entity) || wroteAny;
     if ((0, registry_1.hasLayer)(ctx.profile, 'clientRepository'))
         wroteAny = writeSide(ctx, spec, entity, 'client') || wroteAny;
+    if ((0, registry_1.hasLayer)(ctx.profile, 'hook'))
+        wroteAny = writeHook(ctx, spec, entity) || wroteAny;
     if (wroteAny)
         console.log(`✅ Action "${spec.name}" scaffolded in "${feature}"`);
     return wroteAny;
@@ -93,13 +96,23 @@ function writeInput(ctx, spec) {
 function writeSide(ctx, spec, entity, side) {
     const repositoryLayer = side === 'client' ? 'clientRepository' : 'serverRepository';
     const serviceLayer = side === 'client' ? 'clientService' : 'serverService';
-    const renderRepository = side === 'client' ? client_repository_1.renderClientRepository : server_repository_1.renderServerRepository;
+    const renderRepository = side === 'client' ? (0, repository_1.clientRenderer)(ctx) : server_repository_1.renderServerRepository;
     const repositoryFile = path.join((0, resolve_1.ensureLayerDir)(ctx, repositoryLayer), `${spec.name}.repository.ts`);
     const wroteRepository = (0, write_1.writeIfAbsent)(repositoryFile, () => renderRepository(ctx, spec, entity, repositoryFile));
     const serviceFile = path.join((0, resolve_1.ensureLayerDir)(ctx, serviceLayer), `${spec.name}.service.ts`);
     const wroteService = (0, write_1.writeIfAbsent)(serviceFile, () => (0, service_1.renderService)(ctx, spec, entity, serviceFile, side));
     return wroteRepository || wroteService;
 }
+function writeHook(ctx, spec, entity) {
+    const dir = (0, resolve_1.ensureLayerDir)(ctx, 'hook');
+    (0, hook_renderer_1.ensureQueryKeys)(ctx, dir);
+    const render = (0, hook_renderer_1.hookRenderer)(ctx);
+    const filePath = path.join(dir, `${spec.name}.hook.ts`);
+    const wrote = (0, write_1.writeIfAbsent)(filePath, () => render(ctx, spec, entity, filePath));
+    if (wrote)
+        (0, hints_1.hintReactQuery)(ctx.profile);
+    return wrote;
+}
 function writeController(ctx, spec, entity) {
     if (ctx.profile.name === 'next-fullstack') {
         const routeDir = path.join((0, paths_1.apiRouteDir)(ctx.stack, ctx.feature), spec.path.slice(1));
@@ -107,8 +120,9 @@ function writeController(ctx, spec, entity) {
         const routeFile = path.join(routeDir, 'route.ts');
         return (0, write_1.writeIfAbsent)(routeFile, () => (0, next_action_route_1.renderActionRoute)(ctx, spec, routeFile));
     }
-    const controllerFile = path.join((0, resolve_1.ensureLayerDir)(ctx, 'controller'), `${spec.name}.controller.ts`);
-    const render = ctx.profile.name === 'nest' ? nest_1.renderNestController : node_1.renderNodeController;
+    const suffix = (0, controller_renderer_1.controllerSuffix)(ctx.profile.name);
+    const controllerFile = path.join((0, resolve_1.ensureLayerDir)(ctx, 'controller'), `${spec.name}.${suffix}.ts`);
+    const render = (0, controller_renderer_1.controllerRenderer)(ctx.profile.name);
     const wroteController = (0, write_1.writeIfAbsent)(controllerFile, () => render(ctx, spec, entity, controllerFile));
     const line = ctx.profile.name === 'node' ? (0, node_1.renderNodeRouteLine)(ctx, spec, entity) : null;
     if (wroteController && line !== null) {

package/dist/commands/controller-renderer.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.controllerRenderer = controllerRenderer;
+exports.controllerSuffix = controllerSuffix;
+const nest_1 = require("../templates/controllers/nest");
+const node_1 = require("../templates/controllers/node");
+const server_fn_1 = require("../templates/controllers/server-fn");
+const RENDERERS = Object.freeze({
+    nest: nest_1.renderNestController,
+    node: node_1.renderNodeController,
+    'tanstack-start': server_fn_1.renderServerFn,
+});
+const SUFFIXES = Object.freeze({
+    'tanstack-start': 'fn',
+});
+function controllerRenderer(stack) {
+    const renderer = RENDERERS[stack];
+    if (renderer === undefined) {
+        throw new Error(`No controller renderer registered for the "${stack}" stack.`);
+    }
+    return renderer;
+}
+function controllerSuffix(stack) {
+    return SUFFIXES[stack] ?? 'controller';
+}

package/dist/commands/controller.js

@@ -37,11 +37,11 @@ exports.makeController = makeController;
 const path = __importStar(require("path"));
 const registry_1 = require("../stack/registry");
 const actions_1 = require("../templates/actions");
-const nest_1 = require("../templates/controllers/nest");
 const next_route_1 = require("../templates/controllers/next-route");
 const node_1 = require("../templates/controllers/node");
 const fs_1 = require("../utils/fs");
 const paths_1 = require("../utils/paths");
+const controller_renderer_1 = require("./controller-renderer");
 const resolve_1 = require("./resolve");
 const write_1 = require("./write");
 function makeController(feature, name) {
@@ -51,10 +51,12 @@ function makeController(feature, name) {
         return writeNextRoutes(ctx, name);
     }
     const dir = (0, resolve_1.ensureLayerDir)(ctx, 'controller');
-    const render = ctx.profile.name === 'nest' ? nest_1.renderNestController : node_1.renderNodeController;
-    const written = (0, write_1.writeSpecFiles)(dir, (0, actions_1.standardActions)(name), 'controller', (spec, filePath) => render(ctx, spec, name, filePath));
+    const render = (0, controller_renderer_1.controllerRenderer)(ctx.profile.name);
+    const suffix = (0, controller_renderer_1.controllerSuffix)(ctx.profile.name);
+    const written = (0, write_1.writeSpecFiles)(dir, (0, actions_1.standardActions)(name), suffix, (spec, filePath) => render(ctx, spec, name, filePath));
+    const label = ctx.profile.name === 'tanstack-start' ? 'Server functions' : 'Controllers';
     if (written > 0)
-        console.log(`✅ Controllers for "${name}" created at ${dir}`);
+        console.log(`✅ ${label} for "${name}" created at ${dir}`);
     const wroteRoutes = ctx.profile.name === 'node' ? writeNodeRoutes(ctx, name) : false;
     return written > 0 || wroteRoutes;
 }

package/dist/commands/feature.js

@@ -37,6 +37,7 @@ exports.makeFeature = makeFeature;
 const path = __importStar(require("path"));
 const registry_1 = require("../stack/registry");
 const page_1 = require("../templates/frontend/page");
+const route_1 = require("../templates/frontend/route");
 const module_1 = require("../templates/nest/module");
 const fs_1 = require("../utils/fs");
 const naming_1 = require("../utils/naming");
@@ -88,7 +89,7 @@ function scaffoldLayers(ctx, entity) {
     if ((0, registry_1.hasLayer)(profile, 'clientService'))
         (0, service_1.makeService)(feature, entity, 'client');
     if ((0, registry_1.hasLayer)(profile, 'hook'))
-        (0, hook_1.makeHook)(feature, `use${entity}`, entity);
+        (0, hook_1.makeHook)(feature, entity);
     if ((0, registry_1.hasLayer)(profile, 'component'))
         (0, component_1.makeComponent)(feature, entity, 'client');
     if ((0, registry_1.hasLayer)(profile, 'container'))
@@ -96,8 +97,12 @@ function scaffoldLayers(ctx, entity) {
 }
 function writeEntryFile(ctx, entity, all) {
     if ((0, registry_1.hasLayer)(ctx.profile, 'page')) {
-        const filePath = path.join(ctx.featureDir, 'page.tsx');
-        (0, fs_1.writeFileSafe)(filePath, (0, page_1.renderPage)(ctx, entity, filePath, all));
+        const isRoute = ctx.profile.name === 'tanstack-start';
+        const filePath = path.join(ctx.featureDir, isRoute ? 'index.tsx' : 'page.tsx');
+        const content = isRoute
+            ? (0, route_1.renderRoute)(ctx, entity, filePath, all)
+            : (0, page_1.renderPage)(ctx, entity, filePath, all);
+        (0, fs_1.writeFileSafe)(filePath, content);
     }
     if ((0, registry_1.hasLayer)(ctx.profile, 'module')) {
         const filePath = path.join(ctx.featureDir, `${ctx.feature}.module.ts`);

package/dist/commands/hints.js

@@ -2,13 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resetHints = resetHints;
 exports.hintNestjsZod = hintNestjsZod;
+exports.hintReactQuery = hintReactQuery;
 exports.standardClassNames = standardClassNames;
 exports.hintRegisterInModule = hintRegisterInModule;
 const detect_1 = require("../stack/detect");
 const actions_1 = require("../templates/actions");
 let nestjsZodHinted = false;
+let reactQueryHinted = false;
 function resetHints() {
     nestjsZodHinted = false;
+    reactQueryHinted = false;
 }
 function hintNestjsZod(stack) {
     if (stack.stack !== 'nest' || stack.hasNestjsZod || nestjsZodHinted)
@@ -17,6 +20,13 @@ function hintNestjsZod(stack) {
     console.log('ℹ️  nestjs-zod is not installed. Run: npm install nestjs-zod');
     console.log('   Then register the pipe in AppModule: { provide: APP_PIPE, useClass: ZodValidationPipe }');
 }
+function hintReactQuery(profile) {
+    if (!profile.queryHooks || reactQueryHinted)
+        return;
+    reactQueryHinted = true;
+    console.log('ℹ️  Hooks use TanStack Query. Install it: npm install @tanstack/react-query');
+    console.log('   Then wrap your app in a QueryClientProvider.');
+}
 function standardClassNames(name, suffix) {
     return actions_1.ACTIONS.map((action) => `${action}${name}${suffix}`);
 }

package/dist/commands/hook-renderer.js

@@ -0,0 +1,63 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hookRenderer = hookRenderer;
+exports.ensureQueryKeys = ensureQueryKeys;
+const path = __importStar(require("path"));
+const hook_1 = require("../templates/frontend/hook");
+const query_hook_1 = require("../templates/frontend/query-hook");
+const query_keys_1 = require("../templates/frontend/query-keys");
+const fs_1 = require("../utils/fs");
+/**
+ * Picks the hook template for the profile: TanStack Query hooks where the profile supports
+ * them, the plain useState/useEffect hook otherwise.
+ */
+function hookRenderer(ctx) {
+    return ctx.profile.queryHooks ? query_hook_1.renderQueryHook : hook_1.renderHook;
+}
+/**
+ * Ensures the shared `<feature>.keys.ts` module exists for query-hook profiles. Unlike
+ * `writeIfAbsent`, this never warns: the keys file is deliberately shared across every hook
+ * in the feature, so every `make:action`/`make:hook` call re-checking it is expected, not a
+ * skipped write worth flagging.
+ */
+function ensureQueryKeys(ctx, dir) {
+    if (!ctx.profile.queryHooks)
+        return;
+    const keysFile = path.join(dir, `${ctx.feature}.keys.ts`);
+    if ((0, fs_1.fileExists)(keysFile))
+        return;
+    (0, fs_1.writeFileSafe)(keysFile, (0, query_keys_1.renderQueryKeys)(ctx.feature));
+}

package/dist/commands/hook.js

@@ -1,52 +1,30 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeHook = makeHook;
-const path = __importStar(require("path"));
 const registry_1 = require("../stack/registry");
-const hook_1 = require("../templates/frontend/hook");
-const fs_1 = require("../utils/fs");
+const actions_1 = require("../templates/actions");
+const hints_1 = require("./hints");
+const hook_renderer_1 = require("./hook-renderer");
 const resolve_1 = require("./resolve");
-function makeHook(feature, name, pascalName) {
+const write_1 = require("./write");
+const OLD_HOOK_NAME_PATTERN = /^use[A-Z]/;
+function rejectOldHookName(feature, entity) {
+    if (!OLD_HOOK_NAME_PATTERN.test(entity))
+        return;
+    const suggestedEntity = entity.slice('use'.length);
+    throw new Error(`make:hook now takes the entity, not the hook name — try make:hook ${feature}/${suggestedEntity}.`);
+}
+function makeHook(feature, entity) {
     const ctx = (0, resolve_1.requireFeature)(feature);
     (0, registry_1.assertLayer)(ctx.profile, 'hook', 'make:hook');
-    const filePath = path.join((0, resolve_1.ensureLayerDir)(ctx, 'hook'), `${name}.ts`);
-    if ((0, fs_1.fileExists)(filePath)) {
-        throw new Error(`Hook "${name}" already exists at ${filePath}`);
+    rejectOldHookName(feature, entity);
+    const dir = (0, resolve_1.ensureLayerDir)(ctx, 'hook');
+    (0, hook_renderer_1.ensureQueryKeys)(ctx, dir);
+    const render = (0, hook_renderer_1.hookRenderer)(ctx);
+    const written = (0, write_1.writeSpecFiles)(dir, (0, actions_1.standardActions)(entity), 'hook', (spec, filePath) => render(ctx, spec, entity, filePath));
+    if (written > 0) {
+        console.log(`✅ Hooks for "${entity}" created at ${dir}`);
+        (0, hints_1.hintReactQuery)(ctx.profile);
     }
-    const entity = pascalName ?? name.replace(/^use/, '');
-    (0, fs_1.writeFileSafe)(filePath, (0, hook_1.renderHook)(ctx, name, entity, filePath));
-    console.log(`✅ Hook "${name}" created at ${filePath}`);
+    return written > 0;
 }

package/dist/commands/repository.js

@@ -1,18 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientRenderer = clientRenderer;
 exports.makeRepository = makeRepository;
 const actions_1 = require("../templates/actions");
 const server_repository_1 = require("../templates/backend/server-repository");
 const client_repository_1 = require("../templates/frontend/client-repository");
+const server_fn_repository_1 = require("../templates/frontend/server-fn-repository");
 const resolve_1 = require("./resolve");
 const sides_1 = require("./sides");
 const write_1 = require("./write");
+// Selected on the profile name, not on `queryHooks`: the two coincide today but mean different
+// things. `queryHooks` picks the hook renderer; this picks whether a server function exists to call.
+function clientRenderer(ctx) {
+    return ctx.profile.name === 'tanstack-start' ? server_fn_repository_1.renderServerFnRepository : client_repository_1.renderClientRepository;
+}
 function makeRepository(feature, name, side = 'both') {
     const ctx = (0, resolve_1.requireFeature)(feature);
     let wroteAny = false;
     for (const current of (0, sides_1.resolveSides)(ctx.profile, side, sides_1.REPOSITORY_SIDES)) {
         const dir = (0, resolve_1.ensureLayerDir)(ctx, sides_1.REPOSITORY_SIDES[current]);
-        const render = current === 'client' ? client_repository_1.renderClientRepository : server_repository_1.renderServerRepository;
+        const render = current === 'client' ? clientRenderer(ctx) : server_repository_1.renderServerRepository;
         const written = (0, write_1.writeSpecFiles)(dir, (0, actions_1.standardActions)(name), 'repository', (spec, filePath) => render(ctx, spec, name, filePath));
         if (written > 0) {
             console.log(`✅ Repositories (${current}) for "${name}" created at ${dir}`);

package/dist/init/content.js

@@ -15,6 +15,7 @@ const AGENTS_LINES = [
     'Rules the generated code follows, and that new code must keep:',
     '',
     '- One file per action per layer. `findActiveUsers` gets `FindActiveUsers.service.ts`, `FindActiveUsers.repository.ts`, and `FindActiveUsers.controller.ts`. It never goes inside `ShowUser.service.ts` or `ListUser.service.ts`.',
+    '- Hooks are one file per action too: `<Action><Entity>.hook.ts` exporting `use<Action><Entity>` (for example `useListUser`, `useCreateUser`). There is no combined `use<Entity>.ts`.',
     '- The chain is controller or hook, then service, then repository. Business logic lives in services. Data access lives in repositories. Controllers validate input and call one service.',
     '- Feature folders are kebab-case (`coffee-type`). Entity, action, and class names are PascalCase (`CoffeeType`, `FindActiveUsers`).',
     '- Generated repositories throw until you wire them to your data source. Generated controllers on Node need a line in `<feature>.routes.ts`, and on Nest need registering in `<feature>.module.ts`; the tool prints the exact line.',
@@ -34,7 +35,7 @@ const SKILL_LINES = [
     '',
     '## Detect the stack',
     '',
-    'The tool reads `package.json` and prints `Stack: <stack> (detected)` before every command. Stacks: `next-fullstack`, `next-frontend`, `react`, `node` (Express, Fastify, Hono, or none), `nest`. Override with `--stack <name>` if detection is wrong.',
+    'The tool reads `package.json` and prints `Stack: <stack> (detected)` before every command. Stacks: `next-fullstack`, `next-frontend`, `react`, `node` (Express, Fastify, Hono, or none), `nest`, `tanstack-start`. Override with `--stack <name>` if detection is wrong.',
     '',
     '## Commands',
     '',
@@ -49,10 +50,12 @@ const SKILL_LINES = [
     '| Five controllers or Next route handlers | `npx domain-driver make:controller users/User` |',
     '| A bespoke operation | `npx domain-driver make:action users/User findActiveUsers` |',
     '| Bespoke operation with a request body | `npx domain-driver make:action users/User archiveUser --with-input --returns one` |',
-    '| Component, container, hook | `npx domain-driver make:component users/UserCard`, `make:container users/UserContainer`, `make:hook users/useUser` |',
+    '| Component, container, hook | `npx domain-driver make:component users/UserCard`, `make:container users/UserContainer`, `make:hook users/User` |',
     '| Refresh this guidance | `npx domain-driver init` |',
     '',
-    'On `next-fullstack`, `make:service` and `make:repository` take `--side client|server|both` (default both).',
+    'On `next-fullstack` and `tanstack-start`, `make:service` and `make:repository` take `--side client|server|both` (default both).',
+    '',
+    'Hooks are one file per action — `<Action><Entity>.hook.ts` exporting `use<Action><Entity>` — never a combined `use<Entity>.ts`. On `tanstack-start` they are TanStack Query hooks backed by a generated `<feature>.keys.ts`; elsewhere they are plain React state.',
     '',
     '## Rules',
     '',
@@ -68,6 +71,7 @@ const SKILL_LINES = [
     '- Next.js: `app/<feature>` or `src/app/<feature>`; route handlers under `app/api/<feature>`.',
     '- React and Node: `src/features/<feature>` or `features/<feature>`.',
     '- Nest: `src/<feature>` with a `<feature>.module.ts`.',
+    '- TanStack Start: `src/routes/<feature>` or `routes/<feature>`; every layer folder is prefixed with `-` so the router ignores it, and the entry file is `index.tsx`, not `page.tsx`.',
 ];
 exports.AGENTS_SECTION = AGENTS_LINES.join('\n');
 exports.SKILL_CONTENT = `${SKILL_LINES.join('\n')}\n`;

package/dist/stack/detect.js

@@ -99,6 +99,8 @@ function parseOverride(value) {
 function inferStack(cwd, deps) {
     if (deps.has('@nestjs/core'))
         return 'nest';
+    if (deps.has('@tanstack/react-start'))
+        return 'tanstack-start';
     if (deps.has('next'))
         return hasApiDir(cwd) ? 'next-fullstack' : 'next-frontend';
     if (deps.has('react'))
@@ -121,5 +123,9 @@ function resolveFeatureRoot(cwd, stack) {
             return (0, fs_1.isDirectory)(path.join(cwd, 'src')) ? 'src/features' : 'features';
         case 'nest':
             return 'src';
+        case 'tanstack-start':
+            if ((0, fs_1.isDirectory)(path.join(cwd, 'src', 'routes')))
+                return 'src/routes';
+            return (0, fs_1.isDirectory)(path.join(cwd, 'routes')) ? 'routes' : 'src/routes';
     }
 }

package/dist/stack/profiles/nest.js

@@ -15,4 +15,5 @@ exports.nest = Object.freeze({
     },
     clientDirective: false,
     serverComponents: false,
+    queryHooks: false,
 });

package/dist/stack/profiles/next-frontend.js

@@ -25,4 +25,5 @@ exports.nextFrontend = Object.freeze({
     },
     clientDirective: true,
     serverComponents: true,
+    queryHooks: false,
 });

package/dist/stack/profiles/next-fullstack.js

@@ -41,4 +41,5 @@ exports.nextFullstack = Object.freeze({
     },
     clientDirective: true,
     serverComponents: true,
+    queryHooks: false,
 });

package/dist/stack/profiles/node.js

@@ -14,4 +14,5 @@ exports.node = Object.freeze({
     },
     clientDirective: false,
     serverComponents: false,
+    queryHooks: false,
 });

package/dist/stack/profiles/react.js

@@ -16,4 +16,5 @@ exports.react = Object.freeze({
     },
     clientDirective: false,
     serverComponents: false,
+    queryHooks: false,
 });

package/dist/stack/profiles/tanstack-start.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tanstackStart = void 0;
+exports.tanstackStart = Object.freeze({
+    name: 'tanstack-start',
+    folders: [
+        '-components',
+        '-containers',
+        '-hooks',
+        '-client/services',
+        '-client/repositories',
+        '-server/functions',
+        '-server/services',
+        '-server/repositories',
+        '-schemas',
+        '-types',
+    ],
+    layers: [
+        'page',
+        'component',
+        'container',
+        'hook',
+        'clientService',
+        'clientRepository',
+        'serverService',
+        'serverRepository',
+        'controller',
+        'schema',
+        'types',
+    ],
+    layerDirs: {
+        component: '-components',
+        container: '-containers',
+        hook: '-hooks',
+        clientService: '-client/services',
+        clientRepository: '-client/repositories',
+        serverService: '-server/services',
+        serverRepository: '-server/repositories',
+        controller: '-server/functions',
+        schema: '-schemas',
+        types: '-types',
+    },
+    clientDirective: false,
+    serverComponents: false,
+    queryHooks: true,
+});

package/dist/stack/registry.js

@@ -11,12 +11,14 @@ const next_frontend_1 = require("./profiles/next-frontend");
 const react_1 = require("./profiles/react");
 const node_1 = require("./profiles/node");
 const nest_1 = require("./profiles/nest");
+const tanstack_start_1 = require("./profiles/tanstack-start");
 const PROFILES = Object.freeze({
     'next-fullstack': next_fullstack_1.nextFullstack,
     'next-frontend': next_frontend_1.nextFrontend,
     react: react_1.react,
     node: node_1.node,
     nest: nest_1.nest,
+    'tanstack-start': tanstack_start_1.tanstackStart,
 });
 const LAYER_COMMANDS = Object.freeze({
     component: 'make:component',
@@ -45,7 +47,8 @@ function layerDir(profile, layer) {
     return dir;
 }
 function componentDir(profile, type) {
-    return profile.serverComponents ? `components/${type}` : 'components';
+    const base = layerDir(profile, 'component');
+    return profile.serverComponents ? `${base}/${type}` : base;
 }
 function availableCommands(profile) {
     const commands = profile.layers

package/dist/stack/types.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LAYERS = exports.HTTP_FRAMEWORKS = exports.STACK_NAMES = void 0;
 exports.isStackName = isStackName;
-exports.STACK_NAMES = ['next-fullstack', 'next-frontend', 'react', 'node', 'nest'];
+exports.STACK_NAMES = ['next-fullstack', 'next-frontend', 'react', 'node', 'nest', 'tanstack-start'];
 exports.HTTP_FRAMEWORKS = ['express', 'fastify', 'hono'];
 exports.LAYERS = [
     'page',

package/dist/templates/actions.js

@@ -5,6 +5,7 @@ exports.actionCase = actionCase;
 exports.standardAction = standardAction;
 exports.standardActions = standardActions;
 exports.customAction = customAction;
+exports.isQueryAction = isQueryAction;
 const naming_1 = require("../utils/naming");
 exports.ACTIONS = ['List', 'Show', 'Create', 'Update', 'Delete'];
 exports.WRITE_ACTIONS = ['Create', 'Update'];
@@ -66,3 +67,14 @@ function customAction(entity, actionName, options) {
         failure: `Failed to ${camel} ${entity}`,
     });
 }
+/**
+ * Whether a hook renders as a query (auto-fetches, returns data) rather than a mutation
+ * (triggered imperatively). `spec.method === 'get'` alone is not enough: a custom action
+ * declared `--returns void` is also a GET (no input forces GET regardless of return kind),
+ * but it has no payload worth polling for and must not auto-fire on mount. `usesEntityType`
+ * is false exactly when the action returns void, so requiring it here routes that case to
+ * the mutation branch instead.
+ */
+function isQueryAction(spec) {
+    return spec.method === 'get' && spec.usesEntityType;
+}

package/dist/templates/controllers/server-fn.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderServerFn = renderServerFn;
+const naming_1 = require("../../utils/naming");
+function inputFor(spec) {
+    if (spec.schema !== null && spec.usesId) {
+        return {
+            validator: `z.object({ id: z.string(), data: ${spec.schema}Schema })`,
+            call: 'data.id, data.data',
+            handlerArg: '{ data }',
+            needsZod: true,
+        };
+    }
+    if (spec.schema !== null) {
+        return { validator: `${spec.schema}Schema`, call: 'data', handlerArg: '{ data }', needsZod: false };
+    }
+    if (spec.usesId) {
+        return { validator: 'z.string()', call: 'data', handlerArg: '{ data }', needsZod: true };
+    }
+    return { validator: null, call: '', handlerArg: '', needsZod: false };
+}
+function renderServerFn(ctx, spec, entity, fromFile) {
+    const { validator, call, handlerArg, needsZod } = inputFor(spec);
+    const method = spec.method === 'get' ? 'GET' : 'POST';
+    const servicePath = ctx.importLayer(fromFile, 'serverService', `${spec.name}.service`);
+    const imports = ["import { createServerFn } from '@tanstack/react-start';"];
+    if (needsZod)
+        imports.push("import { z } from 'zod';");
+    if (spec.schema !== null) {
+        const schemaPath = ctx.importLayer(fromFile, 'schema', `${spec.schema}.schema`);
+        imports.push(`import { ${spec.schema}Schema } from '${schemaPath}';`);
+    }
+    imports.push(`import { ${spec.name}Service } from '${servicePath}';`);
+    const validatorLine = validator === null ? '' : `\n  .validator(${validator})`;
+    return `${imports.join('\n')}
+
+const service = new ${spec.name}Service();
+
+export const ${(0, naming_1.lowerFirst)(spec.name)} = createServerFn({ method: '${method}' })${validatorLine}
+  .handler(async (${handlerArg}) => service.handle(${call}));
+`;
+}

package/dist/templates/frontend/container.js

@@ -4,21 +4,25 @@ exports.renderContainer = renderContainer;
 const registry_1 = require("../../stack/registry");
 function renderContainer(ctx, containerName, entity, fromFile) {
     const header = ctx.profile.clientDirective ? "'use client';\n\n" : '';
-    const hookName = `use${entity}`;
-    const hookPath = ctx.importLayer(fromFile, 'hook', hookName);
+    const hookName = `useList${entity}`;
+    const hookPath = ctx.importLayer(fromFile, 'hook', `List${entity}.hook`);
     const componentPath = ctx.importFrom(fromFile, `${(0, registry_1.componentDir)(ctx.profile, 'client')}/${entity}`);
+    const query = ctx.profile.queryHooks;
+    const loadingField = query ? 'isPending' : 'loading';
+    const errorExpression = query ? '{error.message}' : '{error}';
+    const items = query ? '(data ?? [])' : 'data';
     return `${header}import { ${hookName} } from '${hookPath}';
 import ${entity} from '${componentPath}';
 
 export default function ${containerName}() {
-  const { items, loading, error } = ${hookName}();
+  const { data, ${loadingField}, error } = ${hookName}();
 
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error}</div>;
+  if (${loadingField}) return <div>Loading...</div>;
+  if (error) return <div>Error: ${errorExpression}</div>;
 
   return (
     <div>
-      {items.map((item) => (
+      {${items}.map((item) => (
         <${entity} key={item.id} {...item} />
       ))}
     </div>

package/dist/templates/frontend/hook.js

@@ -1,109 +1,93 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderHook = renderHook;
+const naming_1 = require("../../utils/naming");
 const actions_1 = require("../actions");
-function serviceImports(ctx, fromFile, entity) {
-    return actions_1.ACTIONS.map((action) => {
-        const servicePath = ctx.importLayer(fromFile, 'clientService', `${action}${entity}.service`);
-        return `import { ${action}${entity}Service } from '${servicePath}';`;
-    }).join('\n');
+const signatures_1 = require("../signatures");
+function payloadType(spec) {
+    return spec.returns.replace(/^Promise<(.*)>$/, '$1');
 }
-function serviceInstances(entity) {
-    return actions_1.ACTIONS.map((action) => `const ${action.toLowerCase()}Service = new ${action}${entity}Service();`).join('\n');
-}
-function renderHook(ctx, hookName, entity, fromFile) {
-    const header = ctx.profile.clientDirective ? "'use client';\n\n" : '';
-    const typePath = ctx.importLayer(fromFile, 'types', `${entity}.types`);
-    const createPath = ctx.importLayer(fromFile, 'schema', `Create${entity}.schema`);
-    const updatePath = ctx.importLayer(fromFile, 'schema', `Update${entity}.schema`);
-    return `${header}import { useState, useEffect, useCallback } from 'react';
-import { ${entity} } from '${typePath}';
-${serviceImports(ctx, fromFile, entity)}
-import { Create${entity} } from '${createPath}';
-import { Update${entity} } from '${updatePath}';
-
-${serviceInstances(entity)}
+function header(ctx, spec, entity, fromFile, hooks) {
+    const directive = ctx.profile.clientDirective ? "'use client';\n\n" : '';
+    const servicePath = ctx.importLayer(fromFile, 'clientService', `${spec.name}.service`);
+    const domain = (0, signatures_1.domainImports)(ctx, fromFile, spec, entity);
+    return `${directive}import { ${hooks} } from 'react';
+${domain.join('\n')}${domain.length > 0 ? '\n' : ''}import { ${spec.name}Service } from '${servicePath}';
 
-export function ${hookName}() {
-  const [items, setItems] = useState<${entity}[]>([]);
-  const [selected, setSelected] = useState<${entity} | null>(null);
+const service = new ${spec.name}Service();
+`;
+}
+function renderQuery(ctx, spec, entity, fromFile) {
+    const type = payloadType(spec);
+    const isList = type.endsWith('[]');
+    const stateType = isList ? type : `${type} | null`;
+    const initial = isList ? '[]' : 'null';
+    const deps = spec.usesId ? '[id]' : '[]';
+    return `${header(ctx, spec, entity, fromFile, 'useState, useEffect, useCallback')}
+export function use${spec.name}(${spec.params}) {
+  const [data, setData] = useState<${stateType}>(${initial});
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
-  const fetchAll = useCallback(async () => {
-    setLoading(true);
-    setError(null);
-    try {
-      const data = await listService.handle();
-      setItems(data);
-    } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : 'Failed to fetch');
-    } finally {
-      setLoading(false);
-    }
-  }, []);
-
-  const fetchOne = useCallback(async (id: string) => {
+  const refetch = useCallback(async () => {
     setLoading(true);
     setError(null);
     try {
-      const data = await showService.handle(id);
-      setSelected(data);
+      setData(await service.handle(${spec.args}));
     } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : 'Failed to fetch');
+      setError(err instanceof Error ? err.message : '${spec.failure}');
     } finally {
       setLoading(false);
     }
-  }, []);
+  }, ${deps});
 
-  const create = useCallback(async (data: Create${entity}) => {
-    setLoading(true);
-    setError(null);
-    try {
-      const created = await createService.handle(data);
-      setItems((prev) => [...prev, created]);
-      return created;
-    } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : 'Failed to create');
-      return null;
-    } finally {
-      setLoading(false);
-    }
-  }, []);
+  useEffect(() => {
+    void refetch();
+  }, [refetch]);
 
-  const update = useCallback(async (id: string, data: Update${entity}) => {
-    setLoading(true);
-    setError(null);
-    try {
-      const updated = await updateService.handle(id, data);
-      setItems((prev) => prev.map((item) => (item.id === id ? updated : item)));
-      return updated;
-    } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : 'Failed to update');
-      return null;
-    } finally {
-      setLoading(false);
-    }
-  }, []);
+  return { data, loading, error, refetch };
+}
+`;
+}
+function renderMutation(ctx, spec, entity, fromFile) {
+    const callable = (0, naming_1.lowerFirst)(spec.name);
+    const returnsValue = spec.usesEntityType;
+    const type = payloadType(spec);
+    const callbackType = returnsValue ? `(result: ${type}) => void` : '() => void';
+    const body = returnsValue
+        ? `      const result = await service.handle(${spec.args});
+      onSuccess?.(result);
+      return result;`
+        : `      await service.handle(${spec.args});
+      onSuccess?.();`;
+    const failure = returnsValue
+        ? `      setError(err instanceof Error ? err.message : '${spec.failure}');
+      return null;`
+        : `      setError(err instanceof Error ? err.message : '${spec.failure}');`;
+    return `${header(ctx, spec, entity, fromFile, 'useState, useCallback')}
+export function use${spec.name}(options: { onSuccess?: ${callbackType} } = {}) {
+  const { onSuccess } = options;
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
 
-  const remove = useCallback(async (id: string) => {
+  const ${callable} = useCallback(async (${spec.params}) => {
     setLoading(true);
     setError(null);
     try {
-      await deleteService.handle(id);
-      setItems((prev) => prev.filter((item) => item.id !== id));
+${body}
     } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : 'Failed to delete');
+${failure}
     } finally {
       setLoading(false);
     }
-  }, []);
-
-  useEffect(() => {
-    fetchAll();
-  }, [fetchAll]);
+  }, [onSuccess]);
 
-  return { items, selected, loading, error, fetchAll, fetchOne, create, update, remove };
+  return { ${callable}, loading, error };
 }
 `;
 }
+function renderHook(ctx, spec, entity, fromFile) {
+    return (0, actions_1.isQueryAction)(spec)
+        ? renderQuery(ctx, spec, entity, fromFile)
+        : renderMutation(ctx, spec, entity, fromFile);
+}

package/dist/templates/frontend/query-hook.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderQueryHook = renderQueryHook;
+const actions_1 = require("../actions");
+const signatures_1 = require("../signatures");
+const query_keys_1 = require("./query-keys");
+function preamble(ctx, spec, entity, fromFile, imported) {
+    const servicePath = ctx.importLayer(fromFile, 'clientService', `${spec.name}.service`);
+    const keysPath = ctx.importLayer(fromFile, 'hook', `${ctx.feature}.keys`);
+    const domain = (0, signatures_1.domainImports)(ctx, fromFile, spec, entity);
+    return `import { ${imported} } from '@tanstack/react-query';
+${domain.join('\n')}${domain.length > 0 ? '\n' : ''}import { ${spec.name}Service } from '${servicePath}';
+import { ${(0, query_keys_1.keysConstant)(ctx.feature)} } from '${keysPath}';
+
+const service = new ${spec.name}Service();
+`;
+}
+/**
+ * A custom GET action (e.g. `FindActiveCats`) has `usesId: false`, just like List. Testing
+ * only `usesId` would give it the exact same key as List's `all` — one cache entry shared by
+ * two hooks, with whichever observer mounts last winning the `queryFn`. `spec.path === '/'`
+ * is what actually distinguishes List from a custom action, so it is the second branch.
+ * The `[...all, name]` spread (rather than a bare `[feature, name]`) is deliberate: TanStack
+ * Query invalidates by key prefix, so a Create mutation invalidating `keys.all` still
+ * invalidates this custom list for free.
+ */
+function queryKey(ctx, spec) {
+    const keys = (0, query_keys_1.keysConstant)(ctx.feature);
+    if (spec.usesId)
+        return `${keys}.detail(id)`;
+    if (spec.path === '/')
+        return `${keys}.all`;
+    return `[...${keys}.all, '${spec.name}']`;
+}
+function renderQuery(ctx, spec, entity, fromFile) {
+    return `${preamble(ctx, spec, entity, fromFile, 'useQuery')}
+export function use${spec.name}(${spec.params}) {
+  return useQuery({
+    queryKey: ${queryKey(ctx, spec)},
+    queryFn: (): ${spec.returns} => service.handle(${spec.args}),
+  });
+}
+`;
+}
+function mutationInput(spec) {
+    if (spec.usesId && spec.schema !== null) {
+        return {
+            signature: `({ id, data }: { id: string; data: ${spec.schema} })`,
+            call: 'id, data',
+            idFrom: '{ id }',
+        };
+    }
+    if (spec.usesId)
+        return { signature: '(id: string)', call: 'id', idFrom: 'id' };
+    if (spec.schema !== null)
+        return { signature: `(data: ${spec.schema})`, call: 'data', idFrom: null };
+    return { signature: '()', call: '', idFrom: null };
+}
+function renderMutation(ctx, spec, entity, fromFile) {
+    const keys = (0, query_keys_1.keysConstant)(ctx.feature);
+    const { signature, call, idFrom } = mutationInput(spec);
+    const args = idFrom === null ? '()' : `(_result, ${idFrom})`;
+    const detail = idFrom === null
+        ? ''
+        : `\n      void queryClient.invalidateQueries({ queryKey: ${keys}.detail(id) });`;
+    return `${preamble(ctx, spec, entity, fromFile, 'useMutation, useQueryClient')}
+export function use${spec.name}() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ${signature}: ${spec.returns} => service.handle(${call}),
+    onSuccess: ${args} => {
+      void queryClient.invalidateQueries({ queryKey: ${keys}.all });${detail}
+    },
+  });
+}
+`;
+}
+function renderQueryHook(ctx, spec, entity, fromFile) {
+    return (0, actions_1.isQueryAction)(spec)
+        ? renderQuery(ctx, spec, entity, fromFile)
+        : renderMutation(ctx, spec, entity, fromFile);
+}

package/dist/templates/frontend/query-keys.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keysConstant = keysConstant;
+exports.renderQueryKeys = renderQueryKeys;
+const naming_1 = require("../../utils/naming");
+function keysConstant(feature) {
+    return `${(0, naming_1.lowerFirst)((0, naming_1.toPascalCase)(feature))}Keys`;
+}
+function renderQueryKeys(feature) {
+    return `export const ${keysConstant(feature)} = {
+  all: ['${feature}'] as const,
+  detail: (id: string) => ['${feature}', id] as const,
+};
+`;
+}

package/dist/templates/frontend/route.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderRoute = renderRoute;
+function renderRoute(ctx, entity, fromFile, withContainer) {
+    const head = `import { createFileRoute } from '@tanstack/react-router';`;
+    const routeBlock = `export const Route = createFileRoute('/${ctx.feature}/')({
+  component: ${entity}Page,
+});`;
+    if (!withContainer) {
+        return `${head}
+
+${routeBlock}
+
+function ${entity}Page() {
+  return (
+    <div>
+      <h1>${entity}</h1>
+    </div>
+  );
+}
+`;
+    }
+    const containerPath = ctx.importLayer(fromFile, 'container', `${entity}Container`);
+    return `${head}
+import ${entity}Container from '${containerPath}';
+
+${routeBlock}
+
+function ${entity}Page() {
+  return <${entity}Container />;
+}
+`;
+}

package/dist/templates/frontend/server-fn-repository.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderServerFnRepository = renderServerFnRepository;
+const naming_1 = require("../../utils/naming");
+const signatures_1 = require("../signatures");
+function callArgument(spec) {
+    if (spec.usesId && spec.schema !== null)
+        return '({ data: { id, data } })';
+    if (spec.usesId)
+        return '({ data: id })';
+    if (spec.schema !== null)
+        return '({ data })';
+    return '()';
+}
+function renderServerFnRepository(ctx, spec, entity, fromFile) {
+    const fnName = (0, naming_1.lowerFirst)(spec.name);
+    const fnPath = ctx.importLayer(fromFile, 'controller', `${spec.name}.fn`);
+    const imports = [...(0, signatures_1.domainImports)(ctx, fromFile, spec, entity), `import { ${fnName} } from '${fnPath}';`];
+    return `${imports.join('\n')}
+
+export class ${spec.name}Repository {
+  async handle(${spec.params}): ${spec.returns} {
+    return ${fnName}${callArgument(spec)};
+  }
+}
+`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "domain-driver",
-  "version": "0.3.0",
-  "description": "CLI scaffolding tool for domain-driven feature folders in Next.js, React, Node, and NestJS projects, with per-action files, bespoke actions, and agent guidance",
+  "version": "0.4.0",
+  "description": "CLI scaffolding tool for domain-driven feature folders in Next.js, React, Node, NestJS, and TanStack Start projects, with per-action files, bespoke actions, and agent guidance",
   "main": "dist/index.js",
   "bin": {
     "domain-driver": "./dist/index.js"
@@ -18,6 +18,7 @@
     "build": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "typecheck:tanstack-fixture": "node scripts/typecheck-tanstack-fixture.js",
     "postinstall": "node ./scripts/postinstall.js"
   },
   "keywords": [
@@ -30,12 +31,14 @@
     "node",
     "express",
     "fastify",
-    "hono"
+    "hono",
+    "tanstack",
+    "tanstack-start"
   ],
   "author": "Isaac Hatilima",
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",