Tooling and scripts

Workspace

Package manager: pnpm 10 (packageManager: pnpm@10.28.2). Node 20 or newer. CI uses Node 24.
Workspaces in pnpm-workspace.yaml: apps/*, packages/*, tooling/*.
Dependency versions are pinned once in the catalog: block of pnpm-workspace.yaml and referenced as "catalog:" in each package.json. Change a version there, not per package.
Add dependencies with pnpm add, for example pnpm --filter saas add some-package. Do not edit package.json by hand.
Turborepo (turbo.json) runs tasks. globalEnv lists the variables that affect the build cache: NODE_ENV, NEXT_PUBLIC_SITE_URL, NEXT_PUBLIC_SAAS_URL, AUTH_TRUSTED_ORIGINS, CORE_API_URL, CORE_API_SERVICE_ID, SERVICE_AUTH_SECRET and two Next flags.

Root scripts

Run from frontend/.

Script	Command	Notes
`pnpm dev`	`bash ../tools/ensure-core-api.sh --start && dotenv -c -- turbo dev --filter=saas --filter=marketing`	Makes sure the core API is up first. Starts it from `../backend` if not
`pnpm dev:app`	The same without the API check
`pnpm build`	`turbo build --filter=saas --filter=marketing`
`pnpm start`	`dotenv -c -- turbo start --filter=saas`
`pnpm type-check`	`dotenv -c -- turbo type-check --filter=saas`	Only the `saas` app
`pnpm lint`	`oxlint .`
`pnpm lint:fix`	`oxlint --fix .`
`pnpm format`	`oxfmt .`
`pnpm format:check`	`oxfmt --check .`
`pnpm test`	`dotenv -c -- turbo test`
`pnpm clean`	`turbo clean`
`pnpm check:core-api`	`bash tools/check-no-direct-core-api.sh`	See below
`pnpm check:theme`	`node tools/check-theme-tokens.mjs`	See Theming

dotenv -c loads .env and its cascade (.env.local and so on) from the repo root before running Turborepo. There are no db:* scripts. The Prisma package is gone from this repo.

App scripts

App	Script	Command
`saas`	`dev`	`next dev --port 3000`
`saas`	`build`	`next build --webpack`
`saas`	`type-check`	`next typegen && tsc --noEmit`
`saas`	`test`, `test:watch`, `test:coverage`	Vitest
`saas`	`e2e`, `e2e:ci`	Playwright
`marketing`	`dev`	`next dev --port 3001`
`marketing`	`build`	`next build --webpack`, a static export
`marketing`	`type-check`	`next typegen && tsc --noEmit`

Production builds use webpack (--webpack). next.config.ts also sets a turbopack.root, which applies to next dev. Each package (ui, auth, i18n, payments, logs, notifications, utils) has its own type-check script (tsc --noEmit), but the root pnpm type-check filters to saas. Package code is still checked there, because saas imports it as source.

Type checking

next typegen generates the route types first, so typed params and links are current before tsc runs. Run pnpm type-check before every push. It is the slowest check, so run it once, not in parallel with other heavy jobs. tooling/typescript (@repo/tsconfig) holds three presets:

Preset	Used by	Notable options
`base.json`	Extended by the other two	`strict`, `strictNullChecks`, `moduleResolution: "bundler"`, `module: "Preserve"`, `isolatedModules`, `resolveJsonModule`, `skipLibCheck`, `types: ["node"]`
`nextjs.json`	`apps/saas`, `apps/marketing`	DOM libs, `noEmit`, the `next` plugin
`react-library.json`	`packages/*`	`ES2021` and DOM libs

noUnusedLocals and noUnusedParameters are off. oxlint reports unused code instead.

Linting

oxlint, configured in .oxlintrc.json:

{
	"plugins": ["typescript", "react", "import", "jsx-a11y", "oxc"],
	"ignorePatterns": [
		"**/.content-collections/**",
		"**/prisma/zod/index.ts",
		"**/orpc-router.generated.d.ts"
	],
	"options": { "typeAware": true }
}

Type aware rules run through oxlint-tsgolint, a root dependency. There is no ESLint in this repo. Lint one file while working: pnpm exec oxlint path/to/file.tsx. Disable comments use the oxlint form, for example // oxlint-disable-line eslint-plugin-react-hooks/exhaustive-deps.

Formatting

oxfmt, configured in .oxfmtrc.json:

