Blocks.md

Blocks

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

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

Block	Flags	Minimal	Common	Everything
AllContributors	--add-allcontributors, --exclude-allcontributors		✅	💯
Are The Types Wrong	--add-are-the-types-wrong, --exclude-are-the-types-wrong
Contributing Docs	--add-contributing-docs, --exclude-contributing-docs	✔️	✅	💯
Contributor Covenant	--add-contributor-covenant, --exclude-contributor-covenant	✔️	✅	💯
CSpell	--add-cspell, --exclude-cspell			💯
Codecov	--add-codecov, --exclude-codecov		✅	💯
Development Docs	--add-development-docs, --exclude-development-docs	✔️	✅	💯
ESLint	--add-eslint, --exclude-eslint	✔️	✅	💯
ESLint Comments Plugin	--add-eslint-comments-plugin, --exclude-eslint-comments-plugin			💯
ESLint JSDoc Plugin	--add-eslint-jsdoc-plugin, --exclude-eslint-jsdoc-plugin			💯
ESLint JSONC Plugin	--add-eslint-jsonc-plugin, --exclude-eslint-jsonc-plugin			💯
ESLint Markdown Plugin	--add-eslint-markdown-plugin, --exclude-eslint-markdown-plugin			💯
ESLint More Styling	--add-eslint-more-styling, --exclude-eslint-more-styling			💯
ESLint Node Plugin	--add-eslint-node-plugin, --exclude-eslint-node-plugin			💯
ESLint package.json Plugin	--add-eslint-package-json-plugin, --exclude-eslint-package-json-plugin			💯
ESLint Perfectionist Plugin	--add-eslint-perfectionist-plugin, --exclude-eslint-perfectionist-plugin			💯
ESLint Plugin	--add-eslint-plugin, --exclude-eslint-plugin
ESLint Regexp Plugin	--add-eslint-regexp-plugin, --exclude-eslint-regexp-plugin			💯
ESLint YML Plugin	--add-eslint-yml-plugin, --exclude-eslint-yml-plugin			💯
Funding	--add-funding, --exclude-funding		✅	💯
GitHub Actions CI	--add-github-actions-ci, --exclude-github-actions-ci	✔️	✅	💯
GitHub Issue Templates	--add-github-issue-templates, --exclude-github-issue-templates	✔️	✅	💯
GitHub PR Template	--add-github-pr-template, --exclude-github-pr-template	✔️	✅	💯
Gitignore	--add-gitignore, --exclude-gitignore	✔️	✅	💯
Knip	--add-knip, --exclude-knip			💯
Main	--add-main, --exclude-main	✔️	✅	💯
MIT License	--add-mit-license, --exclude-mit-license	✔️	✅	💯
ncc	--add-ncc, --exclude-ncc
nvmrc	--add-nvmrc, --exclude-nvmrc			💯
OctoGuide	--add-octoguide, --exclude-octoguide		✅	💯
OctoGuide Strict	--add-octoguide-strict, --exclude-octoguide-strict			💯
Package JSON	--add-package-json, --exclude-package-json	✔️	✅	💯
pnpm Dedupe	--add-pnpm-dedupe, --exclude-pnpm-dedupe			💯
Prettier	--add-prettier, --exclude-prettier	✔️	✅	💯
Prettier Plugin Curly	--add-prettier-plugin-curly, --exclude-prettier-plugin-curly			💯
Prettier Plugin Package JSON	--add-prettier-plugin-package-json, --exclude-prettier-plugin-package-json			💯
Prettier Plugin Sentences Per Line	--add-prettier-plugin-sentences-per-line, --exclude-prettier-plugin-sentences-per-line			💯
Prettier Plugin Sh	--add-prettier-plugin-sh, --exclude-prettier-plugin-sh			💯
README.md	--add-readme-md, --exclude-readme-md	✔️	✅	💯
release-it	--add-release-it, --exclude-release-it		✅	💯
Renovate	--add-renovate, --exclude-renovate			💯
Security Docs	--add-security-docs, --exclude-security-docs	✔️	✅	💯
Templated With	--add-templated-with, --exclude-templated-with	✔️	✅	💯
TSDown	--add-tsdown, --exclude-tsdown	✔️	✅	💯
TypeScript	--add-typescript, --exclude-typescript	✔️	✅	💯
Vitest	--add-vitest, --exclude-vitest		✅	💯
VS Code	--add-vs-code, --exclude-vs-code			💯
Web-ext	--add-web-ext, --exclude-web-ext

For example, this uses ncc instead of the default tsdown builder:

npx create-typescript-app --add-ncc --exclude-tsdown

See also CLI for customizing templated repositories when running npx create-typescript-app.

"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

tsdown: Builds output definitions and JavaScript files. Each *.ts source file within src/ is built into .d.ts and .js 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. Additional formatting can be provided by the following plugins:

• prettier-plugin-curly
• prettier-plugin-sentences-per-line
• prettier-plugin-sh
• prettier-plugin-packagejson

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 rulesets 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
• OctoGuide
• 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

OctoGuide

OctoGuide: checks that contributor activity on your GitHub repository aligns with common expectations of smoothly-running projects. It will automatically post friendly comments when contributors take actions you don’t want them to.

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.

• Lint ESLint
• Lint JSDoc
• Lint JSON
• Lint Package JSON
• Lint Packages
• Lint Perfectionist
• Lint Regexp
• Lint Spelling
• Lint Strict
• Lint Stylistic
• Lint YML
• OctoGuide Strict

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 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 Regexp

eslint-plugin-regexp: 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 .yaml files, such as sorting keys.

OctoGuide Strict

OctoGuide's Strict Config: additionally enforces enforcing semantic pull request conventions.