ak-architecture

Scaffold a React (Vite) or Next.js project with a real architecture that is ready to build on: a choice of folder structures, a typed React Query + Axios API layer, optional auth with cookie-based tokens, global state, i18n, multiple themes and architecture rules enforced by ESLint.

npx ak-architecture my-app     # new folder
npx ak-architecture .          # the current folder, the project is named after it

Questions

| Question | Options | | --- | --- | | Project name | a folder name or path, . for the current directory | | Framework | Next.js (App Router), React (Vite + React Router) | | Folder structure | Modular (default), Feature-Sliced Design, Layered | | UI library | shadcn/ui, Ant Design, none | | Tailwind CSS | yes / no (always on with shadcn/ui) | | Global state | Zustand, Redux Toolkit | | Authentication | yes (default) / no: login page, cookie tokens and route guards | | Node.js version | 20, 22, 24, 26 (default: the one running the CLI) | | How many languages? | a number, then the language codes (first is the default) | | How many themes? | a number, then the theme names (first is the default) |

With authentication, tokens are always stored in cookies — this is not a question. Without it, the project has no login page, token store or route guards, and the API layer sends requests without a token.

The project name works like in create-vite:

• . scaffolds into the current directory and names the project after the folder.
• A folder name that is not a valid npm package name (My Project) is converted (my-project) and you can edit the suggestion.
• A folder that is not empty asks what to do: cancel, keep the existing files (same-named files are overwritten and listed afterwards) or remove them. .git is always kept.

Every answer can also be passed as a flag, which skips that question:

npx ak-architecture my-app \
  --framework next --structure fsd --ui shadcn --state zustand --no-auth \
  --node 22 --locales uz,ru,en --themes light,dark

| Flag | Description | | --- | --- | | --framework <next\|react> | Framework | | --structure <modular\|fsd\|layered> | Folder structure | | --ui <shadcn\|antd\|none> | Component library | | --tailwind / --no-tailwind | Tailwind CSS | | --state <zustand\|redux> | Global client state | | --auth / --no-auth | Login page, cookie tokens and route guards | | --node <20\|22\|24\|26> | Node.js version the project targets | | --locales <codes> | Comma-separated language codes, first is default | | --themes <names> | Comma-separated theme names, first is default | | --no-install | Skip installing dependencies | | --no-git | Skip git init | | -y, --yes | Use defaults for every question not passed as a flag |

Folder structures

All three structures contain the same code and the same features. They differ in where the files live, how imports are allowed to flow, and which rules ESLint enforces.

Modular (default)

Feature modules on top of shared technical layers, the approach popularised by bulletproof-react. The best default for most apps and teams.

src/
├── app/          Next.js App Router adapters, or the React router, guards and providers
├── pages/        Screen components (src/screens in Next.js projects)
├── components/   ui/ (primitives), layout/ (Header, switchers), shared/ (reused composites)
├── modules/      Feature modules: <feature>/{components,hooks,types} + index.ts public API
├── hooks/        useGet / useSend (generic React Query hooks), useTheme
├── services/     request.ts (axios, token refresh on 401), api.ts (typed verbs)
├── store/        Zustand store or Redux Toolkit slice
├── constants/  types/  utils/  lib/  locales/  styles/

app → pages → modules → shared layers. Modules never import each other and are imported only through their index.ts.

Feature-Sliced Design

Feature-Sliced Design is a formal methodology with its own linter. For large, long-lived products and teams that want a standard everybody can look up.

src/
├── app/          App.tsx, providers/, routes/, styles/ (store/ with Redux)
├── pages/        One slice per route: <page>/ui + index.ts. Page-only code stays here
├── features/     Reused user actions: <feature>/{ui,model,api} + index.ts
├── entities/     Business entities: <entity>/{ui,model,api} + index.ts
└── shared/       api/  config/  routes/  i18n/  lib/  ui/

• app → pages → features → entities → shared, slices never import their neighbours, everything is imported through a public API.
• Follows the current FSD docs: no widgets layer (discouraged for new projects), "pages first", ambient RootState / AppDispatch types so shared never imports the Redux store from app.
• Next.js projects use the layout from the FSD guide for Next.js: the App Router folder app/ (and proxy.ts with auth) in the project root, FSD layers in src/ with _app and _pages prefixed so Next.js never mistakes them for routers.
• Ships Steiger, the official FSD linter, as npm run lint:fsd.

Layered

Classic group-by-type. Small apps, prototypes, solo projects, and everyone who wants zero ceremony.

src/
├── app/  pages/
├── components/   ui/  layout/  shared/  <domain>/ (auth/LoginForm)
├── hooks/        useGet, useSend, useTheme, <domain>/ (auth/useLogin)
├── services/  store/  constants/  lib/  utils/  locales/  styles/
└── types/        api.ts, <domain>.ts (auth.ts)

app → pages → components → hooks → services / store / lib. Hooks, services, store and lib never import components.

What every project gets

• App.tsx in React projects: main.tsx mounts <App />, which composes the providers and the router.
• Node.js version: engines in package.json, .nvmrc and the matching @types/node. The minimum of each line comes from the generated stack (Vite 8 and ESLint 10 need 20.19+ / 22.13+), which is also why Node.js 18 is not offered: React Router 7 and Tailwind CSS 4 do not run on it.
• Auth (unless --no-auth): access and refresh tokens live in cookies. The axios instance attaches the token, refreshes it once on a 401 (one shared refresh for parallel requests) and logs out when the refresh fails. Next.js projects guard routes in proxy.ts, React projects in router loaders.
• Themes: every theme is a [data-theme] block of CSS variables (shadcn/ui compatible). The chosen theme is kept in the global store and a cookie, so Next.js renders the right theme on the server with no flash. Ant Design projects get a matching ConfigProvider theme per name.
• i18n: next-intl (Next.js) or react-i18next (React), locale stored in a cookie, translation keys typed.
• Architecture rules in ESLint, written for the chosen structure: import direction, public APIs, no axios outside the API layer, no useQuery / useMutation outside useGet / useSend.
• README.md and CLAUDE.md that describe the chosen structure, so people and AI assistants follow it.

Requirements

Node.js 20.12+ to run the CLI. Generated projects need 20.19+, 22.13+, 24+ or 26+ depending on the Node.js version you pick.

Development

npm install
npm run dev -- my-app --no-install   # run the CLI from source
npm test                             # unit tests, every structure x framework x UI x state combination
npm run test:e2e                     # generates real projects and runs their typecheck, lint and build
npm run build

Templates are written once, against the modular layout (src/templates). A structure (src/structure) is a list of moves from modular paths to its own paths plus its public API folders; imports are rewritten to match and every import is checked to resolve to a generated file.

License

MIT