AGENT SKILL

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

  • env owns a value the platform supplies per deployment, secret or not. A database URL, an API origin, a Stripe key, a provider selection.
  • config owns 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 add refuses two modules claiming one key and names both, and the base's own app is taken; at runtime a duplicate throws at module load. The file name and the key passed to defineSection must match, and add refuses a section file where they differ.
  • The section file lives in packages/config, not in the capability. @repo/config is 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.ts does for config.subscription.appName || config.app.name.

When an override does not take effect

  1. The section is not installed. config.shop only exists once saasaloy add shop has patched src/sections.ts. Check the array.
  2. You edited a section file, not project.ts. A module-owned section file may be rewritten by saasaloy update. Move the edit to project.ts.
  3. You expected a deep merge. One level below the section is the whole rule; a nested record is replaced whole.
  4. 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 env value by definition.
  • Schema validation. typecheck is the gate.
  • A <CAP>_PROVIDER key. Provider selection stays in env.
  • The dev ports. 3000/3001/4000 are read by Node config files at build time.

04 同仓库更多 Skills

mimukit
mimukit/saasaloy

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.

★ 4
mimukit
mimukit/saasaloy

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.

★ 4
mimukit
mimukit/saasaloy

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.

★ 4
mimukit
mimukit/saasaloy

saasaloy-beta

The beta module's own procedure.

★ 4
mimukit
mimukit/saasaloy

helper

暂无简介

★ 4
mimukit
mimukit/saasaloy

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.

★ 4