Skip to main content

Getting Started

Installationโ€‹

npx @rtorcato/repo-tooling setup

What it looks likeโ€‹

Terminal
$ 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:

PromptOptions
Primary languagejs (default), swift, python, perl โ€” defaults to whatever the directory looks like
Project namedefaults to directory name
Project typelibrary, web-app, node-api, nextjs-app, react-app
TypeScript?yes/no
TS config variantbase, react, next, node, express (context-filtered)
Linting/formatting toolbiome (recommended), eslint, both, none
ESLint config (if ESLint)base or nextjs
Oxlint alongside? (if linting)yes/no
Testing frameworkvitest (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.

Non-JS languages

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, and engines.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 preset
  • biome.json / eslint.config.js + prettier.config.js โ€” based on linting choice
  • vitest.config.js / jest.config.js โ€” testing config
  • .husky/pre-commit, commitlint.config.js โ€” if git hooks chosen
  • release.config.js โ€” if semantic release chosen
  • .github/workflows/ci.yml โ€” CI workflow
  • .github/dependabot.yml, .github/workflows/codeql.yml โ€” if security automation chosen
  • README.md โ€” project README scaffold
  • reset.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