Blocks

Blocks are modular template building units that handle specific aspects of TypeScript project generation. Each block is created using base.createBlock() and can be combined to create custom project configurations.

Capabilities

Blocks Collection

Object containing all available blocks accessible by name for flexible project configuration.

/**
 * Collection of all available blocks for project generation
 * Each block handles a specific aspect of the TypeScript project setup
 */
const blocks: {
  // Core Development Blocks
  blockAllContributors: Block;
  blockCodecov: Block;
  blockContributingDocs: Block;
  blockContributorCovenant: Block;
  blockDevelopmentDocs: Block;
  blockFunding: Block;
  blockGitignore: Block;
  blockMain: Block;
  blockMITLicense: Block;
  blockPackageJson: Block;
  blockREADME: Block;
  blockSecurityDocs: Block;
  blockTemplatedWith: Block;

  // TypeScript and Build Blocks
  blockTypeScript: Block;
  blockTSDown: Block;
  blockNcc: Block;
  blockVitest: Block;

  // Linting and Code Quality Blocks
  blockESLint: Block;
  blockESLintComments: Block;
  blockESLintJSDoc: Block;
  blockESLintJSONC: Block;
  blockESLintMarkdown: Block;
  blockESLintMoreStyling: Block;
  blockESLintNode: Block;
  blockESLintPackageJson: Block;
  blockESLintPerfectionist: Block;
  blockESLintPlugin: Block;
  blockESLintRegexp: Block;
  blockESLintYML: Block;
  blockCSpell: Block;
  blockKnip: Block;
  blockMarkdownlint: Block;

  // Formatting Blocks
  blockPrettier: Block;
  blockPrettierPluginCurly: Block;
  blockPrettierPluginPackageJson: Block;
  blockPrettierPluginSh: Block;

  // GitHub Integration Blocks
  blockGitHubActionsCI: Block;
  blockGitHubIssueTemplates: Block;
  blockGitHubPRTemplate: Block;
  blockReleaseIt: Block;
  blockRenovate: Block;

  // Development Environment Blocks
  blockNvmrc: Block;
  blockVSCode: Block;
  blockPnpmDedupe: Block;

  // Specialized Blocks
  blockAreTheTypesWrong: Block;
  blockWebExt: Block;
  blockOctoGuide: Block;
  blockOctoGuideStrict: Block;
  blockCTATransitions: Block;
  blockRemoveDependencies: Block;
  blockRemoveFiles: Block;
};

Core Development Blocks

AllContributors

Configures the AllContributors system for recognizing and managing project contributors.

const blockAllContributors: Block;

Purpose: Sets up .all-contributorsrc configuration and README badge integration for contributor recognition.

Codecov Integration

Sets up Codecov integration for test coverage reporting and analysis.

const blockCodecov: Block;

Purpose: Configures codecov.yml and GitHub Actions integration for automated coverage reporting.

Contributing Documentation

Generates comprehensive contributing guidelines and development documentation.

const blockContributingDocs: Block;

Purpose: Creates CONTRIBUTING.md with project-specific contribution guidelines and setup instructions.

Contributor Covenant

Adds the Contributor Covenant code of conduct to establish community guidelines.

const blockContributorCovenant: Block;

Purpose: Creates CODE_OF_CONDUCT.md with standard community behavioral expectations.

Development Documentation

Creates detailed development documentation including setup and workflow instructions.

const blockDevelopmentDocs: Block;

Purpose: Generates development-focused documentation for contributors and maintainers.

GitHub Funding

Configures GitHub Sponsors funding configuration for project support.

const blockFunding: Block;

Purpose: Sets up .github/FUNDING.yml for donation and sponsorship integration.

Gitignore Configuration

Generates comprehensive .gitignore file with appropriate exclusions for TypeScript projects.

const blockGitignore: Block;

Purpose: Creates .gitignore with Node.js, TypeScript, IDE, and build artifact exclusions.

Main Entry Point

Sets up main entry point configuration for the package.

const blockMain: Block;

Purpose: Configures package.json main field and creates primary module entry points.

MIT License

Adds MIT license file with proper copyright information.

const blockMITLicense: Block;

Purpose: Creates LICENSE.md with MIT license text and project-specific details.

Package.json Configuration

