domain-driver 0.3.1 → 0.4.1

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.
 
 ---
 
@@ -23,12 +23,13 @@ npx domain-driver make:feature <feature>[/<Entity>]
 Every command reads your `package.json` once and prints the stack it found before writing anything:
 
 ```
-Stack: next-fullstack (detected)
+Stack: next-fullstack (detected), root: src/app
 ```
 
 | Stack | Detected when | Features live in |
 |---|---|---|
-| `nest` | `@nestjs/core` is a dependency | `src/<feature>` |
+| `nest` | `@nestjs/core` is a dependency | `src/features/<feature>` if `src/features` exists, otherwise `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>` |
@@ -42,23 +43,51 @@ Override detection with `--stack`:
 domain-driver --stack nest make:feature cat -a
 ```
 
+### Choosing where features live
+
+The "Features live in" column is a convention, not a rule. Two overrides take precedence over it, in this order.
+
+`--root` wins over everything, and suits one-off scaffolding:
+
+```bash
+domain-driver --root src/modules make:feature billing/Billing -a
+```
+
+For a project you work in daily, set it once in `package.json` instead of retyping the flag on every command:
+
+```json
+{
+  "domainDriver": {
+    "featureRoot": "src/modules"
+  }
+}
+```
+
+Either way the stack line tells you which one won, so you can see where files will land before they land:
+
+```
+Stack: nest (detected), root: src/modules (package.json)
+```
+
+The root must be a relative path inside the project. An absolute path or one containing `..` is rejected rather than quietly normalised.
+
 ---
 
 ## 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 +98,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 +124,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 +134,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 +143,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 +159,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 +238,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 +305,29 @@ The cache lives in `~/.cache/domain-driver` (or `$XDG_CACHE_HOME/domain-driver`)
 
 ---
 
+## Upgrading from 0.4.0
+
+Two changes affect existing projects.
+
+On NestJS, a project that already has a `src/features` directory now scaffolds into it instead of directly into `src`. If you keep features in `src` you are unaffected, since the behaviour is opt-in by that directory existing. To pin either choice explicitly, set `domainDriver.featureRoot` in `package.json`.
+
+The entity half of a `<feature>/<Entity>` target must now be PascalCase. `make:schema users/user` previously produced `Listuser.service.ts` exporting `ListuserService`; it now fails with a message telling you to pass `User`.
+
+---
+
+## 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.
@@ -255,6 +352,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 +363,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

@@ -78,7 +78,8 @@ function createProgram(deps) {
         .name('domain-driver')
         .description('CLI scaffolding tool for domain-driven feature folders in Next.js, React, Node, and NestJS projects')
         .version(deps.current)
-        .option('--stack <name>', `Override stack detection (${types_2.STACK_NAMES.join(', ')})`);
+        .option('--stack <name>', `Override stack detection (${types_2.STACK_NAMES.join(', ')})`)
+        .option('--root <dir>', 'Override where feature folders are created, for example src/features');
     let pendingNotice = Promise.resolve(null);
     program.hook('preAction', (_thisCommand, actionCommand) => {
         const name = actionCommand.name();
@@ -93,8 +94,8 @@ function createProgram(deps) {
         }
         if (SKIP_DETECTION.has(name))
             return;
-        const { stack } = program.opts();
-        deps.log((0, detect_1.describeStack)((0, detect_1.detectStack)(stack)));
+        const { stack, root } = program.opts();
+        deps.log((0, detect_1.describeStack)((0, detect_1.detectStack)(stack, root)));
     });
     program.hook('postAction', async () => {
         const notice = await pendingNotice;
@@ -126,7 +127,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}`);