Getting Started
Installationโ
- npx
- pnpm dlx
- global
npx @rtorcato/repo-tooling setup
pnpm dlx @rtorcato/repo-tooling setup
npm install -g @rtorcato/repo-tooling
repo-tooling setup
What it looks likeโ
$ npx @rtorcato/repo-tooling setup
๐ ๏ธ Welcome to repo-tooling setup!
Setting up tooling in: /home/user/acme-lib
โ ๐ฃ๏ธ What is the primary language of this repo? JavaScript/TypeScript
โ ๐ฆ What is your project name? acme-lib
โ ๐๏ธ What type of project are you building? ๐ Library/Package
โ ๐ Do you want to use TypeScript? Yes
โ โ๏ธ Which TypeScript configuration? ๐ง Base (General purpose)
โ ๐ Which linting/formatting tool? โก Biome (Fast, all-in-one)
โ ๐ฆ Also run Oxlint alongside (50โ100ร faster than ESLint)? No
โ ๐งช Which testing framework? โก Vitest (Fast, Vite-powered)
โ ๐ช Set up Git hooks (Husky + lint-staged)? Yes
โ ๐ Set up conventional commit linting? Yes
โ ๐ Automated release tool? ๐ฆ semantic-release (commit-message-driven)
โ ๐ณ Add a tree-shake verification check (apps/treeshake-check)? No
โ ๐ฆ Add publint to lint your package before publishing? Yes
โ ๐ Add status badges (CI, npm, coverage, license) to the README? Yes
โ ๐ก๏ธ Include security automation (Dependabot + CodeQL)? Yes
โ ๐ค Add AI agent rules (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill)? Yes
โ ๐ฆ Which bundler/build tool? ๐ฆ tsup (TypeScript packages)
โ ๐ฅ Target the Bun runtime (bunfig.toml + Bun-typed tsconfig)? No
๐ Generating configuration files...
๐ฆ Installing dependencies...
โ
Dependencies installed successfully!
โจ Formatted generated files
โ
Setup completed successfully!
๐ Next Steps:
1. ๐ง Customize your tsconfig.json as needed
2. ๐ Run linting with: pnpm biome check .
3. ๐งช Run tests with: pnpm vitest
4. ๐ช Commit your changes to test the git hooks
5. ๐ .repo-tooling.json records your setup choices โ doctor uses it to suppress intentional opt-outs
6. ๐ Check the generated README.md for more details
๐ฆ Publish to npm (OIDC trusted publishing โ no NPM_TOKEN):
...
Setup wizardโ
Running setup (or its alias init) launches an interactive wizard:
| Prompt | Options |
|---|---|
| Primary language | js (default), swift, python, perl โ defaults to whatever the directory looks like |
| Project name | defaults to directory name |
| Project type | library, web-app, node-api, nextjs-app, react-app |
| TypeScript? | yes/no |
| TS config variant | base, react, next, node, express (context-filtered) |
| Linting/formatting tool | biome (recommended), eslint, both, none |
| ESLint config (if ESLint) | base or nextjs |
| Oxlint alongside? (if linting) | yes/no |
| Testing framework | vitest (recommended), jest, playwright, cypress, none |
| Test environment (if Jest) | node, browser, both |
| Git hooks (Husky + lint-staged)? | yes/no |
| Conventional commit linting? | yes/no (if git hooks enabled) |
| Release tool (library projects only) | semantic-release, changesets, release-please, none |
| Tree-shake check? (library projects only) | yes/no |
| publint? (library projects only) | yes/no |
| README status badges? | yes/no |
| Security automation (Dependabot + CodeQL)? | yes/no |
| AI agent rules (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill)? | yes/no |
| Monorepo task orchestrator (if a pnpm workspace) | turbo, nx, none |
| Tailwind CSS v4? (web apps) | yes/no |
| Bundler (not Next.js) | tsup, esbuild, rollup, rolldown, vite (web apps), none |
| Bun runtime? (library and Node API) | yes/no |
A universal baseline (.editorconfig, .nvmrc, engines.node, knip.json, .vscode/extensions.json) is scaffolded automatically โ no prompt โ because these are safe defaults for every project.
The table above is the JavaScript/TypeScript question list. Picking Swift asks only for a package name and then scaffolds a SwiftPM library โ SwiftLint, Periphery and swift test are the standard rather than options. See the Swift guide.
Python and Perl write nothing and point you at doctor. For Python that's now a full audit โ Ruff, mypy, pytest, .gitignore, CI and git hooks on top of the language-agnostic checks, all fixable with fix; only the setup preset is still missing. See the Python reference. Perl gets the language-agnostic checks (CI, CodeQL, Dependabot, GitHub repo settings) until its module lands โ see #139.
Non-interactive setup (CI / scripts)โ
Skip the prompts entirely by scaffolding from a named preset:
npx @rtorcato/repo-tooling setup --preset library -d ./acme-lib --skip-install --yes
# The same, without the AI agent files (AGENTS.md, CLAUDE.md, .claude/, .cursor/, Copilot, .mcp.json.example)
npx @rtorcato/repo-tooling setup --preset library -d ./acme-lib --skip-install --yes --no-ai-setup
Presets: minimal, library, web-app, node-api, nextjs-app, react-app, swift-library, vite-plus, vite-plus-app.
minimal is tsconfig + Biome + Vitest and nothing else โ no git hooks, no commitlint, no release pipeline, no Dependabot/CodeQL, no AI agent files.
When stdin and stdout are both a terminal, --preset first prints every file it would write and lets you uncheck the parts you don't want. Piped or redirected โ CI โ it writes everything in one shot. --yes forces the one-shot path in a terminal too.
swift-library scaffolds a SwiftPM package instead of an npm one โ no package.json, no install step. See the Swift guide for the full file list.
vite-plus and vite-plus-app are opt-in: they use Vite+ (vp check, vp test, vp pack / vp build) in place of Biome, tsup and a separate Vitest.
For full control, drive setup from a ProjectConfig JSON file โ print the schema, write a config, preview, then scaffold:
npx @rtorcato/repo-tooling setup --config-schema > project-config.schema.json
npx @rtorcato/repo-tooling setup --config project.json --dry-run # preview file list
npx @rtorcato/repo-tooling setup --config project.json -d ./acme-lib --skip-install
Files generatedโ
package.jsonโ merged with chosen devDependencies, scripts, andengines.node.editorconfig,.nvmrc,knip.jsonโ universal baseline.vscode/extensions.jsonโ recommends the editor extensions matching your enabled tools (merge-friendly)tsconfig.jsonโ extends the matching presetbiome.json/eslint.config.js+prettier.config.jsโ based on linting choicevitest.config.js/jest.config.jsโ testing config.husky/pre-commit,commitlint.config.jsโ if git hooks chosenrelease.config.jsโ if semantic release chosen.github/workflows/ci.ymlโ CI workflow.github/dependabot.yml,.github/workflows/codeql.ymlโ if security automation chosenREADME.mdโ project README scaffoldreset.d.tsโ ts-reset type augmentation (if TypeScript)
For a Swift package the list is entirely different (Package.swift, Sources/, Tests/, .swiftlint.yml, โฆ) โ see the Swift guide.
Existing projects: doctor + fixโ
For repos that already exist, don't rerun setup (it's a fresh-project wizard and would clobber your configs). Use doctor to find drift, then fix to apply scaffolders incrementally:
npx @rtorcato/repo-tooling doctor # see what's missing or drifted
npx @rtorcato/repo-tooling fix # walk every finding, prompting per item
npx @rtorcato/repo-tooling fix dependabot # or apply just one
fix defaults to No when overwriting existing files โ your customisations are preserved unless you explicitly opt in (or pass --yes). See CLI reference for full details.
Using specific configs without the wizardโ
If you only need one config file, use copy:
npx @rtorcato/repo-tooling copy biome # โ biome.json
npx @rtorcato/repo-tooling copy tsconfig # โ tsconfig.json
npx @rtorcato/repo-tooling copy changesets # โ .changeset/config.json
npx @rtorcato/repo-tooling copy oxlint # โ .oxlintrc.json
npx @rtorcato/repo-tooling copy claude-skill # โ .claude/skills/repo-tooling/SKILL.md
copy drops the raw preset as-is. For configs you might later customise (biome, tsconfig, vitest, โฆ) prefer fix <target> โ it won't clobber an existing file without --yes, and doctor verifies it afterwards.
Or import configs directly in your own files:
import '@rtorcato/repo-tooling/typescript/base'
CI/CD secretsโ
The scaffolded release.yml publishes to npm with OIDC trusted publishing, so it needs no NPM_TOKEN. Register the workflow on npm with fix npm-trusted-publisher, and gate it with fix release-environment. See Moving an existing repo to release.yml.
On a Changesets repo, a merge never publishes. For how a change gets from its PR to npm, see Releasing.
GITHUB_TOKEN is provided by GitHub Actions. If you add a RELEASE_TOKEN (an admin PAT that lets semantic-release push past branch protection), store it as a secret on the release environment, not as a repository secret. doctor's Release secrets check flags it at repo level.
Settings โ Environments โ release โ Environment secrets