saasaloy-config
Work with @repo/config — the values this project checks into its repo and ships identically to every environment. Use when a value needs a single home, when deciding whether something belongs in config or in .env, when adding a section for a capability, when a project override is not taking effect, or when the owner says "where do I change the product name", "where do I put this constant", "config or env".
- License 许可
- MIT
- 所属仓库
- mimukit/saasaloy
- 最近更新
- 2026-11-13
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- saasaloy-config
- description
- Work with @repo/config — the values this project checks into its repo and ships identically to every environment. Use when a value needs a single home, when deciding whether something belongs in config or in .env, when adding a section for a capability, when a project override is not taking effect, or when the owner says "where do I change the product name", "where do I put this constant", "config or env".
03 SKILL.md 正文
saasaloy-config — one home for a checked-in value
@repo/config is a frozen plain object of values this project checks into its repo. Read it
with a plain import, from an app, a capability or a React island alike:
import { config } from "@repo/config";
config.app.name;
config.app.locale;
config.auth.adminRole; // once `auth` is installed
There is no factory, no env argument, no async and no I/O. The object is built once at
module load and frozen, so a bundler can inline it.
The rule: config or .env
envowns a value the platform supplies per deployment, secret or not. A database URL, an API origin, a Stripe key, a provider selection.configowns a value checked into the repo that is the same in every deployment. The product name, the locale, a role string.
The test. Two deployments of this project — production and staging. If the value can
differ between them, it is env. If it cannot, it is config. A value that differs between
two different projects but not between one project's environments is config.
packages/config imports nothing, @repo/env included, so a section cannot read an env
var. A value derived from both channels is derived where it is used, not in a section file.
Not the landing copy
Everything on the landing page, prices and tier ids included, lives in
packages/ui/src/content/landing.ts, and saasaloy-landing-copy owns it. config holds
the facts more than one workspace reads: the product name, the locale, the legal paths, and
whatever an installed module's section adds.
The four files
| Path | Who owns it |
|---|---|
src/project.ts |
You. The only file here you are expected to edit. Nothing overwrites it. |
src/sections.ts |
The registry. saasaloy add patches one line into it; do not hand-edit the array. |
src/sections/<key>.ts |
The module that installed it (app belongs to the base template). |
src/define.ts |
The base template. The composition core. |
Changing a value
Edit src/project.ts. It is typed as a partial of the composed shape, so a key no
installed section defines is a typecheck error rather than a value nothing reads.
export const project: ProjectOverride = {
app: { name: "Ledgerly", locale: "en-GB" },
};
The merge goes one level below the section, and no deeper. app: { name: "..." }
replaces the name and keeps the rest of app. A nested record or an array is replaced
whole, so app: { legal: { termsPath: "/legal/terms" } } must also name privacyPath.
Run pnpm typecheck after an edit. That is the only validation there is: the values are
literals in this repo, so a wrong one is a review problem rather than a runtime one.
Adding a section
A capability contributes one section, keyed by the module name. The module ships one file
into packages/config/src/sections/<key>.ts and registers it with a plugin-array patch:
// packages/config/src/sections/shop.ts
import { defineSection } from "@repo/config/define";
export function shopConfig() {
return defineSection("shop", {
defaultCurrency: "USD",
maxCartItems: 50,
});
}
// the module's registry-item.json
{
"file": "packages/config/src/sections.ts",
"kind": "plugin-array",
"exportName": "sections",
"arrayProp": "sections",
"call": "shopConfig",
"import": { "name": "shopConfig", "from": "./sections/shop" }
}
Four rules:
- The key is the module name, flat, and unique.
saasaloy addrefuses two modules claiming one key and names both, and the base's ownappis taken; at runtime a duplicate throws at module load. The file name and the key passed todefineSectionmust match, andaddrefuses a section file where they differ. - The section file lives in
packages/config, not in the capability.@repo/configis the leaf of the dependency graph — it imports nothing, so everything may import it, including the capability whose values these are. A section inside the capability would invert that and cycle. - Import the helper by subpath,
@repo/config/define, never by relative path. - A section never reads another section. They are composed side by side. Apply a
fallback between two sections where the value is used, the way
apps/api/src/subscription-store.tsdoes forconfig.subscription.appName || config.app.name.
When an override does not take effect
- The section is not installed.
config.shoponly exists oncesaasaloy add shophas patchedsrc/sections.ts. Check the array. - You edited a section file, not
project.ts. A module-owned section file may be rewritten bysaasaloy update. Move the edit toproject.ts. - You expected a deep merge. One level below the section is the whole rule; a nested record is replaced whole.
- Something reads the value at build time. A Node config file (
astro.config.mjs,vite.config.ts) is not part of the app graph and keeps its own literals on purpose.
What is not here
- A runtime override channel. A value that must change per deployment is an
envvalue by definition. - Schema validation.
typecheckis the gate. - A
<CAP>_PROVIDERkey. Provider selection stays inenv. - The dev ports. 3000/3001/4000 are read by Node config files at build time.
04 同仓库更多 Skills
saasaloy-subscription
Runbook for the subscription capability — provider-agnostic subscriptions in packages/subscription, with a plan file, a projection table, a billable-subject file, plan entitlements and per-provider modules. Use when adding a plan, adding a plan feature or a numeric limit, gating an API route with requireFeature or requireWithinLimit, reading the 402 it returns, working out why a subject resolves to the free plan, wiring a checkout or portal route, reading a SubscriptionError, choosing or switching SUBSCRIPTION_PROVIDER, registering a webhook in the vendor's dashboard, writing a third subscription provider, or upgrading a project that still has `billing` installed.
saasaloy-notification
Runbook for the notification module, in-app notifications for apps/app. It owns the notifications and notification_opt_outs tables, notify() in apps/api/src/lib/notify.ts, the /notifications api routes, the bell in the app header, the sidebar badge, the /notifications page with Inbox and Preferences tabs, the notification config section, and the daily prune. Use when sending a notification from an api route, adding or changing a category, changing retention, debugging a badge or bell count that does not move, or removing the module.
saasaloy-cms
Runbook for the cms module, the in-house CMS behind apps/admin. Covers code-defined collections, the Tiptap editor, drafts, revisions and redirects, the publish-time renderer, the public blog on apps/web and its 60-second cache. Use when adding a collection or a field, rendering a stored body, reusing the editor, renderer or media field from another module, moving the blog to another path, re-rendering live posts after a renderer upgrade or a STORAGE_PUBLIC_URL change, or working out why a published post is not live yet.
saasaloy-beta
The beta module's own procedure.
helper
暂无简介
saasaloy-update
Runbook for an AI agent that updates this project to a newer Saasaloy CLI and newer module versions with saasaloy update. Use when the owner says "update saasaloy", "upgrade the CLI", "pull the latest modules", "update the base template", "work the merge plan", "clear the update notes", when saasaloy update or saasaloy outdated --check exits 3 or 2, when a merge plan or .saasaloy/merge-plan.md is handed to you, or when an adopted project takes its first update. Covers the CLI upgrade, the preview, --out, the file merges, the update notes and "Notes that may apply", --resolved and --done, a file deleted locally and --restore, a three-way or two-way base, an update that skips releases, --from, the verify commands, and the exit codes.