\n\nScaffold Next.js full-stack modules in seconds with **Next Zod Modules Toolkit (NZMT)**. \n\nGet a domain-focused architecture with a contract-first approach out of the box.\n\nBatteries included! ✨\n\n\n# Try it!\n\n(stackblitz may not work on Safari)\n\nhttps://stackblitz.com/edit/nzmt-playground\n\n# What you get\n\nAfter installing and initializing NZMT, run one CLI command to generate a production-ready backend with React Query hooks:\n\n```bash\nnpx nzmt crud-api user\n```\n\nThis will instantly scaffold:\n\n```bash\nserver/\n entities/user/... # user entity\n stores/user/... # user stores (contract, in-memory, prisma)\n services/user/... # service\n controllers/user/... # API controller\n\napp/api/user/... # api routes\n\nui/shared/queries/user/... # react queries\n```\n\nFeatures DI, logging, in-memory stores, unified errors, and endpoint guards. Everything is ready after a few tweaks — see `Quick start with Prisma` for details.\n\nAll code is editable — scaffold parts individually or together. You can also scaffold front-end widgets. CLI commands are listed in `CLI commands glossary`. \n\n\n# Quick start with Prisma\n\nAssuming you have \n\n- `Next.js` project with a generated `Prisma` client\n- some `User` schema in your `Prisma` client\n- enabled `experimentalDecorators` and `emitDecoratorMetadata` in `compilerOptions` section of `tsconfig.json`\n- configured `@tanstack/react-query`\n\n## Setup\n\n```bash\n# install NZMT and peer dependencies\nnpm i inversify zod reflect-metadata @alevnyacow/nzmt\n\n# initialize NZMT with absolute prisma client path\nnpx nzmt init prismaClientPath:@/generated/prisma/client\n```\n\nThen plug your `Prisma` adapter in scaffolded `/server/infrastructure/prisma/client.ts` file.\n\n## Scaffolding CRUD operations for `User`\n\n```bash\nnpx nzmt crud-api user\n```\n\nThis command scaffolds:\n\n- `User` entity\n- `UserStore` (with Prisma + RAM implementations)\n- `UserService` (ready to be used in Server Actions)\n- `UserController` proxying UserService methods\n- `API routes` for UserController endpoints\n- `React Query hooks` for fetching UserController from client-side\n\nThen tweak a few files:\n\n- `/domain/entities/user/user.entity.ts` → entity schema\n- `/server/stores/user/user.store.ts` → store schemas (if default schemas do not fit your needs)\n- `/server/stores/user/user.store.prisma.ts` → map `UserStore` contracts to Prisma client contracts\n\nAnd after only one command and a few tweaks you have ready-to-use React Query hooks & Server Actions backend.\n\n## Using scaffolded React query hooks\n\n```\nSchema: Client → React Query → API → Controller → Service → Store → DB\n```\n\n```tsx\n'use client'\n\nimport { UserQueries } from '@/ui/shared/queries/user';\n\nexport default function Page() {\n const { mutate: addUser } = UserQueries.usePOST()\n const { data, isFetching } = UserQueries.useGET({ query: {} })\n\n const addRandomUser = () => {\n addUser({ body: { payload: { name: `${Math.random()}` } } })\n }\n\n return (\n
\n );\n}\n\n```\n\n## Using scaffolded Service methods as Next server actions\n\n```\nSchema: Server Action → Service → Store → DB\n```\n\n```tsx\n'use server'\n\nimport { fromDI } from '@/server/di'\nimport type { UserService } from '@/server/services/user'\n\nexport default async function Page() {\n /**\n * FYI: `fromDI` argument is strongly typed and\n * this type automatically updates after you scaffold\n * anything. Cool, right?\n */ \n const userService = fromDI('UserService')\n\n const user1 = await userService.getDetails({ \n filter: { id: 'user-1-id' } \n })\n\n return
{JSON.stringify(user1)}
\n}\n```\n\n# CLI commands glossary\n\n## Initialization\n\n| Command | Scaffolding result | Options |\n| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------- |\n| `npx nzmt init` | **init**ialization | pass `prismaClientPath:` to work with Prisma. E.g. `npx nzmt init prismaClientPath:@/generated/prisma/client` |\n\n## Complex scaffolding\n\n| Command | Scaffolding result |\n| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `npx nzmt crud-api ` | CRUD via Server Actions and React Query hooks. |\n| `npx nzmt crud-service ` | CRUD via Server Actions (no Controllers, API Routes and React Query hooks). |\n| `npx nzmt se ` | **s**tored **e**ntity: entity + store (contracts linked). |\n| `npx nzmt rq` | API **r**outes and React **q**ueries for all of your controllers. This command will also remove endpoints which don't exist anymore with according React query hooks |\n\n## Primary server modules scaffolding\n\n| Command | Scaffolding result | Options |\n| -------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `npx nzmt e ` | **e**ntity | |\n| `npx nzmt vo ` | **v**alue **o**bject | |\n| `npx nzmt cs ` | **c**ustom **s**tore (all schemas are `z.object({})`) | |\n| `npx nzmt s ` | **s**ervice | `i:UserStore,Logger` will automatically inject `UserStore` and `Logger`. E.g. `npx nzmt s shop i:UserStore,ProductStore` will create `ShopService` with already injected `UserStore` and `ProductStore` |\n| `npx nzmt c ` | **c**ontroller | `i:UserService` will automatically inject `UserService`. `Logger` and `Guards` are injected by default regardless of `i:` option |\n\n## Auxiliary server modules scaffolding\n\n| Command | Scaffolding result |\n| ------------------- | ------------------------- |\n| `npx nzmt p ` | **p**rovider |\n| `npx nzmt i ` | **i**nfrastructure module |\n\n## UI modules scaffolding\n\n| Command | Scaffolding result |\n| ------------------- | ------------------------- |\n| `npx nzmt w ` | **w**idget |\n| `npx nzmt lw ` | **l**ayouted **w**idget - widget with separated view layout |\n\n# How to implement your own methods\n\n## Zod schemas (module contracts)\n\nServer method contracts are defined with Zod schemas in files like `user.controller.metadata.ts` or `product.service.metadata.ts`.\n\nThey:\n\n- validate data at runtime\n- can be reused across layers (no separate DTOs needed)\n- automatically infer types (no manual TypeScript work)\n\nService method description example:\n\n```ts\n// ...some service metadata\norderDetails: {\n payload: Order.schema.pick({ \n name: true, \n createdDate: true \n }),\n response: z.object({\n user: User.schema,\n products: z.array(\n Product.schema.omit({ \n price: true \n })\n )\n })\n}\n// ...some service metadata\n```\n\n## Services\n\n1. **Define method in metadata** (`*.service.metadata.ts`):\n\n```ts\n// ...service metadata\nfoo: {\n request: z.object({ str: z.string() }),\n response: z.object({ num: z.number() })\n}\n// ...service metadata\n```\n\n2. **Implement it in service** (`*.service.ts`):\n\n```ts\n// ...service class implementation\nfoo = this.methods('foo', async ({ str }) => {\n // 'foo' string is strongly-typed, don't worry\n // all input and output types are also infered\n return { num: Number(str) }\n})\n// ..service class implementation\n```\n\n### Usage\n\nService methods can be used like a usual method of signature `(data: Request) => Promise`. E.g.\n\n```ts\nconst { num } = await someMethod.foo({ str: '25' })\n```\n\n## Controllers\n\nSame idea, but metadata uses optional `query` and optional `body` instead of abstract `request`.\n\n1. **Metadata** (`*.controller.metadata.ts`):\n\n```ts\n// ...controller metadata\nPOST: {\n query: z.object({ id: z.string() }),\n body: z.object({ delta: z.number() }),\n response: z.object({ success: z.boolean() })\n}\n// ...controller metadata\n```\n\n2. **Implementation** (`*.controller.ts`):\n\n`query` and `body` are merged into one object in implementation:\n\n```ts\n// ...controller class implementation\nPOST = this.endpoints('POST', async ({ id, delta }) => {\n return { success: true }\n})\n// ..controller class implementation\n```\n\n### React-queries and API routes\n\nOnce you done implementing controller methods, just run `nmx nzmt rq`. This command will generate up-to-date API routes and React Query hooks for all your controllers. You can call it also, for example, in a pre-commit hook so that your backend and frontend integration is always kept in sync.\n\n# FAQ\n\n## Why not use Nest or tRPC?\n\n`NZMT` combines the best of both worlds in one package while staying in plain Next.js:\n\n| Feature | NZMT | tRPC | Nest |\n| ---------------------- | --------------------------------------------- | ------ | ------------------------------- |\n| Architecture | contract-first, domain-focused | ❌ | module-centric, tightly coupled |\n| Learning curve | Medium | Low | High |\n| Type safety | ✅ - including run-time checks out of the box | ✅ | ⚠️ |\n| Scaffolding | ✅ - production-ready full-stack | ❌ | ⚠️ |\n| Boilerplate | ✅ - Low | ✅ | ❌ - High |\n| No framework lock-in | ✅ | ✅ | ❌ |\n| Single source of truth | ✅ (schemas) | ⚠️ | ❌ |\n| Time to first feature | ✅ instant full-stack | ⚡ fast | 🐢 slow |\n| Code ownership | ✅ full (generated, editable) | ✅ | ⚠️ (framework patterns) |\n\n\n## What does domain-focused mean?\n\nNZMT puts your business domain first. Entities drive the architecture, so backend and frontend stay consistent.\n\n## What does contract-first mean?\n\nThe behavior of all server modules in NZMT is governed by Zod schemas. Function signatures and entity contracts are derived from these schemas. There is also automatic runtime validation to ensure that all data — function arguments and entity models — conform to their schemas.\n\n## Can I tweak scaffolded files?\n\nYes — everything is fully editable, including configuration. Think of NZMT as a shadcn-style approach for full-stack: scaffold first, then fully own the code. Moreover, in most of the cases your changes are preserved on subsequent generations. For example, if you modify a generated query and run `npx nzmt rq` later, your edits stay intact.\n\n## Do I really need to understand DI and other fancy concepts to use NZMT effectively?\n\nNot really. NZMT handles dependency injection (DI) for you using `inversifyjs`. You don’t need to set it up manually.\nTo get an instance of a service anywhere in your server code, just use:\n\n```tsx\nimport { fromDI } from '@/server/di'\n\nconst userService = fromDI('UserService')\n```\n\nHere, `fromDI` is strongly typed — your IDE will give autocomplete automatically.\n\n## Why data layer modules are called `Stores` and not `Repositories`?\n\nA “Repository” is a specific design pattern for managing data. NZMT prefers Stores — a simple, flexible abstraction for your data layer that can adapt to your needs regardless of the specific pattern. This approach helps to keep your code simple, and it has been successfully used in other languages, like Go.","readmeFilename":"README.md"}
\n
\n 