Generates and configures comprehensive package.json with all necessary fields and dependencies.

const blockPackageJson: Block;

Purpose: Creates complete package.json with metadata, scripts, dependencies, and configuration.

README Generation

Creates comprehensive README.md file with project documentation and usage examples.

const blockREADME: Block;

Purpose: Generates detailed README with installation, usage, API docs, and contributor information.

Security Documentation

Adds security documentation and vulnerability reporting policies.

const blockSecurityDocs: Block;

Purpose: Creates SECURITY.md with security policy and vulnerability reporting procedures.

Template Attribution

Adds attribution indicating the project was created with Create TypeScript App.

const blockTemplatedWith: Block;

Purpose: Includes template attribution in documentation and configuration files.

TypeScript and Build Blocks

TypeScript Configuration

Core TypeScript configuration and build setup including tsconfig.json and compilation options.

const blockTypeScript: Block;

Purpose: Configures TypeScript compilation, type checking, and build processes.

TSDown Build System

Configures tsdown for optimized TypeScript builds and distribution.

const blockTSDown: Block;

Purpose: Sets up tsdown build tool for efficient TypeScript compilation and packaging.

NCC Compilation

Sets up ncc for Node.js CLI application compilation and bundling.

const blockNcc: Block;

Purpose: Configures ncc for creating standalone executable Node.js applications.

Vitest Testing

Configures Vitest testing framework with TypeScript integration and coverage reporting.

const blockVitest: Block;

Purpose: Sets up modern testing framework with TypeScript support and comprehensive configuration.

Linting and Code Quality Blocks

Core ESLint

Base ESLint configuration with TypeScript integration and essential rules.

const blockESLint: Block;

Purpose: Establishes foundational ESLint setup with TypeScript parser and basic rule sets.

ESLint Comments Plugin

ESLint plugin for managing ESLint directive comments and their usage.

const blockESLintComments: Block;

Purpose: Adds rules for proper ESLint comment usage and directive management.

JSDoc Linting

ESLint rules for JSDoc comment validation and consistency.

const blockESLintJSDoc: Block;

Purpose: Enforces JSDoc standards and documentation requirements in TypeScript code.

JSON/JSONC Linting

ESLint configuration for JSON and JSONC file validation and formatting.

const blockESLintJSONC: Block;

Purpose: Applies linting rules to JSON configuration files and data files.

Markdown Linting (ESLint)

ESLint plugin for Markdown file linting and code block validation.

const blockESLintMarkdown: Block;

Purpose: Lints code blocks within Markdown files and ensures consistency.

Additional Styling Rules

Extended ESLint styling rules for consistent code formatting and style.

const blockESLintMoreStyling: Block;

Purpose: Adds comprehensive styling rules beyond basic ESLint configuration.

Node.js ESLint Rules

Node.js-specific ESLint rules for server-side JavaScript and TypeScript development.

const blockESLintNode: Block;

Purpose: Applies Node.js best practices and API usage validation.

Package.json Linting

ESLint plugin for validating and formatting package.json files.

const blockESLintPackageJson: Block;

Purpose: Ensures package.json follows npm best practices and maintains consistency.

Perfectionist Plugin

Import/export sorting and organization rules for maintaining clean code structure.

const blockESLintPerfectionist: Block;

Purpose: Automatically sorts imports, exports, and object properties for consistency.

ESLint Plugin Configuration

Special configuration for projects that are themselves ESLint plugins.

const blockESLintPlugin: Block;

Purpose: Adds meta-configuration for developing ESLint plugins and rules.

Regular Expression Linting

ESLint rules for validating and improving regular expression usage and patterns.

const blockESLintRegexp: Block;

Purpose: Applies best practices for regex patterns and prevents common pitfalls.

YAML Linting

ESLint configuration for YAML file validation and formatting.

const blockESLintYML: Block;

Purpose: Lints YAML configuration files for syntax and style consistency.

CSpell Configuration

Spell checking configuration for code, comments, and documentation.

const blockCSpell: Block;

Purpose: Sets up comprehensive spell checking with technical dictionaries and custom words.

Knip Dead Code Detection

Configures Knip for detecting unused files, dependencies, and exports.

const blockKnip: Block;

Purpose: Identifies dead code and unused dependencies to maintain clean codebases.

