create-m5kdev 0.28.8 → 0.28.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
Guidance for Claude Code when working in this repository.
|
|
4
|
+
|
|
5
|
+
## About This App
|
|
6
|
+
|
|
7
|
+
**{{APP_NAME}}** — {{APP_DESCRIPTION}}
|
|
8
|
+
|
|
9
|
+
This is a pnpm + Turborepo monorepo built on the **m5kdev framework**:
|
|
10
|
+
|
|
11
|
+
- `@m5kdev/backend` — backend kernel: Express, Better Auth, Drizzle (LibSQL), and tRPC. Apps compose it via `createBackendApp(config, [modules])`.
|
|
12
|
+
- `@m5kdev/commons` — shared runtime utilities and contracts.
|
|
13
|
+
- `@m5kdev/config` — configuration loading and validation.
|
|
14
|
+
- `@m5kdev/email` — email rendering and local delivery used by auth flows.
|
|
15
|
+
// m5k:webapp:start
|
|
16
|
+
- `@m5kdev/frontend` — framework-level React providers (`AppConfigProvider`, `AppTrpcQueryProvider`) and hooks.
|
|
17
|
+
- `@m5kdev/web-ui` — web UI components built on HeroUI v3.
|
|
18
|
+
// m5k:webapp:end
|
|
19
|
+
|
|
20
|
+
The framework owns the plumbing (auth, database wiring, tRPC composition, permissions); app code supplies modules and screens that follow the conventions below.
|
|
21
|
+
|
|
22
|
+
## Workspace
|
|
23
|
+
|
|
24
|
+
- `apps/shared` — shared Zod schemas, constants, and the `.env` file every app reads.
|
|
25
|
+
- `apps/server` — backend composition root (`src/app.ts`), app modules (`src/modules/`), hand-registered table list (`src/schema.ts`), and Drizzle scripts.
|
|
26
|
+
// m5k:webapp:start
|
|
27
|
+
- `apps/webapp` — Vite + React 19 frontend: app shell, routes, providers, and feature modules.
|
|
28
|
+
// m5k:webapp:end
|
|
29
|
+
// m5k:expo:start
|
|
30
|
+
- `apps/expo` — Expo (React Native) app sharing the same server and shared contracts.
|
|
31
|
+
// m5k:expo:end
|
|
32
|
+
- `apps/email` — email templates and the local delivery registry.
|
|
33
|
+
// m5k:test-harness:start
|
|
34
|
+
- `apps/e2e` — Playwright end-to-end tests; the server exposes a test-harness module for them.
|
|
35
|
+
// m5k:test-harness:end
|
|
36
|
+
|
|
37
|
+
## Commands
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
pnpm dev # run all apps in dev (turbo)
|
|
41
|
+
pnpm build # build all apps
|
|
42
|
+
pnpm lint # biome check
|
|
43
|
+
pnpm lint:fix # biome check --write
|
|
44
|
+
pnpm check-types # tsc --noEmit everywhere
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Database (Drizzle, run from the repo root):
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
pnpm --filter ./apps/server drizzle:generate # generate migrations from *.db.ts changes
|
|
51
|
+
pnpm --filter ./apps/server drizzle:migrate # apply migrations
|
|
52
|
+
pnpm --filter ./apps/server drizzle:seed # seed the local database
|
|
53
|
+
pnpm --filter ./apps/server drizzle:reset # reset the local database
|
|
54
|
+
pnpm --filter ./apps/server drizzle:studio # inspect the database
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
First-time setup: `pnpm install`, then `drizzle:migrate` and `drizzle:seed`, then `pnpm dev`.
|
|
58
|
+
// m5k:test-harness:start
|
|
59
|
+
|
|
60
|
+
End-to-end tests: `pnpm --filter ./apps/e2e test:e2e` (Playwright).
|
|
61
|
+
// m5k:test-harness:end
|
|
62
|
+
|
|
63
|
+
The local database is a LibSQL file; local auth emails are written to `apps/server/.emails`. Demo login: `admin@{{APP_SLUG}}.local` / `password1234`.
|
|
64
|
+
|
|
65
|
+
## Framework Architecture
|
|
66
|
+
|
|
67
|
+
### Backend: kernel + modules
|
|
68
|
+
|
|
69
|
+
The backend kernel orchestrates modules. Each app module is a `BaseModule` subclass registered in `apps/server/src/app.ts` via `createBackendApp(config, [modules])` — the kernel wires its repositories, services, and tRPC routers.
|
|
70
|
+
|
|
71
|
+
A module lives in `apps/server/src/modules/<name>/` and follows a strict file anatomy where **the Drizzle table is the source of truth** and types flow one way:
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
<name>.db.ts table definition (source of truth; register it in src/schema.ts)
|
|
75
|
+
└─ <name>.dto.ts Zod schemas derived from the table — the module's API surface
|
|
76
|
+
├─ <name>.repository.ts data access, consumes the DTO object
|
|
77
|
+
├─ <name>.service.ts business logic, consumes the DTO object
|
|
78
|
+
└─ <name>.trpc.ts thin router: attaches DTO schemas, delegates to the service
|
|
79
|
+
<name>.grants.ts permission grants for the module
|
|
80
|
+
<name>.module.ts composition unit wiring the above into one class
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Clients infer all row/list types from `AppRouter` (`inferRouterOutputs`) — never hand-mirror server types anywhere. Never write Drizzle migrations by hand; change `*.db.ts`, register new tables in `src/schema.ts`, then run `drizzle:generate` + `drizzle:migrate`.
|
|
84
|
+
|
|
85
|
+
Roles are defined in `apps/shared/src/modules/app/` and passed through both `createBackendApp` metadata and the frontend config provider; when adding roles, extend the module `*.grants.ts` files to match.
|
|
86
|
+
// m5k:webapp:start
|
|
87
|
+
|
|
88
|
+
### Frontend: fixed stack, hooks own the logic
|
|
89
|
+
|
|
90
|
+
The webapp stack is fixed — React 19, HeroUI v3, Tailwind CSS v4, react-router v7, `nuqs` for URL state, TanStack Query over tRPC, i18next. Do not introduce alternatives (no fetch/axios, no form libraries, no other UI kits).
|
|
91
|
+
|
|
92
|
+
- App shell shape: `NuqsAdapter` + `BrowserRouter` + `Providers`; global providers are composed in one place only.
|
|
93
|
+
- Components stay display-focused; data fetching, mutations, and effect chains live in custom hooks under `modules/<feature>/hooks/`, composed into one screen-level hook (e.g. `usePostsRoute`).
|
|
94
|
+
- All server data goes through `useTRPC()` + `queryOptions`/`mutationOptions`; invalidate with the matching `queryFilter()` after mutations.
|
|
95
|
+
- Forms are uncontrolled HeroUI `Form` components with native HTML validation; read values from `FormData` on submit.
|
|
96
|
+
- All user-facing copy goes through i18next; keys live in `apps/webapp/translations/`.
|
|
97
|
+
// m5k:webapp:end
|
|
98
|
+
|
|
99
|
+
### Reference implementation
|
|
100
|
+
|
|
101
|
+
The **posts** feature is the canonical example of every convention. When adding a feature, mirror its structure:
|
|
102
|
+
|
|
103
|
+
- `apps/shared/src/modules/posts/`
|
|
104
|
+
- `apps/server/src/modules/posts/`
|
|
105
|
+
// m5k:webapp:start
|
|
106
|
+
- `apps/webapp/src/modules/posts/`
|
|
107
|
+
// m5k:webapp:end
|
|
108
|
+
|
|
109
|
+
## Detailed Style Guides
|
|
110
|
+
|
|
111
|
+
The framework's detailed conventions live in `.cursor/rules/*.mdc`. Cursor applies them by glob automatically; Claude does not — so **before creating or editing a file that matches a pattern below, read the matching guide first**. They describe how the framework is meant to be used, with correct/incorrect examples.
|
|
112
|
+
|
|
113
|
+
| Guide | Read before touching |
|
|
114
|
+
| --- | --- |
|
|
115
|
+
| `.cursor/rules/module-db-guide.mdc` | `apps/server/src/modules/**/*.db.ts` |
|
|
116
|
+
| `.cursor/rules/module-dto-guide.mdc` | `apps/server/src/modules/**/*.dto.ts` |
|
|
117
|
+
| `.cursor/rules/module-repository-guide.mdc` | `apps/server/src/modules/**/*.repository.ts` |
|
|
118
|
+
| `.cursor/rules/module-service-guide.mdc` | `apps/server/src/modules/**/*.service.ts` |
|
|
119
|
+
| `.cursor/rules/module-trpc-guide.mdc` | `apps/server/src/modules/**/*.trpc.ts` |
|
|
120
|
+
| `.cursor/rules/module-grants-guide.mdc` | `apps/server/src/modules/**/*.grants.ts` |
|
|
121
|
+
| `.cursor/rules/module-module-guide.mdc` | `apps/server/src/modules/**/*.module.ts` |
|
|
122
|
+
| `.cursor/rules/module-schema-guide.mdc` | `apps/shared/src/modules/**/*.schema.ts` |
|
|
123
|
+
// m5k:webapp:start
|
|
124
|
+
| `.cursor/rules/frontend-component-guide.mdc` | webapp `*.tsx` components |
|
|
125
|
+
| `.cursor/rules/frontend-hook-guide.mdc` | webapp `hooks/**` |
|
|
126
|
+
| `.cursor/rules/frontend-data-guide.mdc` | webapp data fetching / tRPC usage |
|
|
127
|
+
| `.cursor/rules/frontend-form-guide.mdc` | webapp forms |
|
|
128
|
+
| `.cursor/rules/frontend-i18n-guide.mdc` | webapp user-facing copy |
|
|
129
|
+
// m5k:webapp:end
|
|
130
|
+
|
|
131
|
+
`AGENTS.md` (repo root and per-app) carries a compact summary of the same conventions for other agents; this file plus the guides above are the authoritative version for Claude.
|