react-domain-architecture
/react-domain-architecture
Use when creating, moving, or naming files in a plain React app (Vite or similar SPA, no Next.js/Remix) organized by business domain, with a modules/ folder and a core/ folder outside it. Best for mid to large apps and teams. Covers module layout, public APIs, import boundaries, config, tests, and growth.
- Author
- htmujahid ↗
- Repository
- project-structure-skills ↗
- Licence
- MIT
- Last repository change
- 02.11.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when creating, moving, or naming files in a plain React app (Vite or similar SPA, no Next.js/Remix) organized by business domain, with a modules/ folder and a core/ folder outside it. Best for mid to large apps and teams. Covers module layout, public APIs, import boundaries, config, tests, and growth.
Original author description
Use when creating, moving, or naming files in a plain React app (Vite or similar SPA, no Next.js/Remix) organized by business domain, with a modules/ folder and a core/ folder outside it. Best for mid to large apps and teams. Covers module layout, public APIs, import boundaries, config, tests, and growth.
How it works
- Target version
- Follow the repo first
- Default directory layout
- Naming conventions
- Dependency direction
- Where things live
- Tests
- Structure at three sizes
- Anti-patterns
SKILL.md preview
---
name: react-domain-architecture
description: Use when creating, moving, or naming files in a plain React app (Vite or similar SPA, no Next.js/Remix) organized by business domain, with a modules/ folder and a core/ folder outside it. Best for mid to large apps and teams. Covers module layout, public APIs, import boundaries, config, tests, and growth.
license: MIT
---
# React domain architecture
Plain React single-page app, grouped by business domain. Server data is handled with TanStack Query (or a similar query client). Each domain is a module. Shared infrastructure lives in `core/`, outside `modules/`.
## Target version
Written for React 19 with TypeScript and Vite on 2026-10-29. Applies to any client-only React setup. Not for meta-frameworks (Next.js, Remix). For small apps, use `react-layered-architecture` instead.
## Follow the repo first
Read `src/modules/` and `src/core/` before creating files. If the project already has conventions (module names, casing, import alias, lint boundaries), use them. Check `tsconfig.json` for aliases and the lint config for import rules.
## Default directory layout
```
src/
main.tsx # entry: mounts <App />
app.tsx # composes core providers and the router
core/ # infrastructure with no business logic
app/ # providers, router, route composition
api/ # HTTP client, QueryClient setup, error types
config/ # env parsing and constants
ui/ # design-system primitives (Button, Modal)
hooks/ # generic hooks (useDebounce)
lib/ # pure helpers
store/ # app-wide client state (auth session, theme)
types/ # shared generic types
styles/ # global CSS and tokens
test/ # test setup and shared helpers
modules/ # one folder per business domain
<module>/
```
Read [references/full-tree.md](references/full-tree.md) when you need the expanded tree, including module internals.
### Module layout
```
modules/invoices/
index.ts # public API: the only file others may import
routes.tsx # route objects for this module
pages/ # route-level components
components/ # module-private UI
hooks/ # module-private hooks
queries/ # query and mutation hooks, query keys, request functions
types/ # module types
```
- Start flat: put files in the module root. Add subfolders once the module passes about 8 files.
- Export from `index.ts` only what other modules or `core/app` need.
## Naming conventions
- Modules: kebab-case domain nouns, such as `invoices` or `user-profile`.
- Files and folders: kebab-case for everything, such as `invoice-table.tsx` and `use-invoices.ts`. Do not mix casing.
- Components: the export is PascalCase and the file is its kebab-case form: `InvoiceTable` in `invoice-table.tsx`.
- Exports: use named exports. Avoid default exports.
- Hooks: `use-thing.ts` for UI logic. Data hooks go in queries, not `hooks/`. Queries: `invoice.queries.ts`, exporting `invoiceKeys`, `useInvoices`, `useCreateInvoice`. Types: `invoice.types.ts`.
- Routes: pages are `invoice-list-page.tsx`. URL paths are kebab-case.
- Do not repeat the module name in file names inside the module, unless the name is the domain entity.
- Imports: use `@/core/...` and `@/modules/...`. Never use `../../..`.
## Dependency direction
```
main -> core/app -> modules -> core
```
- `core` never imports from `modules`.
- A module imports `core` freely.
- A module imports another module only through that module's `index.ts`.
- Never import another module's internal files.
- Prefer composing two modules in a page in `core/app` over coupling them. Avoid circular module imports.
- Move code to `core` only when 3+ modules need it and it has no domain meaning.
## Where things live
- Config: `core/config/`. Read `import.meta.env` only in `core/config/env.ts`.
- Env vars: prefix with `VITE_`. List every var in `.env.example` at the repo root.
- Shared types: generic ones in `core/types/`. Domain types in the owning module's `types/`.
- Query client: create it in `core/api/query-client.ts`. Mount the provider in `core/app`.
- Global state: app-wide state in `core/store/`. Domain state in the owning module. Keep UI state local.
## Tests
- Put tests next to the file: `invoice-table.tsx`, `invoice-table.test.tsx`.
- Put test setup and shared helpers in `core/test/`.
- Test a module through its public API when possible.
- Put end-to-end tests in `e2e/` at the repo root, grouped by module name.
## Structure at three sizes
Read [references/growth-stages.md](references/growth-stages.md) when deciding whether to restructure.
### Prototype
Use `react-layered-architecture` or a flat `src/`. Do not start with modules for a single screen.
### Mid-size
Use `core/` plus 2 to 6 flat modules.
Signal to move up: a module passes about 20 files, two teams edit one module, or modules import each other's internals.
### Large
Give big modules subfolders. Enforce boundaries with lint rules. Split a module into submodules when it holds two domains.
Signal to extract packages: a second app needs `core/`.
## Anti-patterns
Read [references/anti-patterns.md](references/anti-patterns.md) when reviewing a layout or before moving files.
- Do not import `modules/` from `core/`.
- Do not deep-import `modules/x/components/Y`. Import from `modules/x`.
- Do not create a `shared/` or `common/` folder inside or beside `modules/`.
- Do not put domain logic in `core/`.
- Do not create a module per page. A module is a domain.
- Do not re-export everything from `index.ts`.
- Do not share state between modules through globals. Pass it through props or `core/store`.
- Do not write query keys inline. Use the module's key factory.
- Do not copy query data into `useState` or `core/store`.
- Do not use deep relative imports. Use aliases.
- Do not use PascalCase or camelCase file names, or rename a file only to change its case.
Files in this package (4)
- SKILL.md 6 KB
- references/anti-patterns.md 2 KB
- references/full-tree.md 2 KB
- references/growth-stages.md 1 KB
Versions
The database has no other skills named react-domain-architecture.
Database snapshot: 13.11.2026 · package version 53e743821e3f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100react-layered-architecture
Use when creating, moving, or naming files in a plain React app (Vite or similar SPA, no Next.js/Remix) organized by technical layer (pages, components, hooks, queries). Best for small to mid-size apps. Covers layout, naming, import direction, config, tests, and when to move to… - 100nextjs-domain-architecture
Use when creating, moving, or naming files in a full-stack Next.js App Router app organized by business domain, with route groups per domain, underscore-prefixed private folders (_components, _actions, _queries), server actions, and TanStack Query. Best for large apps and teams.… - 100vite-react-best-practices
Comprehensive React 19 and Vite 8 SPA performance, architecture, and deployment guidelines. Use this skill when building, reviewing, or refactoring React applications built with Vite (SPA). Covers Vite 8 build and static hosting requirements, React Router 8 route-level code… - 90react-architecture
Use this skill when the user says 'React structure', 'React architecture', 'React folder', 'React component pattern', 'React hooks architecture', 'React clean arch', 'feature-based React', 'React project layout', or when structuring a React application. This skill enforces:… - 95auth0-react
Use when adding authentication to React applications (login, logout, user sessions, protected routes) - integrates @auth0/auth0-react SDK for SPAs with Vite or Create React App - 86add-page
Add a page to this React SPA that reads from the external API, with its route, query, fake-API handler and tests. Use when asked for a new screen, route or view backed by an API endpoint.