Tooling.md

Tooling

create-typescript-app provides over two dozen pieces of tooling, ranging from code building and formatting to various forms of GitHub repository management. Most can be individually turned off or on.

The create-typescript-app setup scripts -creation, initialization, and migration- will prompt you to choose a "base" template level to initialize from. Those template levels provide common presets of which tooling pieces to enable.

◆  How much tooling would you like the template to set up for you?
│  ○ minimal     Just the bare starter tooling most repositories should ideally include.
│  ○ common      Important additions to the minimal starters such as releases and tests.
│  ○ everything  The most thorough tooling imaginable: sorting, spellchecking, and more!
│  ○ prompt      (allow me to customize)
└

This table summarizes each tooling piece and which base levels they're included in:

Tooling Piece	Exclusion Flag	Minimal	Common	Everything
Building		✔️	✅	💯
Compliance	--exclude-compliance			💯
Contributors	--exclude-contributors		✅	💯
Formatting		✔️	✅	💯
Lint ESLint	--exclude-lint-eslint			💯
Lint JSDoc	--exclude-lint-jsdoc			💯
Lint JSON	--exclude-lint-json			💯
Lint Knip	--exclude-lint-knip		✅	💯
Lint MD	--exclude-lint-md			💯
Lint Package JSON	--exclude-lint-package-json			💯
Lint Packages	--exclude-lint-packages			💯
Lint Perfectionist	--exclude-lint-perfectionist			💯
Lint Regex	--exclude-lint-regex			💯
Lint Spelling	--exclude-lint-spelling			💯
Lint Strict	--exclude-lint-strict			💯
Lint Stylistic	--exclude-lint-stylistic			💯
Lint YML	--exclude-lint-yml			💯
Linting		✔️	✅	💯
Package Management		✔️	✅	💯
Releases	--exclude-releases		✅	💯
Renovate	--exclude-renovate		✅	💯
Repository Templates		✔️	✅	💯
Testing	--exclude-tests		✅	💯
Type Checking		✔️	✅	💯

See also Options for how to customize the way template is run.

"Minimal" Base Level

These tooling pieces are the ones that most repositories should generally always have enabled. Other pieces of tooling are likely to not work as well (or at all) if these are removed.

The "minimal" base is best suited for projects that are very small and not likely to change very frequently. However, they'll be missing out on many of the great tooling pieces enabled in more comprehensive bases. We strongly recommend using at least the "common" base level instead for most repositories.

• Building
• Formatting
• Linting
• Package Management
• Repository Templates
• Type Checking

Building

tsup: Builds output definitions and JavaScript files using esbuild. Each *.ts source file within src/ is built into .d.ts, .js, and .js.map output files in lib/.

Building once:

pnpm run build

Building in watch mode:

pnpm run build --watch

Formatting

Prettier: Formats code for developers and enforces a consistent formatting style. It's run on file save per VS Code settings and as a Git commit hook via husky and lint-staged. prettier-plugin-curly, prettier-plugin-sh, and prettier-plugin-packagejson add in more formatting as well.

Auto-formatting all files:

pnpm run format --write

Linting

ESLint: Static analysis for JavaScript code that detects likely logical issues and helps enforce consistent code style. Uses typescript-eslint to understand TypeScript syntax and include TypeScript-specific rules.

Linting all files:

pnpm run lint

Linting all files, auto-fixing fixable rule reports:

pnpm run lint --fix

Package Management

pnpm: Disk-efficient package manager alternative to npm. It caches packages in a computer-wide registry and symlinks installed packages within that registry.

Installing packages:

pnpm run install

Repository Templates

In code, assorted repository documentation files for GitHub are created:

• Code of conduct
• Contributing guide
• Issue and PR templates
• Security policy

GitHub Actions workflows are added for each of the enabled tooling pieces to run them in CI.

On the GitHub repository, metadata will be populated:

• Issue labels for issue areas, statuses, and types.
• Repository settings such as branch protections and squash merging PRs

Type Checking

TypeScript: A typed superset of JavaScript that ensures runtime behavior matches the code's intent. Configured with strict compiler options, including noImplicitAny and strict.

Type checking once:

pnpm run tsc

Type checking in watch mode:

pnpm run tsc --watch

"Common" Base Level

These added tooling pieces are those that aren't quite essential for a repository, but are still very commonly useful. This is recommended for most users of create-typescript-app to start with.

• Contributors
• Lint Knip
• Releases
• Renovate
• Testing

Contributors

All Contributors: Tracks various kinds of contributions and displays them in a nicely formatted table in the README.md. Contributions will be auto-detected when possible using all-contributors-auto-action.

Lint Knip

Knip: Detects unused files, dependencies, and code exports.

Running Knip:

pnpm run lint:knip

Releases

release-it: Generates changelogs, bumps the package version, and publishes to GitHub and npm based on conventional commits.

Renovate

Renovate: Keeps dependencies up-to-date with PRs, configured to wait a week after each update for safety.

Testing

Vitest: Fast unit tests, configured with coverage tracking.

Additionally:

• @vitest/eslint-plugin will be added to the ESLint config to lint for Vitest-specific issues
• console-fail-test will also be added to ensure tests don't accidentally log to the console.

Running tests in watch mode:

pnpm run test

Running tests in watch mode and auto-updating Vitest snapshots:

pnpm run test -u

Running tests once with coverage tracking:

pnpm run test run --coverage

"Everything" Base Level

This level is for developers who are eager to get the maximum tooling benefits in a repository. Using the "everything" level will gain you comprehensive, strict coverage of all sorts of repository issues, including auto-sorting of properties and strict ESLint configs.

• Compliance
• Lint ESLint
• Lint JSDoc
• Lint JSON
• Lint MD
• Lint Package JSON
• Lint Packages
• Lint Perfectionist
• Lint Regex
• Lint Spelling
• Lint Strict
• Lint Stylistic
• Lint YML

Compliance

PR Compliance Action: Checks PRs for compliance such as addressing a linked issue and proper title formatting.

Lint ESLint

@eslint-community/eslint-plugin-eslint-comments: Enforces proper usage of ESLint configuration comments.

Lint JSDoc

eslint-plugin-jsdoc: Enforces good practices around JSDoc comments.

Lint JSON

eslint-plugin-jsonc: Adds linting for .json and .jsonc files.

Lint MD

Markdownlint: Linting for Markdown code.

pnpm lint:md

This is a separate linter from ESLint, but will likely eventually be switched to an ESLint plugin (#567).

Lint Package JSON

eslint-plugin-package-json: Linting for package.json files.

Lint Packages

Uses pnpm dedupe to deduplicate package dependencies.

pnpm lint:packages

This is grouped with "Lint" tooling pieces, but will likely eventually be renamed (#896).

Lint Perfectionist

eslint-plugin-perfectionist: Lints for sorting properties, imports, etc. This plugin is quite particular -perfectionist, even- but all its rules include auto-fixers that can correct complaints for you.

Lint Regex

eslint-plugin-regex: Detects issues with JavaScript regular expressions, such as potential exponential complexity.

Lint Spelling

CSpell: Spell checking for code. Helps detect typos based on a configurable user dictionary (cspell.json).

pnpm lint:spelling

This is a separate linter from ESLint, but will likely eventually be switched to an ESLint plugin (#897).

Lint Strict

Enables typescript-eslint's strict configs for increased scrutiny around code logic.

Lint Stylistic

Enables typescript-eslint's stylistic configs for increased scrutiny around consistent code style.

Lint YML

eslint-plugin-yml: Adds linting for yaml and .yml files, such as sorting keys.