100 columns, double quotes, semicolons, parentheses around arrow parameters.
Imports are sorted into groups: builtin, external, internal and subpath, then parent, sibling and index, then styles.
Tailwind classes are sorted in className attributes and inside cn(...), using tooling/tailwind/theme.css as the stylesheet.
package.json keys are sorted.
JSON files get no trailing commas.

Source files use tabs.

Git hooks

Husky, installed by the prepare script.

Hook	Runs
`commit-msg`	`pnpm exec commitlint --edit "$1"`
`pre-commit`	`pnpm exec lint-staged`
`pre-push`	The theme check over the whole tree, then oxlint on the files changed in the push

lint-staged

.lintstagedrc.json:

{
	"*.{ts,tsx,js,jsx,mjs,cjs}": ["oxfmt", "oxlint --fix"],
	"*.{json,jsonc}": ["oxfmt"],
	"{apps,packages}/**/*.{ts,tsx,css}": ["node tools/check-theme-tokens.mjs"]
}

pre-push

The script collects the files that differ between the upstream and HEAD (falling back to the last commit), keeps script files, and skips any file that also has uncommitted changes. Then:

node tools/check-theme-tokens.mjs on everything. A failure stops the push.
pnpm exec oxlint on the collected files, if any.

frontend/docs/CI_AND_HOOKS.md says pre-push runs format:check, lint, type-check and check:core-api. The hook in the repo does not. Type-check and the core API boundary check run only in CI.

Commit messages

commitlint.config.cjs extends the conventional config:

Type is one of feat, fix, docs, refactor, perf, test, build, ci, chore, revert.
Subject is required, in lower case or sentence case.
Header at most 100 characters. Body lines over 120 characters produce a warning.

CI

.github/workflows/ci.yml runs on pull requests and on pushes to any branch except dev and main.

Step	Command
Core API boundary	`bash tools/check-no-direct-core-api.sh`
Install	`pnpm install --frozen-lockfile` on Node 24, with the pnpm store cached
Type-check	`pnpm type-check`
Lint	`pnpm lint`
Tests	`pnpm test`

The job sets placeholder values for DATABASE_URL and BETTER_AUTH_SECRET. No database is reached. format:check, check:theme and Playwright are not CI steps.

The first step looks certain to fail on the current tree. The boundary script allows CORE_API_URL only in modules/shared/lib/core-api.ts, and nine other files read it today. See Talking to the core API. This was read from the script and the code, not run.

Deploy workflows are described in Build and deploy.

Guard scripts in `tools/`

Script	Guards
`check-no-direct-core-api.sh`	The API URL and the service secret stay server side and in one place. No `NEXT_PUBLIC_CORE_API*`. No client component touches `core-api`
`check-theme-tokens.mjs`	No single theme colour on a themed surface

The workspace root (one level above frontend) has tools/ensure-core-api.sh, used by pnpm dev. With --start it launches the backend in the background, writes its log to a temp file and waits up to 60 seconds for the health endpoint. Without the flag it prints how to start the API and exits non zero.

Shared Tailwind config

tooling/tailwind is the package @repo/tailwind-config. It ships two CSS files and no JavaScript config. Tailwind 4 is configured in CSS.

File	Contents
`theme.css`	Tokens and the `@theme` mapping
`tailwind-animate.css`	The enter and exit animation utilities used by Radix components (`animate-in`, `fade-in-0`, `zoom-in-95`, `slide-in-from-*`)

apps/saas/postcss.config.cjs wires @tailwindcss/postcss.

Other configs

File	Purpose
`.editorconfig`	Editor defaults
`.vscode/`	Workspace settings
`apps/saas/next-env.d.ts`, `global.d.ts`, `intl.d.ts`	Ambient types. `intl.d.ts` types translation keys
`apps/saas/types.ts`	`SaasConfig`, the type of `config.ts`
`docker-compose.yml`	A leftover from the starter kit: Postgres and MinIO containers named `supastarter-*`. The web app needs neither
`dev.sh`	Runs the standalone server from a local build with `.env` loaded

Before you push

cd frontend
pnpm format
pnpm lint
pnpm type-check
pnpm test
pnpm check:theme

Warnings are acceptable. Errors are not.

​Workspace

​Root scripts

​App scripts

​Type checking

​Linting

​Formatting

​Git hooks

​lint-staged

​pre-push

​Commit messages

​CI

​Guard scripts in tools/

​Shared Tailwind config

​Other configs

​Before you push

Workspace

Root scripts

App scripts

Type checking

Linting

Formatting

Git hooks

lint-staged

pre-push

Commit messages

CI

Guard scripts in `tools/`

Shared Tailwind config

Other configs

Before you push