Skip to content
Skills Library
Programming · Planning

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.

Licence
MIT
Last repository change
02.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.

Licence

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

  1. Target version
  2. Follow the repo first
  3. Default directory layout
  4. Naming conventions
  5. Dependency direction
  6. Where things live
  7. Tests
  8. Structure at three sizes
  9. Anti-patterns
Original SKILL.md headings · 125 lines, 814 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.