Starters
This page is for contributors who change a starter: how to work on one, which files must
stay identical and what CI checks. Each starter is a pnpm workspace under .starters/<starter>, copied into a new
project with pnpx giget@latest gh:Frigear-nu/frigear-nu/.starters/<starter> <dir>.
| Starter | What it is | Guide |
|---|---|---|
.starters/workspace | apps/web: users, auth, account, admin | Workspace starter |
.starters/mobile | apps/mobile: a Capacitor app on @frigear-nu/mobile against any issuer | Mobile starter |
.starters/mobile-standalone | workspace + apps/mobile; apps/web adds @frigear-nu/oauth-server and the API | Standalone mobile starter |
How starters differ from packages
- They are not part of the repository's pnpm workspace:
pnpm-workspace.yamllists onlyapps/*andpackages/*. - They depend on the published
@frigear-nu/*versions, neverworkspace:*orcatalog:. - Each has its own
AGENTS.md.
Keep shared files identical
These are the same in every starter: .github/, .nvmrc, .gitignore, pnpm-workspace.yaml, scripts/ and
packages/. apps/mobile is the same in mobile and mobile-standalone. mobile-standalone/apps/web differs from
workspace/apps/web only in nuxt.config.ts, package.json, .env.example, AGENTS.md, the migrations and
server/api/.
drift job of .github/workflows/starters.yml fails
otherwise.The shared scripts/prepare-env.mjs (pnpm prepare:env) has no dependencies. It copies each .env.example and fills
in empty secrets, never overwriting a value.
Work on a starter in a copy
Work in a copy outside the repository, then copy the changes back:
cp -R .starters/<starter> "$TMPDIR/<starter>"
cd "$TMPDIR/<starter>" && pnpm install
To try unreleased packages, point @frigear-nu/* at packed or linked builds with overrides, in the copy only.
node_modules, .nuxt, .output, .data, .env, pnpm-lock.yaml,
capacitor.config.json or the native ios/ and android/ folders.Regenerate the migrations
After releasing a module that changes a schema, or bumping a starter's versions, regenerate the migrations of every
starter with apps/web, in the copy:
pnpm db:generate
Then commit apps/web/server/db/migrations back. CI fails when they are out of date.
Release packages before merging
A starter that needs an unreleased @frigear-nu version is skipped with a warning on pull requests. On main it fails.
Release the packages first, as Publishing describes.
Keep the guides in step
Each starter has a guide under Examples. When you change a starter's files or commands, update its guide in the same change.
Next steps
- Publishing – release the packages a starter change depends on.
- Installation – the page that compares the starters for new users.