The command line

The tooling is remy, the bin of @joeblew999/remy-ui (packages/ui/src/cli, one TypeScript module per command); an app gets it with the package (npm install, at the package's version) and names it in its package.json scripts, the same ones in every app ("dev:change": "remy change"). An app says once, in remy.config.ts, where it is deployed and its ports:

import type { RemyProject } from '@joeblew999/remy-ui/project';

export default {
  origins: { production: 'https://your-app.your-subdomain.workers.dev', docs: 'https://your-app-docs.your-subdomain.workers.dev' },
  ports: { preview: 4173, docsPreview: 4174 },   // the main checkout's; a worktree computes its own from its name
} satisfies RemyProject;

The layoutCopy Anchor Link

Every Remy repo, remy-auth included, has the same files in the same places; what is inside the product's files differs. The layout is the paths the commands and the package read, so a file anywhere else is simply not found; no checker of its own keeps it.

A new consumerCopy Anchor Link

The one recipe. A new app starts from the blank app, template/ in remy-auth at the release tag: the layout above with only the repo's own files in it (its names, one home page in every language, a docs index per site, the layout's config files at a few lines each). Everything else is the package, which one version bump upgrades.

1. Prerequisites: Node as .node-version says, gh auth login with a token that has read:packages, Google Chrome (the checks use it), and wrangler login before the first deploy.
2. npx -y giget@3.3.1 gh:joeblew999/remy-auth/template#vX.Y.Z <name>, then cd <name> and git init (the translation and plans tools read git history; npm run setup says so if it is missing).
3. Name the app: replace my-app and My app (grep -rn -i "my.app" --exclude-dir=node_modules .): package.json, wrangler.jsonc, src/service.ts, remy.config.ts's origins, docs/docs.config.ts (the product's name and source, which the app's frame reads too) and messages/en.json.
4. Node as .node-version says, then GITHUB_TOKEN=$(gh auth token) npm install once to write package-lock.json, then npm run setup (npm ci, the pinned skills and the remy skill, the AGENTS.md rules block, MCP registration, the flow's guard, the installation's checks).
5. Commit everything, package-lock.json, skills-lock.json and src/routeTree.gen.ts included. The blank app's strings come translated; after the English changes (messages/en.json, the docs), commit it and translate this once by hand, REMY_FLOW=hand npx remy i18n translate, which writes and commits the other languages; from then on dev:land does it.
6. The first deploy, by hand: npx remy cloudflare deploy, and npx remy cloudflare docs-deploy for the docs. Once the repository is on GitHub (step 7), work goes through the flow: dev:land for every finished change, dev:promote for production and the docs.
7. CI: .github/workflows/google.yml calls remy-auth's shared workflow at the same tag (every language, Google's audits on every push to main). Grant the new repository read access in the @joeblew999/remy-ui package's settings ("Manage Actions access"), or npm ci fails there.

