Getting Started

Installation

npx

npx @rtorcato/repo-tooling setup

pnpm dlx

pnpm --package=@rtorcato/repo-tooling dlx setup

global

npm install -g @rtorcato/repo-tooling
repo-tooling setup

What it looks like

Terminal

$ npx @rtorcato/repo-tooling setup

🛠️  Welcome to JS Tooling Setup!

Setting up tooling in: /home/user/my-lib

? 🗣️  What is the primary language of this repo? JavaScript/TypeScript
? 📦 What is your project name? my-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)
? 🧪 Which testing framework? ⚡ Vitest (Fast, Vite-powered)
? 🪝 Set up Git hooks (Husky + lint-staged)? Yes
? 📝 Set up conventional commit linting? Yes
? 🚀 Set up semantic release for automated versioning? Yes
? 🛡️  Include security automation (Dependabot + CodeQL)? Yes
? 📦 Which bundler/build tool? 📦 tsup (TypeScript packages)

📝 Generating configuration 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. 📖 Check the generated README.md for more details

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
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)
Semantic release?	yes/no (library projects only)
Security automation (Dependabot + CodeQL)?	yes/no
Bundler	tsup, esbuild, vite (web apps), none

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 ./my-lib --skip-install

Presets: library, web-app, node-api, nextjs-app, react-app, swift-library.

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.

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 ./my-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
• codecov.yml — if Vitest chosen; CI runs pnpm coverage and uploads to Codecov
• .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.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

For automated publishing via Semantic Release, add these to your GitHub repository secrets:

1. NPM_TOKEN — npm authentication token
2. GITHUB_TOKEN — automatically provided by GitHub Actions

Settings → Secrets and variables → Actions