create-typescript-app

The create-typescript-app CLI provides different presets to balance tooling complexity with project needs:

• Minimal: Provides the barest starting template with only essential tooling for building, formatting, linting, and releasing a small TypeScript package.
• Common: Includes minimal tooling plus common repository management automation, such as contributor recognition, release management, and testing.
• Everything: Includes the full suite of latest safety checks and standardization tools (this is the preset used by the repository itself).

You can customize which preset is used via the CLI.

create-typescript-app uses a modular system called "Blocks" to provide various tooling pieces, such as code building, formatting, and GitHub repository management.

Each block can be individually enabled or disabled using specific CLI flags during the project creation process. You can use --add-<block-name> to include a feature or --exclude-<block-name> to remove it.

Blocks are also organized into "Base Levels" (Minimal, Common, and Everything), which determine which features are included by default in different configuration profiles.

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

The project automatically generates several GitHub documentation files:

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

It also adds GitHub Actions workflows for all enabled tooling to run in CI. On the GitHub repository, it populates metadata including Issue labels (for areas, statuses, and types) and Repository settings (such as branch rulesets and squash merging PRs).

The refinements key is used to customize the tooling provided by the selected Preset. You can modify the behavior of the template through addons and blocks.

addons

Use addons to provide additional configuration to existing Blocks. For example, you can add specific words to the blockCSpell addon list.

blocks

You can manipulate the set of Blocks provided by a Preset using two sub-keys:

• add: An array of Blocks to include in addition to the Preset's defaults.
• exclude: An array of Blocks to remove from the Preset's defaults.

See Blocks.md for a full list of available blocks and their corresponding CLI flags.

create-typescript-app is a solution for setting up new or existing repositories with comprehensive TypeScript tooling, including building, testing, automated release management, contributor recognition, and GitHub repository settings.

Prerequisites

Ensure you have the following installed:

• Node.js
• pnpm
• GitHub CLI (optional, but recommended; you must be logged in)

Installation and Execution

To initialize the setup in your current directory or an existing repository, run:

npx create-typescript-app

Static analysis is performed by ESLint using typescript-eslint to support TypeScript syntax and specific rules. This helps detect logical issues and enforce code style.

Commands:

• pnpm lint: Lint all files.
• pnpm lint --fix: Lint all files and automatically fix fixable rule reports.

Use the --remote flag to automatically create a repository on GitHub. This can be used when creating a brand new project or when transitioning an existing local Git repository to GitHub. If an origin remote already exists, create-typescript-app will synchronize the local repository with it, including pushing commits, setting labels, and updating repository settings.

npx create-typescript-app --remote

Part of the 'Everything' base level, this command uses pnpm dedupe to clean up and deduplicate package dependencies.

pnpm lint:packages

Knip is used to detect unused files, dependencies, and code exports within the repository.

pnpm lint:knip

The project uses pnpm as a disk-efficient package manager. It uses a content-addressable storage system to cache packages and symlinks them into your project.

pnpm install

Testing is powered by Vitest, configured with coverage tracking. The setup includes @vitest/eslint-plugin for linting Vitest-specific issues and console-fail-test to prevent accidental console logging during tests.

Commands:

• pnpm test: Run tests in watch mode.
• pnpm test -u: Run tests in watch mode and auto-update Vitest snapshots.
• pnpm test run --coverage: Run tests once with coverage tracking.

To start the interactive setup process for a new TypeScript application, use the following command. By default, this creates a local Git repository only and does not perform any network requests to GitHub.

npx create-typescript-app