Then the app grows in its own files: pages in src/routes/ (a page beside a parent's path, such as videos.$videoId next to videos, is videos_.$videoId.tsx: TanStack nests videos.$videoId inside videos, which then needs an <Outlet />), their links in src/remy-app.tsx, strings in messages/en.json (m from src/paraglide/messages.js), an API as a contract package and src/api/ (every procedure that takes input documents an error, or apiChecks fails: the package's api/coverage rule), docs in docs/content/. Move to a new release with npm run upgrade -- <version> (the package and the CI workflow's tag together). Two local browser runs at once share PREVIEW_PORT and the second fails to start its server: give each shell its own (PREVIEW_PORT=4232 npm run …).

A repository that publishes packagesCopy Anchor Link

A repository may also publish packages of its own (a contract, a UI package), as remy-auth does; that costs no command of its own. Its packages are npm workspaces (packages/<name>/, package.json's workspaces), and each one that is not private is published by remy packages (npm run packages -- …):

In remy.config.ts: release.package (the package whose version names the release) and release.title. A package's exports name every subpath its users import ("./video": "./src/video.ts"); anything else is refused at build time and in Playwright, whose message names the importing file, not the export map. A package's own strings are its own inlang project, compiled by its build, whose runtime follows the platform's language with one call, followLocale(runtime) (locale); the i18n tasks read it through I18N_INLANG. Checks the repository adds to a release go in its release-checks script (remy-auth: template:check, ui:verify). remy-auth sets a release's version with npm run ui:version -- X.Y.Z, which writes it everywhere it appears (the package and the blank app's pins).

Choosing the version: released, development or localCopy Anchor Link

The tooling and the package are one thing: remy-auth's npm run dev:release publishes @joeblew999/remy-ui X.Y.Z, bin included, and tags the same commit vX.Y.Z. A consumer pins that one number in its package.json (and its CI workflow's tag), and npm run upgrade -- X.Y.Z moves both. To work against remy-auth's own checkout, npm link ../remy-auth/packages/ui (and npm unlink back).

The platform supplies every npm package the app and the tasks need, at one version: they are @joeblew999/remy-ui's own dependencies (the framework, the toolchain, the checks' tools), so an app's package.json names the package, its own packages and whatever its product adds. the check's single-copies part (in remy check) fails when a package that breaks when installed twice (React, TanStack Router and Query, the MDX stringifier; the package's remy.singleCopy list) is: remove the app's own pin. The commands call an app's own hooks where it has them, as scripts of its package.json, run if present: generate (code generated before type checking; the blank app's compiles its own catalog), local (the local state an app needs before it runs, which dev, build and dev:start run first; remy-auth writes its .dev.vars and migrates its local D1 there), release-checks and test:consumers.

The development flow is code, packages/ui/src/cli/flow.ts, with four steps and a guard (how we work):

npm run test -- every is every check of ours in every language (inside remy verify). remy verify and CI end with remy test consumers, the other repositories this one serves tested as they get it: the app's test:consumers script, nothing by default; in remy-auth, the consumer fixture, which builds the blank app and a package it owns from this commit's platform (the package from a tarball with a version of its own, the tasks from a copy outside any node_modules, the template's .npmrc) and runs install, skills (installed once per pinned list, then reused), the tooling invariants, the check, the quick browser checks, the docs and a dry-run publish (~1.5 to 3 min, mostly the network). A change that would break another repository fails there, not in that repository. Tests are type-checked with the app (tsconfig.json includes tests/). Google's level is npm run test -- google (Lighthouse audits, local; CI on every push and tag) and npm run test -- cwv (Core Web Vitals on a throwaway Cloudflare Worker); the release runs both.

Where checks run: the shared package's own behaviour is proven once, in remy-auth, before each release. An app built on the package runs a contract set (its pages render, site and app pages stay apart, its own features work) plus Google's level on its own site pages, not the whole package suite again. Keep checks cheap rather than dropping them (Playwright's clock rather than real waits, one browser page per check, parallel workers). Checks loop over checkedLocales from @joeblew999/remy-ui/checks, which honours CHECK_LOCALES. Every step says how long it took.

TranslationsCopy Anchor Link

One layout in every app, so the same remy i18n commands work everywhere (the rule for who translates is one writer):

Two pipelines, one for each kind of text, the same pattern in both: detect offline with git, translate with the machine's Claude Code (headless, no tools), commit. Both are TypeScript in the package (packages/ui/src/cli/i18n.ts, translate.ts: remy i18n check, remy i18n translate); the tasks below forward to them.

• UI messages (Paraglide): the catalogs, locales and base locale come from inlang's own settings.json (I18N_INLANG, else the one project git knows). Detected: missing catalogs and keys (jq), lost or invented {placeholders} (@lingual/i18n-check), keys whose English changed since the catalog's last commit (git, jq), plural categories the locale needs (Intl.PluralRules, tasks/i18n/messages/plurals.mjs: no upstream tool checks them).
• Docs (Fumadocs): the folder is I18N_DOCS_DIR (default docs/content); each site with an i18n.json translates every English page into each of its languages. Detected: missing and stale pages (git), orphans, and Fumadocs UI's own text (ui/<lang>.json against ui/en.json).
• The translator is the machine's Claude Code headless (claude -p), with no tools, no MCP servers, skills or project settings, and structured output: a catalog's keys come back as JSON and are merged in English key order; a page comes back whole, and is written only when it is a page (page.ts). The prompts are packages/ui/src/cli/prompts.ts. One call per language (messages) or per page (docs), I18N_JOBS at a time.
• Checks need no key, no network and full git history (a shallow clone is refused). Translating uses the Claude login on the machine.
• An app with no inlang project and no docs sites gets "nothing to check" and exit 0.

Settings: I18N_MODEL (default sonnet), I18N_JOBS (4), I18N_COMMIT=0 (leave the change uncommitted for review), I18N_BRANCH (main).

CloudflareCopy Anchor Link

npx remy cloudflare <command>; each says in its header comment whether it is local or remote (and production).

Credentials come from Wrangler's login, or from the keychain through fnox (tooling).

PlansCopy Anchor Link

The plans rule (how we work) as commands (npm run plans -- …), the same in every project: .plans/now.md is the one ordered list, .plans/*.md the few open plan files, .plans/done/ and .plans/parked/ the rest, .plans/stability-log.md optional. A project with no .plans/ passes plans check and has nothing to list.

close and park change files and stage the move but never commit: read git diff, then npm run dev:change.