zakarya

Production-grade frontend framework generator for Next.js (App Router) TanStack Query · Axios · TypeScript Strict · Feature-Based Architecture

Table of Contents

1. Philosophy
2. CLI Architecture
3. Internal Folder Structure
4. Installation
5. Commands
   • zakarya create
   • zakarya generate feature
   • zakarya generate resource
   • zakarya doctor
6. Generated Project Architecture
7. Generator Engine Design
8. Complete Generated Feature Example
9. zakarya.config.json Reference
10. Plugin System
11. Safety System
12. Naming Convention Engine
13. Dependency Rules
14. Evolution Roadmap

Philosophy

zakarya is not a template copier. It is a frontend framework generation system.

It exists to solve the #1 scaling problem in frontend engineering teams: architectural drift.

When five engineers start five features, they produce five different patterns — different folder names, different query strategies, different error handling approaches, different import paths. Three months later, the codebase is an archaeology site.

zakarya enforces a single, opinionated, machine-verified architecture. Every feature generated by zakarya is:

• Isolated — cannot import from another feature
• Predictable — identical internal structure, always
• Consistent — same naming conventions, same query patterns, same service contract
• Safe — no accidental overwrites, backup before every mutation
• Extensible — plugins can add new generator types without touching core

CLI Architecture

zakarya (CLI entry)
│
├── commands/              ← Commander.js command registrations
│   ├── create.ts          ← zakarya create <n>
│   ├── init.ts            ← zakarya init <n> (alias)
│   ├── generate.ts        ← zakarya generate feature|resource
│   └── doctor.ts          ← zakarya doctor (arch validation)
│
├── generators/            ← Core generation logic
│   ├── project.generator.ts   ← Scaffolds full Next.js project
│   ├── feature.generator.ts   ← Generates isolated feature module
│   └── resource.generator.ts  ← CRUD resource with smart presets
│
├── engine/                ← Generation primitives
│   ├── naming.engine.ts   ← All naming conventions (camel/pascal/kebab/…)
│   ├── template.engine.ts ← {{VAR}} interpolation + #if/#each blocks
│   └── injection.engine.ts← Safe code injection into existing files
│
├── templates/             ← Code templates per layer
│   ├── feature/           ← types/service/queries/mutations/hooks templates
│   └── project/           ← shared layer / app / config templates
│
├── config/
│   ├── config.types.ts    ← ZakaryaConfig interface + DEFAULT_CONFIG
│   └── config.resolver.ts ← Reads & deep-merges zakarya.config.json
│
├── plugins/
│   └── plugin.system.ts   ← Plugin contract, registry, loader
│
├── safety/
│   └── safety.system.ts   ← Backup-before-overwrite, confirm gates
│
└── utils/
    ├── banner.ts           ← ASCII art banner
    └── package.ts          ← Reads CLI version from package.json

... (README truncated for brevity)