saasaloy 0.7.0 → 0.8.0
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/README.md +4 -2
- package/dist/index.js +222 -79
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/schemas/registry-item.schema.json +5 -2
- package/templates/base/AGENTS.md +80 -470
- package/templates/base/_agents/skills/saasaloy-design/SKILL.md +33 -22
- package/templates/base/_agents/skills/saasaloy-landing-copy/SKILL.md +17 -2
- package/templates/base/_agents/skills/saasaloy-setup/SKILL.md +38 -7
- package/templates/base/_saasaloy-base.json +1 -0
- package/templates/base/apps/web/DESIGN.md +4 -4
- package/templates/base/apps/web/astro.config.mjs +2 -1
- package/templates/base/apps/web/src/layouts/Layout.astro +2 -2
- package/templates/base/oxlint.config.mjs +14 -10
- package/templates/base/package.json +1 -0
- package/templates/base/packages/env/src/define.test.ts +33 -0
- package/templates/base/packages/ui/AGENTS.md +159 -0
- package/templates/base/packages/ui/CLAUDE.md +1 -0
- package/templates/base/packages/ui/components.json +1 -1
- package/templates/base/packages/ui/src/containers/README.md +4 -4
- package/templates/base/packages/ui/src/styles/brand.css +145 -0
- package/templates/base/packages/ui/src/styles/globals.css +6 -7
- package/templates/base/packages/ui/src/styles/web.css +7 -139
- package/templates/base/turbo.json +1 -0
package/templates/base/AGENTS.md
CHANGED
|
@@ -11,36 +11,30 @@ Every installed module ships a skill in `.agents/skills/<name>/SKILL.md`, linked
|
|
|
11
11
|
This is a **pnpm workspace monorepo** managed by **Turborepo**.
|
|
12
12
|
|
|
13
13
|
- **Root**: Configuration files only. Repository tooling lives in `packages/tooling` (see "Code at the Root")
|
|
14
|
-
- **`apps/*`**: Applications (
|
|
14
|
+
- **`apps/*`**: Applications. The base ships `apps/web` (Astro). `saasaloy add` writes the others: `admin` and `app` (TanStack Router SPAs) and `api` (Hono on Workers)
|
|
15
15
|
- **`packages/*`**: Shared packages
|
|
16
16
|
|
|
17
17
|
### Dev Port Map
|
|
18
18
|
|
|
19
|
-
Every dev port in this repo is pinned, not assigned on the fly. The api Worker's CORS
|
|
20
|
-
allow-list and the auth module's trusted origins hardcode the localhost origins, so a
|
|
21
|
-
drifting port turns into an unexplained CORS rejection.
|
|
19
|
+
Every dev port in this repo is pinned, not assigned on the fly. The api Worker's CORS allow-list and the auth module's trusted origins hardcode the localhost origins, so a drifting port turns into an unexplained CORS rejection.
|
|
22
20
|
|
|
23
21
|
| Workspace | Port | Dev URL | Pinned in |
|
|
24
22
|
| --- | --- | --- | --- |
|
|
25
23
|
| `apps/web` (Astro) | 3000 | `http://localhost:3000` | `apps/web/astro.config.mjs` (`server.port`) |
|
|
26
|
-
| `apps/admin` (TanStack
|
|
24
|
+
| `apps/admin` (TanStack Router) | 3001 | `http://localhost:3001` | `apps/admin/vite.config.ts` (`server.port`, `strictPort`) |
|
|
25
|
+
| `apps/app` (TanStack Router) | 3002 | `http://localhost:3002` | `apps/app/vite.config.ts` (`server.port`, `strictPort`) |
|
|
26
|
+
| `packages/email-react` preview | 3003 | `http://localhost:3003` | `packages/email-react/package.json` (`dev`, `--port`) |
|
|
27
27
|
| `apps/api` (Hono on Workers) | 4000 | `http://localhost:4000` | `apps/api/wrangler.jsonc` (`dev.port`) |
|
|
28
28
|
| Postgres (local, `database-postgres`) | 5432 | `postgres://postgres:postgres@127.0.0.1:5432/app` | `DATABASE_URL` in `packages/env/.env.example` |
|
|
29
29
|
|
|
30
|
-
The `apps/admin` and `apps/api` rows apply once you run `saasaloy add admin` or
|
|
31
|
-
`saasaloy add api`.
|
|
30
|
+
The `apps/admin`, `apps/app`, preview and `apps/api` rows apply once you run `saasaloy add` for `admin`, `app`, `email-react` or `api`.
|
|
32
31
|
|
|
33
32
|
Rules for a new app or service:
|
|
34
33
|
|
|
35
|
-
- **Take the next free port in the block** — `apps/*` count up from 3000, backend services
|
|
36
|
-
|
|
37
|
-
- **
|
|
38
|
-
|
|
39
|
-
- **Name the origin, don't infer it.** A browser-side caller reads `PUBLIC_API_URL`
|
|
40
|
-
through `webEnv()` or `adminEnv()`, with no fallback — an unset key fails the build
|
|
41
|
-
naming the key. A server-side caller reads its own key through `apiEnv(c.env)`.
|
|
42
|
-
- **Update both allow-lists when you add a browser origin**: `DEV_ORIGINS` in
|
|
43
|
-
`apps/api/src/index.ts` and `DEV_ORIGINS` in `packages/auth/src/auth.ts`.
|
|
34
|
+
- **Take the next free port in the block** — `apps/*` count up from 3000, backend services from 4000. Add a row to this table in the same change.
|
|
35
|
+
- **Set `strictPort` (or the framework's equivalent).** A busy port must fail loudly. A silent `+1` moves the app to an origin nothing allows.
|
|
36
|
+
- **Name the origin, don't infer it.** A browser-side caller reads `PUBLIC_API_URL` through `webEnv()` or `adminEnv()`, with no fallback — an unset key fails the build naming the key. A server-side caller reads its own key through `apiEnv(c.env)`.
|
|
37
|
+
- **Update both allow-lists when you add a browser origin**: `DEV_ORIGINS` in `apps/api/src/index.ts` and `DEV_ORIGINS` in `packages/auth/src/auth.ts`.
|
|
44
38
|
|
|
45
39
|
### Code at the Root
|
|
46
40
|
|
|
@@ -50,28 +44,17 @@ No code lives at the repository root. The root holds configuration only: `packag
|
|
|
50
44
|
|
|
51
45
|
### Workspace Commands
|
|
52
46
|
|
|
53
|
-
|
|
54
|
-
- Example: `pnpm --filter @repo/ui build`
|
|
55
|
-
- Use `pnpm turbo run <task> --filter <package-name>` for Turborepo tasks
|
|
47
|
+
Run a command in one package with `pnpm --filter <package-name> <command>` (`pnpm --filter @repo/ui build`), and a Turborepo task with `pnpm turbo run <task> --filter <package-name>`.
|
|
56
48
|
|
|
57
49
|
### The `clean` Script — Required in Every Workspace
|
|
58
50
|
|
|
59
|
-
`pnpm clean` at the root wipes the repo back to a fresh-clone state: it runs
|
|
60
|
-
`turbo run clean` across every workspace, then deletes all `node_modules` and `.turbo`
|
|
61
|
-
directories. Recover with `pnpm install`.
|
|
51
|
+
`pnpm clean` at the root wipes the repo back to a fresh-clone state: it runs `turbo run clean` across every workspace, then deletes all `node_modules` and `.turbo` directories. Recover with `pnpm install`.
|
|
62
52
|
|
|
63
|
-
**Every app and package you create MUST declare its own `clean` script.** A workspace
|
|
64
|
-
without one is silently skipped by `turbo run clean` and leaves stale build output behind.
|
|
53
|
+
**Every app and package you create MUST declare its own `clean` script.** A workspace without one is silently skipped by `turbo run clean` and leaves stale build output behind.
|
|
65
54
|
|
|
66
|
-
- Use **`rimraf`** (added as an exact-pinned `devDependency` of that workspace) — never
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
- Delete only what the workspace **generates**: `dist`, `.astro`, `.wrangler`,
|
|
70
|
-
`*.tsbuildinfo`. Never delete committed source or generated-then-committed files
|
|
71
|
-
(e.g. Drizzle migrations).
|
|
72
|
-
- Do **not** delete `node_modules` or `.turbo` from a workspace-level `clean` — the root
|
|
73
|
-
script removes those in one pass after Turborepo has finished. Deleting `.turbo` while
|
|
74
|
-
Turborepo is still streaming its task log into it fails on Windows.
|
|
55
|
+
- Use **`rimraf`** (added as an exact-pinned `devDependency` of that workspace) — never `rm -rf`, which does not exist on Windows. Pass `-g` when any argument is a glob; without it rimraf treats arguments as literal paths.
|
|
56
|
+
- Delete only what the workspace **generates**: `dist`, `.astro`, `.wrangler`, `*.tsbuildinfo`. Never delete committed source or generated-then-committed files (e.g. Drizzle migrations).
|
|
57
|
+
- Do **not** delete `node_modules` or `.turbo` from a workspace-level `clean` — the root script removes those in one pass after Turborepo has finished. Deleting `.turbo` while Turborepo is still streaming its task log into it fails on Windows.
|
|
75
58
|
|
|
76
59
|
```jsonc
|
|
77
60
|
// apps/<name>/package.json
|
|
@@ -85,51 +68,28 @@ without one is silently skipped by `turbo run clean` and leaves stale build outp
|
|
|
85
68
|
|
|
86
69
|
## Tech & Tools
|
|
87
70
|
|
|
88
|
-
- **pnpm** — non-auth settings live in `pnpm-workspace.yaml` (camelCase), never `.npmrc`.
|
|
89
|
-
Exact versions are pinned (`saveExact`).
|
|
71
|
+
- **pnpm** — non-auth settings live in `pnpm-workspace.yaml` (camelCase), never `.npmrc`. Exact versions are pinned (`saveExact`).
|
|
90
72
|
- **TypeScript + ESM.** Internal packages are consumed JIT (no build step) via `workspace:*`.
|
|
91
|
-
- **Add features, don't hand-wire them.** Prefer `saasaloy add <module>` over manually
|
|
92
|
-
creating routes/schema/auth. Most of what a module contributes is a file dropped at a
|
|
93
|
-
convention-based extension point; the rest is a small reversible patch on a file that has
|
|
94
|
-
to name its entries statically. An api route is the second kind — `saasaloy add` edits
|
|
95
|
-
`apps/api/src/index.ts` to add one `.route()` link and its import, and `saasaloy remove`
|
|
96
|
-
takes both out again. Do not add a route by dropping a file into `apps/api/src/routes/`
|
|
97
|
-
and expecting it to mount: nothing globs that folder, and the entry file's `AppType` is
|
|
98
|
-
what the typed `hc` client reads.
|
|
73
|
+
- **Add features, don't hand-wire them.** Prefer `saasaloy add <module>` over manually creating routes/schema/auth. Most of what a module contributes is a file dropped at a convention-based extension point; the rest is a small reversible patch on a file that has to name its entries statically. An api route is the second kind — `saasaloy add` edits `apps/api/src/index.ts` to add one `.route()` link and its import, and `saasaloy remove` takes both out again. Do not add a route by dropping a file into `apps/api/src/routes/` and expecting it to mount: nothing globs that folder, and the entry file's `AppType` is what the typed `hc` client reads.
|
|
99
74
|
|
|
100
75
|
### The `@repo/env` Environment Layer
|
|
101
76
|
|
|
102
|
-
`packages/env` owns every environment value this project reads. One tracked key list, one
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
- **`packages/env/.env
|
|
106
|
-
|
|
107
|
-
A value you type in it survives that, and nothing is ever removed.
|
|
108
|
-
- **`packages/env/.env` holds the values**, and it is gitignored. `saasaloy env` prompts
|
|
109
|
-
for each unset key and writes it.
|
|
110
|
-
- **`pnpm env:setup` writes every service's own `.env`** from those two files. A *service*
|
|
111
|
-
is a workspace that reads a `.env` — `api`, `web`, `admin` — and
|
|
112
|
-
`packages/env/src/services.ts` is the table. The `deploy` row has no file: it holds the
|
|
113
|
-
Cloudflare credentials a deploy loads in memory.
|
|
77
|
+
`packages/env` owns every environment value this project reads. One tracked key list, one command that distributes it, one typed gate in front of the capabilities.
|
|
78
|
+
|
|
79
|
+
- **`packages/env/.env.example` is the key list**, and it is the only example file. It is tracked, and `saasaloy add` regenerates it from the installed modules' own descriptions. A value you type in it survives that, and nothing is ever removed.
|
|
80
|
+
- **`packages/env/.env` holds the values**, and it is gitignored. `saasaloy env` prompts for each unset key and writes it.
|
|
81
|
+
- **`pnpm env:setup` writes every service's own `.env`** from those two files. A *service* is a workspace that reads a `.env` — `api`, `web`, `admin` — and `packages/env/src/services.ts` is the table. The `deploy` row has no file: it holds the Cloudflare credentials a deploy loads in memory.
|
|
114
82
|
- **`pnpm deploy:production` deploys every Worker.** It checks the git gates and every service's production values first, then deploys each Worker one at a time in the order `packages/tooling/src/targets.ts` gives. Each Worker runs its own `env-deploy <service>`: build with the production values in the environment, then `wrangler deploy --secrets-file`. The `local` source reads production values from the gitignored `packages/env/.env.prod`. Nothing writes a production value under `apps/`. The `saasaloy-deploy` skill covers the gates, the flags and the rollback.
|
|
115
|
-
- **`createEnv` is the gate.** `apiEnv(c.env)` on the server, `webEnv()` in a frontend.
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
- **A `client` key must start with `PUBLIC_`**, and the type system enforces it. Client
|
|
119
|
-
code reading a server key throws by name.
|
|
120
|
-
- **There is no `.dev.vars`.** Every runtime here reads `.env`. A leftover `.dev.vars`
|
|
121
|
-
hides `.env` from wrangler without warning, so `saasaloy doctor` reports one and
|
|
122
|
-
`pnpm env:setup` carries its values across and deletes it.
|
|
83
|
+
- **`createEnv` is the gate.** `apiEnv(c.env)` on the server, `webEnv()` in a frontend. It validates on the first call and throws once naming every failing key, its module and what the key is for.
|
|
84
|
+
- **A `client` key must start with `PUBLIC_`**, and the type system enforces it. Client code reading a server key throws by name.
|
|
85
|
+
- **There is no `.dev.vars`.** Every runtime here reads `.env`. A leftover `.dev.vars` hides `.env` from wrangler without warning, so `saasaloy doctor` reports one and `pnpm env:setup` carries its values across and deletes it.
|
|
123
86
|
- **Never read `process.env`** in a file a Worker imports. Node tooling reads it freely.
|
|
124
87
|
|
|
125
|
-
The `saasaloy-env` skill is the runbook: adding a key, the section rule, the server/client
|
|
126
|
-
split, blank-on-purpose keys, and the offline rule.
|
|
88
|
+
The `saasaloy-env` skill is the runbook: adding a key, the section rule, the server/client split, blank-on-purpose keys, and the offline rule.
|
|
127
89
|
|
|
128
90
|
### The `@repo/config` Value Layer
|
|
129
91
|
|
|
130
|
-
`packages/config` (`@repo/config`) owns the values this project checks into its repo and ships
|
|
131
|
-
identically to every environment: the product name, the locale, the legal paths, and each
|
|
132
|
-
installed module's section. Read it with a plain import, from any app or package:
|
|
92
|
+
`packages/config` (`@repo/config`) owns the values this project checks into its repo and ships identically to every environment: the product name, the locale, the legal paths, and each installed module's section. Read it with a plain import, from any app or package:
|
|
133
93
|
|
|
134
94
|
```ts
|
|
135
95
|
import { config } from "@repo/config";
|
|
@@ -138,15 +98,11 @@ config.app.name; // `siteName` in @repo/ui re-exports this
|
|
|
138
98
|
config.app.locale; // the shared layout's <html lang>
|
|
139
99
|
```
|
|
140
100
|
|
|
141
|
-
It is a frozen plain object, built once at module load. It has **zero runtime dependencies and
|
|
142
|
-
imports nothing**, which is what lets every app, every package and every browser bundle import it.
|
|
101
|
+
It is a frozen plain object, built once at module load. It has **zero runtime dependencies and imports nothing**, which is what lets every app, every package and every browser bundle import it.
|
|
143
102
|
|
|
144
|
-
**config or `.env`?** Two deployments of *this* project — production and staging. If the value can
|
|
145
|
-
differ between them it is an env var, secret or not. If it cannot, it is config. A database URL is
|
|
146
|
-
env; the product's name is config.
|
|
103
|
+
**config or `.env`?** Two deployments of *this* project — production and staging. If the value can differ between them it is an env var, secret or not. If it cannot, it is config. A database URL is env; the product's name is config.
|
|
147
104
|
|
|
148
|
-
**The landing copy is not config.** Prices, tier ids and every sentence on the page stay in
|
|
149
|
-
`@repo/ui/content/landing.ts`.
|
|
105
|
+
**The landing copy is not config.** Prices, tier ids and every sentence on the page stay in `@repo/ui/content/landing.ts`.
|
|
150
106
|
|
|
151
107
|
Four files, and only one is yours:
|
|
152
108
|
|
|
@@ -157,418 +113,62 @@ Four files, and only one is yours:
|
|
|
157
113
|
| `src/sections/<key>.ts` | The module that installed it (`app` is the base's). |
|
|
158
114
|
| `src/define.ts` | The base template. The composition core. |
|
|
159
115
|
|
|
160
|
-
The merge goes **one level below the section**: `app: { name: "..." }` replaces the name and keeps
|
|
161
|
-
the rest of `app`, while a nested record or an array is replaced whole. A key no installed section
|
|
162
|
-
defines is a `typecheck` error, which is the only validation there is — the values are literals in
|
|
163
|
-
this repo. Run `/saasaloy-config` for the whole runbook.
|
|
116
|
+
The merge goes **one level below the section**: `app: { name: "..." }` replaces the name and keeps the rest of `app`, while a nested record or an array is replaced whole. A key no installed section defines is a `typecheck` error, which is the only validation there is — the values are literals in this repo. Run `/saasaloy-config` for the whole runbook.
|
|
164
117
|
|
|
165
118
|
### The `@repo/ui` Design Layer
|
|
166
119
|
|
|
167
|
-
`packages/ui` owns the design layer: the Tailwind
|
|
168
|
-
|
|
169
|
-
Those layer folders are the whole top level of `src/`: `assets` (images, SVGs and icons, added when the first one arrives), `blocks`, `components`, `containers`, `content`, `lib` and `styles`. Do not add an app folder such as `src/admin/` or `src/web/` beside them. When one app needs its own files inside a layer, give that layer a child folder (`blocks/admin/`, `components/shared/`).
|
|
170
|
-
|
|
171
|
-
The theme is one shared file plus one theme file per app:
|
|
172
|
-
|
|
173
|
-
- **`src/styles/globals.css`** is the shared layer: the Tailwind imports, the `@source`
|
|
174
|
-
globs and the base layer. It holds no token values, and no app imports it directly.
|
|
175
|
-
- **`src/styles/web.css`** is the web app's theme: the `dark` custom variant, its `:root`
|
|
176
|
-
and `.dark` token values, its `@theme inline` colour mapping and its radius scale. It
|
|
177
|
-
imports `globals.css`, and `apps/web` pulls it in once, through the shared layout that
|
|
178
|
-
imports `@repo/ui/styles/web.css`. `components.json` points here, so a shadcn preset
|
|
179
|
-
lands here. The landing page's layout, type and motion utilities sit at the end of the
|
|
180
|
-
file, after the colour tokens, and a preset leaves them alone.
|
|
181
|
-
- **`src/styles/admin.css`** is the admin app's theme, in the same shape, written by
|
|
182
|
-
`saasaloy add admin`.
|
|
183
|
-
|
|
184
|
-
Each theme file repeats the `dark` variant and the `@theme inline` mapping on purpose.
|
|
185
|
-
shadcn merges a preset in place only when the target file itself holds them, and it does
|
|
186
|
-
not look through an `@import`. Move either one into `globals.css` and a preset appends a
|
|
187
|
-
duplicate to `web.css` instead.
|
|
188
|
-
|
|
189
|
-
**Each app has its own `DESIGN.md`, in its own folder.** `apps/web/DESIGN.md` records the
|
|
190
|
-
web tokens in `web.css` and the rules behind them, and fingerprints `web.css`. An app
|
|
191
|
-
that carries its own theme file gets its own `apps/<app>/DESIGN.md`, which fingerprints
|
|
192
|
-
that file. There is no `DESIGN.md` at the repository root. Read the document for the app
|
|
193
|
-
you are changing before you add or change UI.
|
|
120
|
+
`packages/ui` owns the design layer: the Tailwind theme in `src/styles/`, the vendored shadcn primitives, the blocks, the containers and the copy. Its own guide is `packages/ui/AGENTS.md`. Read it before you add or change UI in any app. These are the rules that reach past the package:
|
|
194
121
|
|
|
195
|
-
|
|
122
|
+
- **Read the app's `DESIGN.md` first.** `apps/web/DESIGN.md` covers the web app, and `apps/admin/DESIGN.md` covers the admin app when it is installed. There is no `DESIGN.md` at the repository root.
|
|
123
|
+
- **No IO in `@repo/ui`.** A block or a container takes its data, its links and its callbacks as props. The app owns fetch, auth, the router and the stores, and passes in what the block needs.
|
|
124
|
+
- **Import by subpath.** `import { Button } from "@repo/ui/components/button"`. The package root exports project-wide constants only (`siteName`).
|
|
125
|
+
- **The signed-in apps use the `shell` set.** `apps/admin` and `apps/app` import from `@repo/ui/{components,blocks,containers}/shell/*`, and a lint rule makes a base primitive there an error.
|
|
126
|
+
- **Words live in `packages/ui/src/content/`**, never in a block, so a copy pass and a later translation find them.
|
|
127
|
+
- **No UI kit as a dependency.** Copy a kit's component into `src/components/` or `src/blocks/` as source this project owns.
|
|
196
128
|
|
|
197
|
-
|
|
198
|
-
package root, so importing one never drags in the rest. The root export is project-wide
|
|
199
|
-
constants only (`siteName`, which re-exports `config.app.name`):
|
|
129
|
+
### The Base Skills
|
|
200
130
|
|
|
201
|
-
|
|
202
|
-
import { siteName } from "@repo/ui";
|
|
203
|
-
import { Button } from "@repo/ui/components/button";
|
|
204
|
-
import { PricingTable } from "@repo/ui/blocks/pricing-table";
|
|
205
|
-
import { landing, ui } from "@repo/ui/content/landing";
|
|
206
|
-
import { cn } from "@repo/ui/lib/utils";
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
**The admin app has its own primitive set.** `saasaloy add admin` writes it into `src/components/admin/`, with its blocks in `src/blocks/admin/` and its shell and layouts in `src/containers/admin/`. Admin code imports only those, and a lint rule makes a base primitive under `apps/admin/**` an error, because both sets have a `button` and the wrong one renders with no complaint:
|
|
210
|
-
|
|
211
|
-
```ts
|
|
212
|
-
import { Button } from "@repo/ui/components/admin/button";
|
|
213
|
-
import { DataTable } from "@repo/ui/blocks/admin/data-table";
|
|
214
|
-
import { PageHeader } from "@repo/ui/blocks/admin/page-header";
|
|
215
|
-
import { PageLayout } from "@repo/ui/containers/admin/page-layout";
|
|
216
|
-
```
|
|
131
|
+
Seven skills ship with the base, as real files in `.agents/skills/` linked into `.claude/skills/`. Two run in order when you make the project yours:
|
|
217
132
|
|
|
218
|
-
|
|
133
|
+
1. **`saasaloy-setup`** interviews the owner once and writes `docs/product-brief.md`, then sets `config.app.name` and `config.app.locale`. Other skills read the brief rather than ask again.
|
|
134
|
+
2. **`saasaloy-landing-copy`** writes `packages/ui/src/content/landing.ts` from the brief.
|
|
219
135
|
|
|
220
|
-
|
|
136
|
+
The other five run when the thing they own moves:
|
|
221
137
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
6. **`src/lib/`** holds utilities and the client-state stores.
|
|
228
|
-
7. **`src/styles/`** holds the CSS files with the token variables.
|
|
229
|
-
|
|
230
|
-
**One rule covers the whole package: no IO in `@repo/ui`.** No fetch, no persistence, no auth, no router, in any layer. Client-state stores (nanostores) live in `src/lib/`; the app that owns the data hydrates the store and passes what a block needs as props. When a store-shaped need shows up in a block, move the binding up into the app instead of importing the store in place.
|
|
231
|
-
|
|
232
|
-
**Adding a primitive the base doesn't vendor.** `shadcn` is already an exact-pinned
|
|
233
|
-
dependency of `@repo/ui`, so reach it with `--filter … exec` — that runs in the package
|
|
234
|
-
directory, where `components.json` lives:
|
|
235
|
-
|
|
236
|
-
```sh
|
|
237
|
-
pnpm --filter @repo/ui exec shadcn add dialog
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
- **Not `pnpm -C packages/ui dlx …`.** `-C` scopes pnpm's own workspace resolution; it
|
|
241
|
-
does *not* change the directory `dlx` spawns the command in. shadcn then looks for
|
|
242
|
-
`components.json` wherever your shell happens to be and dies at `Verifying framework`.
|
|
243
|
-
If you must use `dlx`, pass shadcn's own flag: `--cwd packages/ui`.
|
|
244
|
-
- Never `npx` (see Never Do).
|
|
245
|
-
- The CLI writes into `src/components/`. Anything it appends to `package.json` arrives
|
|
246
|
-
as a range — **re-pin it to an exact version**.
|
|
247
|
-
- **Add the primitive to a `@source` list, or it renders unstyled.** `globals.css` names
|
|
248
|
-
the components it scans one file at a time, because Tailwind scans content rather than
|
|
249
|
-
imports and a blanket glob charges every app for every primitive. A primitive the
|
|
250
|
-
landing page or `src/blocks/` renders gets an `@source "../components/<name>.tsx";` line
|
|
251
|
-
in `globals.css`; a primitive only one app renders gets its `@source` line in that app's
|
|
252
|
-
own theme file, the way `src/styles/admin.css` takes the whole directory.
|
|
253
|
-
Nothing errors when you skip this — the classes just never reach the CSS.
|
|
254
|
-
- `style` is `base-nova` (Base UI) and is fixed at init — the CLI cannot change it later.
|
|
255
|
-
- `rsc` is `false`, so the CLI strips the `"use client"` directive for you. It means
|
|
256
|
-
nothing in Astro, and the vendored primitives don't carry it.
|
|
257
|
-
|
|
258
|
-
Primitives are source you own. Edit them in place rather than wrapping them.
|
|
259
|
-
|
|
260
|
-
**No UI kit or component library as a dependency.** When a design comes from a kit (Tailark, coss ui, a licensed dashboard kit), copy or rebuild the component into `src/components/` or `src/blocks/` as source this project owns. Do not install the kit's package, and keep no link to its repository for later updates. A copied component changes by hand, like any other file here. The shadcn CLI above is the one sanctioned way to fetch a primitive, because it writes source and leaves no runtime dependency behind.
|
|
261
|
-
|
|
262
|
-
**Swapping the whole theme for a preset.** The token set in
|
|
263
|
-
`packages/ui/src/styles/web.css` is shadcn's `neutral` with `cssVariables: true`, and
|
|
264
|
-
any shadcn **`registry:style`** item is a drop-in replacement for it. The same
|
|
265
|
-
`--filter … exec` form applies — there is no separate theme command:
|
|
266
|
-
|
|
267
|
-
```sh
|
|
268
|
-
pnpm --filter @repo/ui exec shadcn add https://tweakcn.com/r/themes/modern-minimal.json
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
The CLI merges the preset's `:root`, `.dark` and `@theme inline` blocks **into** the
|
|
272
|
-
existing ones in `web.css` and keeps its `@custom-variant dark`, so the hand-written
|
|
273
|
-
parts in `globals.css` — the `@source` rules and the `@layer base` rules — stay put, and
|
|
274
|
-
`components.json` is not touched. The preset reaches the web app only; the admin theme
|
|
275
|
-
in `admin.css` keeps its own values. It usually *extends* `@theme inline` with mappings
|
|
276
|
-
the base does not carry (fonts, tracking, shadows); that is expected.
|
|
277
|
-
|
|
278
|
-
Two places to get an item from:
|
|
279
|
-
|
|
280
|
-
1. **[`https://ui.shadcn.com/create`](https://ui.shadcn.com/create)** — first-party.
|
|
281
|
-
Describe or dial in a theme and it hands you a URL.
|
|
282
|
-
2. **[`https://tweakcn.com`](https://tweakcn.com)** — a much larger preset library,
|
|
283
|
-
serving items at `https://tweakcn.com/r/themes/<name>.json`.
|
|
284
|
-
|
|
285
|
-
Neither is special: the mechanism is the `registry:style` shape, so any URL that serves
|
|
286
|
-
one works.
|
|
287
|
-
|
|
288
|
-
**This edits a file the project owns.** `web.css` is an owned base file: `saasaloy
|
|
289
|
-
update` never overwrites it, and a later template change to it reaches you only through
|
|
290
|
-
the merge plan. A swapped theme is yours to maintain, including re-applying anything you
|
|
291
|
-
had customised in `web.css` that the preset overwrote. Diff the file after running the
|
|
292
|
-
command rather than assuming.
|
|
293
|
-
|
|
294
|
-
A preset swap invalidates `apps/web/DESIGN.md`, which records the token values the old theme had. The `saasaloy-design` skill's `theme` flow runs the command above for you and re-derives the contract from the merged result, so prefer it over running the command by hand. Pick one or the other — running both applies the preset twice.
|
|
295
|
-
|
|
296
|
-
Theme switching is unaffected by any of this. It keys off the `.dark` class, which every preset keeps. The toggle has two states, light and dark: `system` is only the starting state for a visitor who never pressed it, and no press steps back to `system`. Do not give the toggle a third state or a light/dark/system menu.
|
|
297
|
-
|
|
298
|
-
**A project made before the theme split.** Older projects kept the web tokens in
|
|
299
|
-
`globals.css` and the design document at the repository root. `saasaloy update` creates
|
|
300
|
-
`packages/ui/src/styles/web.css` and lists `globals.css` and `Layout.astro` in the merge
|
|
301
|
-
plan, because the project owns both; it never moves your tokens for you. Finish the split
|
|
302
|
-
by hand, in this order:
|
|
303
|
-
|
|
304
|
-
1. Move the `@custom-variant dark` line, the `:root` block, the `.dark` block and the
|
|
305
|
-
`@theme inline` block from `globals.css` into `web.css`, replacing the template's
|
|
306
|
-
copies there, below its `@import "./globals.css";`. Keep your own values, not the
|
|
307
|
-
template's.
|
|
308
|
-
2. Add `"./styles/*": "./src/styles/*"` to the `exports` of `packages/ui/package.json`,
|
|
309
|
-
if the update did not.
|
|
310
|
-
3. In `apps/web/src/layouts/Layout.astro`, import `@repo/ui/styles/web.css` in place of
|
|
311
|
-
`@repo/ui/globals.css`.
|
|
312
|
-
4. Set `tailwind.css` in `packages/ui/components.json` to `src/styles/web.css`, if the
|
|
313
|
-
update did not.
|
|
314
|
-
5. Move `DESIGN.md` to `apps/web/DESIGN.md`, and run the `saasaloy-design` skill's
|
|
315
|
-
`update` flow so its fingerprint names `web.css`.
|
|
316
|
-
6. Run `pnpm build` and check that `globals.css` and `web.css` hold one `@theme inline`
|
|
317
|
-
and one `@custom-variant dark` between them.
|
|
318
|
-
|
|
319
|
-
With the admin app installed, `saasaloy update` also moves its theme: it creates
|
|
320
|
-
`packages/ui/src/styles/admin.css` and deletes `apps/admin/src/styles/admin.css`, or
|
|
321
|
-
keeps it with a warning when you edited it. Carry any edit across to the new file, then
|
|
322
|
-
delete the old one. The new admin app imports `@repo/ui/styles/admin.css`, so its build
|
|
323
|
-
fails until step 2 adds the `./styles/*` export. Update the base and finish step 2 before
|
|
324
|
-
you build admin, and before you run `saasaloy add admin` on a project made before the
|
|
325
|
-
split.
|
|
326
|
-
|
|
327
|
-
**Blocks — the page-level compositions.** `src/blocks/` holds the thirteen marketing
|
|
328
|
-
blocks the landing page is built from: `navbar`, `hero`, `logo-cloud`, `pain-points`,
|
|
329
|
-
`how-it-works`, `feature-grid`, `showcase`, `audience`, `testimonials`, `pricing-table`,
|
|
330
|
-
`faq`, `cta` and `footer`. `logo-cloud`, `pain-points`, `how-it-works`, `showcase`,
|
|
331
|
-
`audience` and `testimonials` are new; a project scaffolded before them gets the files
|
|
332
|
-
through `saasaloy update`, and adds each to its own `index.astro` by hand, since the page
|
|
333
|
-
is the owner's. The blocks need the landing utilities at the end of `web.css`. `web.css`
|
|
334
|
-
is an owned file, so `update` lists it in the merge plan and never adds them for you.
|
|
335
|
-
Copy the template's block, from the comment that opens "The landing page's layout" to
|
|
336
|
-
the `stylelint-enable` line, to the end of your `web.css`. A project made before the
|
|
337
|
-
theme split skips this: `update` creates its `web.css` from the template, block included.
|
|
338
|
-
|
|
339
|
-
**The section recipe.** `index.astro` composes the page from explicit imports, one line
|
|
340
|
-
per section. To remove a section, delete its line and its import, delete its file in
|
|
341
|
-
`src/blocks/`, and blank its navbar and footer labels in `landing.ts`. To reorder, move
|
|
342
|
-
the lines. Every block uses the same container (`section-container`, `-narrow`, `-wide`)
|
|
343
|
-
and spacing (`section-y`) utilities from `src/styles/web.css`, so any order keeps one
|
|
344
|
-
rhythm. A block sets no width, no section padding and no keyframes of its own; motion
|
|
345
|
-
comes from the named utilities there (`blur-in`, `beam-in`, `reveal`, `marquee`,
|
|
346
|
-
`shine-text`, `nav-float`, `hover-lift`), and every one stops under reduced motion.
|
|
347
|
-
|
|
348
|
-
**The logo recipe.** `landing.logos.items[]` is `{ id, name, mark }`. `mark` is a key in
|
|
349
|
-
`LOGO_MARKS` at the top of `blocks/logo-cloud.tsx`. Paste a customer's SVG there under a
|
|
350
|
-
kebab-case key with `fill="currentColor"`, then name the key in content. An unknown key
|
|
351
|
-
renders `name` as a text wordmark.
|
|
352
|
-
|
|
353
|
-
**The production bar.** The page holds to a rubric: no axe violation at WCAG 2.1 AA in
|
|
354
|
-
either theme, no sideways scroll from 360px up, nothing animating under reduced motion, a
|
|
355
|
-
skip link to `<main>` on every page, link-preview metadata on `/`, and exactly two islands
|
|
356
|
-
(`Navbar`, `PricingTable`). Keep each true when you change a block: a new section with
|
|
357
|
-
state is a third island and needs a reason.
|
|
358
|
-
|
|
359
|
-
The rules below are not stylistic — each one prevents a real failure:
|
|
360
|
-
|
|
361
|
-
- **One block, one file, one component export (plus its prop types).**
|
|
362
|
-
`pricing-table.tsx` exports `PricingTable` alongside `PricingTier` and
|
|
363
|
-
`PricingTableProps`, and nothing else — no second component, no default export, no
|
|
364
|
-
`blocks/index.ts` barrel. Astro gives every `client:*` component its own React root, so
|
|
365
|
-
a compound primitive (accordion, dialog, dropdown) split across an `.astro` file throws
|
|
366
|
-
"must be used within" at runtime. Keep the whole composition inside the block.
|
|
367
|
-
- **Props-driven, with every default read from the content module.** Every prop is still
|
|
368
|
-
optional and still carries a default — but the *words* come from
|
|
369
|
-
`packages/ui/src/content/landing.ts`, not from the block. `hero.tsx` has
|
|
370
|
-
`title = landing.hero.title`; `pricing-table.tsx` holds no tier data at all. Keep the
|
|
371
|
-
props for the cases a page really varies (a second landing page can override any of
|
|
372
|
-
them); change the copy by editing the content module. See below.
|
|
373
|
-
- **Never pass a component or a function as a prop from `.astro`.** Astro serializes
|
|
374
|
-
island props, so icons live *inside* the block. Swap one by editing the block.
|
|
375
|
-
- **Semantic kebab-case filenames** (`feature-grid.tsx`), never shadcn's registry-style
|
|
376
|
-
`{category}-{NN}` numbering — that disambiguates variants in a public registry, and
|
|
377
|
-
this project has neither.
|
|
378
|
-
- **Static by default.** A block with no state renders to HTML and ships zero JS. Add a
|
|
379
|
-
client directive only to the block that actually needs the browser, and pick the
|
|
380
|
-
cheapest one: `client:idle` above the fold, `client:visible` below it. A blanket
|
|
381
|
-
`client:load` on the page hydrates everything and throws away the reason this is a
|
|
382
|
-
static site — see `apps/web/src/pages/index.astro` for the worked example.
|
|
383
|
-
- **`theme-toggle` is the exception that proves the rule.** It sits in `src/blocks/`
|
|
384
|
-
beside the marketing blocks but is chrome, not copy: `navbar.tsx` renders it inside the
|
|
385
|
-
bar, and it needs **no** client directive of its own despite being interactive. It has
|
|
386
|
-
no `onClick` and no state — the pre-paint inline script the shared layout emits
|
|
387
|
-
(`THEME_INIT_SCRIPT`, from `packages/ui/src/lib/theme.ts`) drives every
|
|
388
|
-
`[data-theme-toggle]` on the page through one delegated listener, and CSS picks the
|
|
389
|
-
icon off `<html data-theme>`. Move it, restyle it via its `className`, or delete the
|
|
390
|
-
one line in `navbar.tsx` to drop it. Do **not** "fix" it by adding `client:*` or an
|
|
391
|
-
`onClick`, and do not paste a second copy of the boot script into a page: any document
|
|
392
|
-
that renders the block must inline that one constant in its `<head>`, or the control
|
|
393
|
-
stays hidden.
|
|
394
|
-
- **`error-state` is the only error screen, and every app renders it.** An app that adds
|
|
395
|
-
a route surface answers a miss with `ErrorState` — `apps/web` through
|
|
396
|
-
`src/pages/404.astro`, the admin SPA through the root route's `notFoundComponent` and
|
|
397
|
-
its error boundary, and `apps/api` through `base.notFound(...)`, which answers the same
|
|
398
|
-
`{ error: { code, message } }` envelope as every other failure. Do **not** write a
|
|
399
|
-
second error screen in an app: one block means one restyle when the theme moves, and a
|
|
400
|
-
bespoke copy drifts out of the token vocabulary the day nobody is looking. Change the
|
|
401
|
-
words in `packages/ui/src/content/errors.ts`, the markup in
|
|
402
|
-
`packages/ui/src/blocks/error-state.tsx`.
|
|
403
|
-
- **A `prerender = false` page inherits `500.astro`.** `apps/web` registers
|
|
404
|
-
`@astrojs/cloudflare` while staying on `output: "static"`, so `src/pages/500.astro` is
|
|
405
|
-
built ahead of time and carries no detail from the failed request. The day a page opts
|
|
406
|
-
into on-demand rendering, a throw inside it lands on that page for free — nothing to
|
|
407
|
-
add. Two things move on that day and only that day: `wrangler.jsonc` gains a `main`
|
|
408
|
-
pointing at the server entry the adapter now writes, and `dist/server` stops being
|
|
409
|
-
empty. Setting `main` before then breaks the build, which is why the comment in
|
|
410
|
-
`wrangler.jsonc` says to wait.
|
|
411
|
-
- **A block never reaches the network; the app injects the behaviour.** A block that needs
|
|
412
|
-
to send something takes a function prop (`onSubmit`) and calls it. It does not import an
|
|
413
|
-
api package, an http client, or `import.meta.env`. Two reasons, both concrete.
|
|
414
|
-
`packages/ui` has a `typecheck` script and consumes workspaces as source, so one
|
|
415
|
-
`import type { AppType } from "@repo/api/client"` here makes `tsc` compile the entire
|
|
416
|
-
Worker source tree under this package's tsconfig. And a block that hardcodes an endpoint
|
|
417
|
-
is a block you cannot reuse on a second page. The counterpart lives in the app: a small
|
|
418
|
-
React file under `apps/web/src/components/` builds the client and passes the function
|
|
419
|
-
down. Astro serializes island props, so the page renders **that** file, never the block
|
|
420
|
-
directly.
|
|
421
|
-
- **A link that leaves the site opens a new tab.** Spread `externalLinkProps(href)` from `@repo/ui/lib/external-link` onto the anchor and render `newTabHint(href)` inside it. The href decides: an absolute URL gets `target="_blank"`, `rel="noopener noreferrer"` and a screen-reader hint, and a path or a same-page anchor stays in the tab. Do not write `target="_blank"` by hand.
|
|
422
|
-
- **A value that waits on a request shows a skeleton.** Render the `Skeleton` primitive at the size the value will take until the response arrives, never a blank gap or a spinner. Add it with `pnpm --filter @repo/ui exec shadcn add skeleton` the first time a block needs it.
|
|
423
|
-
- **A block never imports a store either.** Local state is fine; shared state is not. The app-side island reads the store and passes the values and the handlers down, the same pattern it uses for `onSubmit`.
|
|
424
|
-
- **A module's UI arrives here too, and you wire it up by hand.** `saasaloy add <module>`
|
|
425
|
-
writes a UI-bearing module's block into `src/blocks/` exactly like the base blocks, adds
|
|
426
|
-
the app-side island that feeds it, and then stops: nothing globs a folder, and no command
|
|
427
|
-
edits `index.astro`. The command prints a pointer to the module's skill, and that skill's
|
|
428
|
-
**Wire-up** section carries the import line, the component to render, the client
|
|
429
|
-
directive, and a suggested spot on the page. Put it where you want it. `saasaloy remove`
|
|
430
|
-
deletes the files it wrote and leaves your import alone, so take that line out yourself.
|
|
431
|
-
|
|
432
|
-
Blocks, like primitives, are source you own — they are meant to be edited, not wrapped.
|
|
433
|
-
|
|
434
|
-
**Containers — the shells and the layouts.** `src/containers/` holds the compositions that place blocks and components on a page: an app shell, a page layout, a page frame. The base ships none; `saasaloy add admin` writes the admin app's into `src/containers/admin/`.
|
|
435
|
-
|
|
436
|
-
- **A container places, a block renders.** It decides where the panels, the header and the detail view go, and it adds no copy a block could hold.
|
|
437
|
-
- **No router, no session.** A container takes the nav data, the current area, a link component and the account as props. The app reads its router and its session and passes them in, so a container never depends on one app's routes.
|
|
438
|
-
- **Still no IO.** A container does not fetch, persist, or authenticate.
|
|
439
|
-
- **Same file rules as blocks:** one container per file, semantic kebab-case filename, no barrel.
|
|
440
|
-
|
|
441
|
-
**The content module — where the words live.** `packages/ui/src/content/landing.ts` holds
|
|
442
|
-
every user-visible string on the landing page, in two namespaces:
|
|
443
|
-
|
|
444
|
-
- **`landing.*`** — marketing copy. What the product is, who it is for, what it costs.
|
|
445
|
-
This is the whole surface a copy rewrite touches. The brand itself is not here: it is
|
|
446
|
-
`config.app.name` in `packages/config/src/project.ts`, is not translated, and is set once
|
|
447
|
-
by `saasaloy-setup`. The currency symbol and the tier ids and names are read from
|
|
448
|
-
`@repo/config` for the same reason — they are ids and numbers, and `packages/billing`
|
|
449
|
-
charges against the same ids.
|
|
450
|
-
- **`ui.*`** — chrome and accessibility labels (`Monthly`, `Most popular`, `Close menu`,
|
|
451
|
-
`Billing period`). Nothing here says anything about the product, so a copy pass never
|
|
452
|
-
rewrites it. It does get translated, key for key, when `landing.*` is written in some
|
|
453
|
-
language other than English — no translation layer ships in the base, so that pass is the
|
|
454
|
-
only one these strings get.
|
|
455
|
-
|
|
456
|
-
Blocks import it **directly** — `import { landing, ui } from "@repo/ui/content/landing"` —
|
|
457
|
-
never as props from `index.astro`. Astro serializes island props, so passing content into
|
|
458
|
-
`<PricingTable client:visible />` would write every string into the HTML payload *and*
|
|
459
|
-
still ship the defaults inside the island's bundle. Direct import keeps the static blocks
|
|
460
|
-
at zero JavaScript.
|
|
461
|
-
|
|
462
|
-
Five rules keep that file mechanically translatable — a translation layer reads a keyed
|
|
463
|
-
record and nothing else. Follow them when you add a block or a key:
|
|
464
|
-
|
|
465
|
-
1. **Max three levels below a namespace** (`landing.features.title`). Compiler-based i18n
|
|
466
|
-
libraries emit one flat identifier per message and cannot see deeper nesting.
|
|
467
|
-
2. **Position is never the key.** Lists are arrays whose items carry a stable `id`, so
|
|
468
|
-
reordering the feature grid cannot silently reattach the wrong translation. One list is
|
|
469
|
-
exempt — a tier's `features` bullets stay a plain `string[]`, because nothing reads them
|
|
470
|
-
individually (a feature id and an FAQ id both anchor an item that outlives its wording)
|
|
471
|
-
and a tier's bullets are rewritten with that tier. The content file states the trade-off
|
|
472
|
-
in full.
|
|
473
|
-
3. **Single-brace `{token}` placeholders, never a template literal.** Copy is data; a
|
|
474
|
-
template literal is a function, which no extraction tool can read. Render with
|
|
475
|
-
`interpolate()` from `@repo/ui/lib/interpolate`.
|
|
476
|
-
4. **No runtime concatenation.** `/month` plus `", billed annually"` is two whole
|
|
477
|
-
messages (`ui.pricing.perMonth`, `ui.pricing.perMonthAnnual`) — word order does not
|
|
478
|
-
survive the seam in every language.
|
|
479
|
-
5. **Only user-visible strings move.** Section `id`s and the same-page anchors pointing at
|
|
480
|
-
them are structure and stay in the block. A few things break the rule, all because a
|
|
481
|
-
thing rewritten *with* the copy belongs *near* the copy: the whole `tiers` array (prices
|
|
482
|
-
and `ctaHref`s included); every `icon`, held as a registry *name* like `"zap"` and
|
|
483
|
-
resolved to a component by `packages/ui/src/lib/icons.ts`, and every logo `mark`,
|
|
484
|
-
resolved by `blocks/logo-cloud.tsx`; every outbound link (`*Href`), which leaves the
|
|
485
|
-
page and so cannot break a section link; and the code the page quotes (terminal
|
|
486
|
-
commands, module names, file paths). A translation layer reads `id`, `icon`, `mark`,
|
|
487
|
-
every `*Href` and the quoted code as non-message data. A pair of backticks inside a
|
|
488
|
-
message renders as `<code>` through `inlineCode()` from `@repo/ui/lib/inline-code`.
|
|
489
|
-
|
|
490
|
-
**No copy that goes stale.** Do not write a version number, a release date or a count into a message. Say something general and link to where the current value lives: the hero pill says "See what's new" and links to the changelog, so it stays true across every release.
|
|
491
|
-
|
|
492
|
-
Two consequences worth knowing. Blanking a navbar or footer link's label in content drops
|
|
493
|
-
that link, which is how a removed section loses its nav entry without editing a block. And
|
|
494
|
-
the theme toggle's labels deliberately stay in `packages/ui/src/lib/theme.ts`: that file is
|
|
495
|
-
inlined verbatim into a pre-paint `<script>` and is import-free on purpose.
|
|
496
|
-
|
|
497
|
-
**The default copy is Saasaloy's own.** A fresh project's page describes Saasaloy, and
|
|
498
|
-
`config.app.name` in `packages/config/src/sections/app.ts` defaults to `"Saasaloy"`, so the brand and the
|
|
499
|
-
words agree until you replace both. The two skills below replace them in one pass.
|
|
500
|
-
|
|
501
|
-
**Making this project yours.** Four skills ship with the base (linked at
|
|
502
|
-
`.claude/skills/`, real files in `.agents/skills/`). The first two run in order:
|
|
503
|
-
|
|
504
|
-
1. **`saasaloy-setup`** asks ten questions about the product — starting with its name — and
|
|
505
|
-
writes the answers to `docs/product-brief.md`. Every question carries sample answers you
|
|
506
|
-
can take, edit, or ignore. It also sets `config.app.name` and `config.app.locale`. Nothing else
|
|
507
|
-
reads your product knowledge out of your head, so run it first; other skills read the
|
|
508
|
-
brief rather than interviewing you again.
|
|
509
|
-
2. **`saasaloy-landing-copy`** turns that brief into the landing page's words. It drafts
|
|
510
|
-
into `docs/landing-copy-draft.md` for you to review and edit, then writes
|
|
511
|
-
`packages/ui/src/content/landing.ts` once you approve, then deletes the draft.
|
|
512
|
-
|
|
513
|
-
The other two have no place in that order, because they run whenever the thing they own moves:
|
|
514
|
-
|
|
515
|
-
3. **`saasaloy-design`** keeps `apps/web/DESIGN.md` true, and `apps/admin/DESIGN.md` when the admin app is installed. Its `theme` flow swaps the
|
|
516
|
-
preset and re-derives the contract; `update` re-derives after you change `web.css` or
|
|
517
|
-
add components; `audit` reports where the code and the contract disagree. It reads the
|
|
518
|
-
product brief when one exists and never writes it.
|
|
519
|
-
4. **`saasaloy-config`** covers `@repo/config`: the config-versus-`.env` rule, adding a
|
|
520
|
-
section, the merge rule, and why an override is not taking effect.
|
|
521
|
-
|
|
522
|
-
Invoke them rather than editing thirteen blocks by hand — and if you do edit by hand, keep the
|
|
523
|
-
strings in the content module so the next pass finds them.
|
|
138
|
+
- **`saasaloy-design`** keeps each app's `DESIGN.md` true, and swaps the web theme for a shadcn preset.
|
|
139
|
+
- **`saasaloy-config`** covers `@repo/config`: a section, the merge rule, config versus `.env`.
|
|
140
|
+
- **`saasaloy-env`** covers `packages/env`: adding a key, the server and client split, `pnpm env:setup`.
|
|
141
|
+
- **`saasaloy-testing`** says which test a change needs under this project's testing mode.
|
|
142
|
+
- **`saasaloy-deploy`** covers `pnpm deploy:production`, its gates and the rollback.
|
|
524
143
|
|
|
525
144
|
### Naming Conventions
|
|
526
145
|
|
|
527
|
-
- **
|
|
528
|
-
- **Components**: PascalCase (`UserProfile`, `DataTable`)
|
|
529
|
-
- **Constants**: UPPER_SNAKE_CASE (`API_BASE_URL`, `MAX_RETRIES`)
|
|
530
|
-
- **Types/Interfaces**: PascalCase (`User`, `ApiResponse`)
|
|
146
|
+
- **Code**: camelCase functions (`fetchUserData`), PascalCase components and types (`UserProfile`, `ApiResponse`), UPPER_SNAKE_CASE constants (`MAX_RETRIES`)
|
|
531
147
|
- **Files**: kebab-case for components (`user-profile.tsx`), camelCase for utilities (`utils.ts`)
|
|
532
148
|
|
|
533
149
|
## Linting, Formatting, and Commit Hooks
|
|
534
150
|
|
|
535
|
-
The linter is **[oxlint](https://oxc.rs)** configured from
|
|
536
|
-
**[Ultracite](https://www.ultracite.ai)**'s presets, with **Prettier** and **Stylelint**
|
|
537
|
-
owning formatting. All four run from `oxlint.config.mjs`, `prettier.config.js` and
|
|
538
|
-
`stylelint.config.js` at the root — there is no shared config package, because oxlint
|
|
539
|
-
cannot consume one (`extends` takes file paths, JSON only).
|
|
151
|
+
The linter is **[oxlint](https://oxc.rs)** configured from **[Ultracite](https://www.ultracite.ai)**'s presets, with **Prettier** and **Stylelint** owning formatting. All four run from `oxlint.config.mjs`, `prettier.config.js` and `stylelint.config.js` at the root — there is no shared config package, because oxlint cannot consume one (`extends` takes file paths, JSON only).
|
|
540
152
|
|
|
541
153
|
- `pnpm lint` — the gate. Four passes, in order:
|
|
542
|
-
1. `lint:types` — oxlint with `--type-aware` over `packages/env/src`, `packages/tooling/src` and `packages/ui/src`
|
|
154
|
+
1. `lint:types` — oxlint with `--type-aware` over `packages/config/src`, `packages/env/src`, `packages/tooling/src` and `packages/ui/src`
|
|
543
155
|
2. `lint:code` — oxlint over everything, no type information
|
|
544
156
|
3. `lint:css` — Stylelint over `**/*.css`
|
|
545
157
|
4. `format:check` — `prettier --check .`
|
|
546
|
-
- `pnpm lint:fix` — passes 1-3 with `--fix`: the type-aware oxlint invocation over
|
|
547
|
-
the same three folders, the plain one over everything, then Stylelint. **Never** add
|
|
548
|
-
`--fix-suggestions`: it rewrites `a[i++]` to `a[i += 1]`, which is a different program.
|
|
158
|
+
- `pnpm lint:fix` — passes 1-3 with `--fix`: the type-aware oxlint invocation over the same four folders, the plain one over everything, then Stylelint. **Never** add `--fix-suggestions`: it rewrites `a[i++]` to `a[i += 1]`, which is a different program.
|
|
549
159
|
- `pnpm format` — `prettier --write .`
|
|
550
|
-
- `pnpm typecheck` — `
|
|
160
|
+
- `pnpm typecheck` — `turbo run typecheck`, which runs `tsc` in each workspace, and it must pass before you commit.
|
|
551
161
|
|
|
552
|
-
**Why the type-aware pass is scoped and the plain one is not.** `--type-aware` is a
|
|
553
|
-
global CLI switch, so the split is by invocation rather than by config. It stays off
|
|
554
|
-
`.astro` because `apps/web/tsconfig.json` includes the build-generated
|
|
555
|
-
`.astro/types.d.ts`, which would make `astro sync` a prerequisite of every `pnpm lint`,
|
|
556
|
-
including on a fresh clone. Do not merge the two passes.
|
|
162
|
+
**Why the type-aware pass is scoped and the plain one is not.** `--type-aware` is a global CLI switch, so the split is by invocation rather than by config. It stays off `.astro` because `apps/web/tsconfig.json` includes the build-generated `.astro/types.d.ts`, which would make `astro sync` a prerequisite of every `pnpm lint`, including on a fresh clone. Do not merge the two passes.
|
|
557
163
|
|
|
558
|
-
**Markdown is not formatted.** `.prettierignore` excludes `**/*.md` because Ultracite's
|
|
559
|
-
Prettier config sets `proseWrap: "never"`, which would collapse every hand-wrapped
|
|
560
|
-
paragraph — this file included — into a single line.
|
|
164
|
+
**Markdown is not formatted.** `.prettierignore` excludes `**/*.md` because Ultracite's Prettier config sets `proseWrap: "never"`, which would collapse every hand-wrapped paragraph into a single line.
|
|
561
165
|
|
|
562
166
|
**Commit hooks are installed by husky** on your first `pnpm install`, and they need a `.git` directory, which `saasaloy init` creates for you. The root `prepare` script is `husky && node packages/tooling/src/link-skills.ts`, so the same install also links every folder in `.agents/skills/` into `.claude/skills/`. pnpm skips `prepare` when an install changes nothing, so after you add a skill folder to a checkout that is already installed, run `pnpm skills:link`. The hooks:
|
|
563
167
|
|
|
564
|
-
- `pre-commit` runs **lint-staged** over staged files only — oxlint `--fix`, Stylelint
|
|
565
|
-
|
|
566
|
-
whole project graph, which defeats staged-file scoping.
|
|
567
|
-
- `commit-msg` runs **commitlint** with `@commitlint/config-conventional`, so messages
|
|
568
|
-
must read `type(scope): subject` — `feat:`, `fix(api):`, `chore(deps):`.
|
|
168
|
+
- `pre-commit` runs **lint-staged** over staged files only — oxlint `--fix`, Stylelint `--fix`, Prettier `--write`. It skips the type-aware pass on purpose: that one needs the whole project graph, which defeats staged-file scoping.
|
|
169
|
+
- `commit-msg` runs **commitlint** with `@commitlint/config-conventional`, so messages must read `type(scope): subject` — `feat:`, `fix(api):`, `chore(deps):`.
|
|
569
170
|
|
|
570
|
-
Bypass in a genuine emergency with `git commit --no-verify`, or `HUSKY=0` to skip every
|
|
571
|
-
hook (which is also how you keep hooks out of CI).
|
|
171
|
+
Bypass in a genuine emergency with `git commit --no-verify`, or `HUSKY=0` to skip every hook (which is also how you keep hooks out of CI).
|
|
572
172
|
|
|
573
173
|
## Testing Instructions
|
|
574
174
|
|
|
@@ -580,9 +180,9 @@ Testing mode: `off`. This project ships no module tests, and `saasaloy add` writ
|
|
|
580
180
|
- Turn module tests on with `saasaloy testing tests-after`, or `saasaloy testing tdd` to work test-first.
|
|
581
181
|
<!-- /saasaloy:testing -->
|
|
582
182
|
|
|
183
|
+
- Run every gate at once: `pnpm check`. It runs `typecheck`, `lint`, `test` and `build` in that order, stops at the first failure, and edits no file. Run `pnpm lint:fix` and `pnpm format` first.
|
|
583
184
|
- Run type checking: `pnpm typecheck` (must pass before commits)
|
|
584
|
-
- Run linting: `pnpm lint` (see above — it reports, `pnpm lint:fix` fixes)
|
|
585
|
-
- Check formatting: `pnpm format:check`, or `pnpm format` to rewrite
|
|
185
|
+
- Run linting: `pnpm lint` (see above — it reports, `pnpm lint:fix` fixes, and `pnpm format` rewrites the formatting)
|
|
586
186
|
- Run the tests: `pnpm test`. It runs `turbo run test` (each workspace's own `test` script), then `vitest run` from the root, whose `vitest.config.ts` treats every workspace under `apps/*` and `packages/*` as a project. Write new tests for Vitest: put a `*.test.ts` file beside the code, and give the workspace a `vitest.config.ts` only when it needs setup of its own. Do not add a per-workspace `test` script that calls Vitest, or the file runs twice. `packages/env` is the exception: its tests run on `node --test` through its own `test` script, and the root config leaves it out.
|
|
587
187
|
- Run the browser suite: `pnpm e2e`, once `saasaloy add e2e` is installed. It is Playwright against the running apps, in `packages/e2e`. Run `pnpm e2e:install` once per machine first to download Chromium. The root `vitest.config.ts` leaves `packages/e2e` out, so `pnpm test` never collects a Playwright spec. The `saasaloy-e2e` skill covers adding a flow and reading a red run.
|
|
588
188
|
- `packages/tooling` tests run on Vitest through the root `vitest.config.ts`, like every other workspace. The workspace has a `typecheck` script and no `test` script, so `pnpm test` runs each file once.
|
|
@@ -598,6 +198,18 @@ Testing mode: `off`. This project ships no module tests, and `saasaloy add` writ
|
|
|
598
198
|
- **Merge a hotfix branch into `main`, never rebase it.** A rebase rewrites the commit its release tag names.
|
|
599
199
|
- **An agent deploys only after the owner says so in the same session.** It runs `pnpm deploy:production --dry-run` and reports first. The `saasaloy-deploy` skill is the procedure, and `docs/runbook-deploy.md` holds this project's own deploy steps.
|
|
600
200
|
|
|
201
|
+
## Unattended work
|
|
202
|
+
|
|
203
|
+
An agent may build this project with no person at the keyboard. These rules apply only then, and they override "Ask First" where they say so.
|
|
204
|
+
|
|
205
|
+
- **The signal is `autonomy: afk`** in the YAML frontmatter of `docs/product-brief.md`. Only a person sets it: `saasaloy-setup` asks "Run the build unattended?" as its last question. With no such field, every skill keeps its attended path and asks.
|
|
206
|
+
- **A person supplies the two inputs**: the env values in `packages/env/.env`, and the brief, written through the attended `saasaloy-setup` interview. The person also runs `pnpm env:setup` before the first build. The brief is complete when all ten answers are filled (Name, Language, Audience, Problem, Current alternative, Differentiator, Proof, Tone, Pricing, Where "sign up" goes) and none is tagged `weak:`. With an incomplete brief, stop before the first module and list each missing or weak section under `## Blocked` in `docs/build-log.md`.
|
|
207
|
+
- **`pnpm check` is the gate.** Run `pnpm lint:fix` and `pnpm format`, then `pnpm check`. A stage is not done until it passes.
|
|
208
|
+
- **Commit once per stage on `build/mvp`.** Create the branch if it does not exist, and continue on it when it does. Commit through the Husky and commitlint hooks, never with `--no-verify`. Never push.
|
|
209
|
+
- **`docs/build-log.md` is the output.** Give each stage a `## <stage>` section with what it did and its commit hash. Put what stopped the run under `## Blocked`, and each step you leave for a person under `## Left for a human`. A new session reads the log first and continues from the last stage with a commit.
|
|
210
|
+
- **Allowed without asking:** database schema changes and migrations, new dependencies (exact-pinned), and new workspace packages (with a `clean` script).
|
|
211
|
+
- **Still forbidden:** a deploy (`pnpm deploy:production`, `wrangler deploy`), anything that spends money or creates a vendor account, editing a secret (`packages/env/.env`, `.env.prod`, a dashboard), deleting data outside the local dev database, and `git push`. Every other "Ask First" item stays forbidden too. Log the step under `## Left for a human` and carry on.
|
|
212
|
+
|
|
601
213
|
## Boundaries
|
|
602
214
|
|
|
603
215
|
### ✅ Always Do
|
|
@@ -608,19 +220,19 @@ Testing mode: `off`. This project ships no module tests, and `saasaloy add` writ
|
|
|
608
220
|
- Give every new app or package a `clean` script backed by `rimraf` (see above)
|
|
609
221
|
- Use TypeScript strict mode (no `any` without explicit reason)
|
|
610
222
|
- Use workspace package names (`@repo/ui`, `@repo/config`, `@repo/tsconfig`) for imports
|
|
611
|
-
- Put a value you would otherwise write twice in `@repo/config`, and a per-deployment value in
|
|
612
|
-
`.env`/`.dev.vars` — see above
|
|
223
|
+
- Put a value you would otherwise write twice in `@repo/config`, and a per-deployment value in `packages/env/.env` — see above
|
|
613
224
|
|
|
614
225
|
### ⚠️ Ask First
|
|
615
226
|
|
|
227
|
+
Under `autonomy: afk`, "Unattended work" above decides these instead.
|
|
228
|
+
|
|
616
229
|
- Adding new dependencies (especially to root `package.json`)
|
|
617
230
|
- Building new UI before the owner has approved a mockup. Show screenshots of the mockup first and get approval. A change after approval gets a new mockup, not a fix after the work lands
|
|
618
231
|
- Modifying Turborepo configuration (`turbo.json`)
|
|
619
232
|
- Changing TypeScript strictness settings
|
|
620
233
|
- Modifying the husky hooks (`.husky/`), `lint-staged.config.js`, or `commitlint.config.js`
|
|
621
234
|
- Creating new workspace packages
|
|
622
|
-
- Changing `oxlint.config.mjs`, `prettier.config.js`, or `stylelint.config.js` — including
|
|
623
|
-
turning a rule off. Suppress the one occurrence with a comment that says why instead
|
|
235
|
+
- Changing `oxlint.config.mjs`, `prettier.config.js`, or `stylelint.config.js` — including turning a rule off. Suppress the one occurrence with a comment that says why instead
|
|
624
236
|
- Database schema changes or migrations
|
|
625
237
|
- CI/CD workflow modifications (`.github/workflows/`)
|
|
626
238
|
|
|
@@ -628,12 +240,10 @@ Testing mode: `off`. This project ships no module tests, and `saasaloy add` writ
|
|
|
628
240
|
|
|
629
241
|
- Never use `npm` or `npx`, instead use `pnpm` & `pnpm dlx`
|
|
630
242
|
- Never use `rm -rf` in a package script — it breaks on Windows; use `rimraf`
|
|
631
|
-
- Commit secrets or API keys. `packages/env/.env` is gitignored; `packages/env/.env.example`
|
|
632
|
-
is tracked and holds local defaults only
|
|
243
|
+
- Commit secrets or API keys. `packages/env/.env` is gitignored; `packages/env/.env.example` is tracked and holds local defaults only
|
|
633
244
|
- Modify `node_modules/` or `pnpm-lock.yaml` manually (use `pnpm install`)
|
|
634
245
|
- Remove or disable TypeScript strict mode
|
|
635
|
-
- Remove or disable the lint-staged or commitlint hooks, or commit with `--no-verify`
|
|
636
|
-
as a habit rather than an emergency
|
|
246
|
+
- Remove or disable the lint-staged or commitlint hooks, or commit with `--no-verify` as a habit rather than an emergency
|
|
637
247
|
- Use `any` type without explicit `@ts-expect-error` or `@ts-ignore` with justification
|
|
638
248
|
- Break the workspace structure (don't move packages outside `apps/*` or `packages/*`)
|
|
639
|
-
- Commit without running type checks and linting
|
|
249
|
+
- Commit without running type checks and linting
|