Markdownlint

Dedicated Markdown linting with comprehensive style and formatting rules.

const blockMarkdownlint: Block;

Purpose: Ensures Markdown files follow consistent formatting and style guidelines.

Formatting Blocks

Core Prettier

Base Prettier configuration for code formatting across all supported file types.

const blockPrettier: Block;

Purpose: Establishes consistent code formatting standards for the entire project.

Prettier Curly Plugin

Prettier plugin for consistent curly brace formatting and style.

const blockPrettierPluginCurly: Block;

Purpose: Enforces consistent brace usage and formatting in JavaScript/TypeScript code.

Package.json Formatting

Prettier plugin specifically for formatting package.json files consistently.

const blockPrettierPluginPackageJson: Block;

Purpose: Maintains consistent formatting and field ordering in package.json files.

Shell Script Formatting

Prettier plugin for formatting shell scripts and bash files.

const blockPrettierPluginSh: Block;

Purpose: Applies consistent formatting to shell scripts and bash configuration files.

GitHub Integration Blocks

GitHub Actions CI/CD

Comprehensive GitHub Actions workflow configuration for continuous integration and deployment.

const blockGitHubActionsCI: Block;

Purpose: Sets up automated testing, building, and deployment workflows.

Issue Templates

GitHub issue template configuration for structured bug reports and feature requests.

const blockGitHubIssueTemplates: Block;

Purpose: Creates issue templates for consistent bug reporting and feature requests.

Pull Request Template

GitHub pull request template for consistent PR descriptions and checklists.

const blockGitHubPRTemplate: Block;

Purpose: Provides PR template with review checklist and description guidelines.

Release-It Configuration

Automated release management and version bumping with release-it.

const blockReleaseIt: Block;

Purpose: Configures automated versioning, changelog generation, and npm publishing.

Renovate Configuration

Renovate bot configuration for automated dependency updates and security patches.

const blockRenovate: Block;

Purpose: Sets up intelligent dependency update automation with merge strategies.

Development Environment Blocks

Node Version Manager

.nvmrc configuration for consistent Node.js version management across environments.

const blockNvmrc: Block;

Purpose: Pins Node.js version for consistent development environments.

Visual Studio Code

VS Code workspace configuration including settings, extensions, and debugging setup.

const blockVSCode: Block;

Purpose: Configures IDE settings, recommended extensions, and debugging configurations.

pnpm Deduplication

pnpm-specific configuration for dependency deduplication and optimization.

const blockPnpmDedupe: Block;

Purpose: Optimizes pnpm installations and reduces dependency duplication.

Specialized Blocks

Are The Types Wrong

Configures are-the-types-wrong for TypeScript package validation and compatibility checking.

const blockAreTheTypesWrong: Block;

Purpose: Validates TypeScript declaration files and package exports compatibility.

Web Extension Support

Specialized configuration for browser extension development projects.

const blockWebExt: Block;

Purpose: Adds web extension specific build tools and manifest configuration.

Octo Configuration Guide

Sets up Octo configuration guide for development workflow documentation.

const blockOctoGuide: Block;

Purpose: Provides comprehensive development workflow and contribution guidelines.

Strict Octo Configuration

Enhanced Octo configuration with stricter development and contribution guidelines.

const blockOctoGuideStrict: Block;

Purpose: Applies strict development practices and enhanced workflow requirements.

CTA Transitions

Create TypeScript App specific transition configurations and migration helpers.

const blockCTATransitions: Block;

Purpose: Handles template upgrades and configuration migrations for existing projects.

Dependency Removal

Utility block for removing specified dependencies from the generated project.

const blockRemoveDependencies: Block;

Purpose: Removes unwanted dependencies during template customization.

File Removal

Utility block for removing specified files from the generated project structure.

const blockRemoveFiles: Block;

Purpose: Removes unnecessary files during template customization and cleanup.

Usage Examples

import { blocks, createConfig } from "create-typescript-app";

// Use specific blocks
const { blockTypeScript, blockESLint, blockVitest } = blocks;

// Create custom configuration with selected blocks
const customConfig = createConfig({
  directory: "./custom-project",
  title: "Custom TypeScript Project",
  repository: "custom-project", 
  owner: "username",
  // Individual blocks can be configured through presets or custom selection
});