TypeScript Bootstrap Template

A modern TypeScript project template with ESM, testing, linting, and quality tools built-in.

• TypeScript Bootstrap Template
  • Quick Start
    • Bootstrap Options
  • What's Included
  • Common Commands
    • Using npm
    • Using mise tasks (Recommended)
  • Requirements
  • Setup Development Environment
  • Project Structure
  • Building
  • Testing
  • Code Quality
    • Pre-commit Hooks
  • Configuration
  • Using as a Library
  • CI/CD Pipeline
  • License
  • Support

Quick Start

Bootstrap a new project:

npx --yes --package=github:templ-project/typescript bootstrap ./my-project
cd my-project
npm install
npm test

That's it! You now have a fully configured TypeScript project.

MCP Search Providers

The web_search MCP tool supports multiple providers via the optional provider argument:

• duckduckgo (default)
• google (Google Custom Search JSON API)
• bing (Bing Web Search API)
• brave (Brave Search API)

Tool input

{
  "query": "model context protocol",
  "provider": "google",
  "limit": 5
}

Required environment variables

• GOOGLE_API_KEY and GOOGLE_CSE_ID for provider=google
• BING_API_KEY for provider=bing
• BRAVE_API_KEY for provider=brave

Optional:

• BING_API_ENDPOINT (override default Bing endpoint)

You can copy .env.example and fill in your provider keys.

Bootstrap Options

# Bootstrap with only ESM and CJS builds (no browser builds)
npx --yes --package=github:templ-project/typescript bootstrap --target esm,cjs ./my-project

# Bootstrap as part of a monorepo (removes .husky, .github)
npx --yes --package=github:templ-project/typescript bootstrap --part-of-monorepo ./packages/my-lib

# Show all available options
npx --yes --package=github:templ-project/typescript bootstrap --help

See .npx-install/README.md for detailed bootstrap documentation.

What's Included

| Feature | Tool | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------- | | Language | TypeScript 5.9 | Type-safe JavaScript | | Runtime | Node.js 22+ | Modern JavaScript runtime | | Execution | tsx | TypeScript execution without build | | Module System | ESM | Native ES Modules | | Build System | tsc + esbuild | Type-check + fast bundling | | Test Framework | Vitest | Fast unit testing with V8 coverage | | Linting | ESLint | Code quality with TypeScript rules | | Formatting | Prettier | Consistent code formatting | | Documentation | MkDocs + Material for MkDocs | Project documentation site | | Task Runner | mise tasks | Modern build automation | | Tool Management | mise | Isolated development environment | | Pre-commit Hooks | Husky + lint-staged | Automatic validation | | Duplicate Detection | jscpd | Copy-paste detector | | CI/CD | GitHub Actions | Multi-platform testing & releases |

Common Commands

Using npm

npm start              # Run the app (via tsx)
npm test               # Run tests
npm run test:coverage  # Run tests with coverage
npm run lint           # Lint and auto-fix
npm run format         # Format code with Prettier
npm run build          # Build for production
npm run docs           # Build MkDocs site (strict)
npm run validate       # Run all quality checks

Using mise tasks (Recommended)

# === Development ===
mise run run              # Run the application (via node)
mise run format            # Format all code (Prettier)
mise run format:check      # Check formatting without fixing
mise run lint              # Lint all code (ESLint + TypeScript)
mise run lint:check        # Check all without fixing
mise run duplicate-check   # Check for duplicate code
mise run docs              # Build MkDocs site (strict)
mise run docs:serve        # Serve documentation locally
mise run deps:sync         # Install all dependencies (mise, npm)
mise run deps:refresh      # Update all dependencies
mise run deps:clean        # Remove all dependencies

Requirements

• mise - Tool version management (installs everything else)

Automatically installed via mise:

• Node.js 22+
• Python 3.11+ (for helper scripts)
• ShellCheck (shell script linting)
• PowerShell Core (cross-platform PowerShell)

Setup Development Environment

# Install mise (if not already installed)
# Linux/macOS:
curl https://mise.run | sh

# Windows (PowerShell):
winget install jdx.mise
# or: choco install mise

# Install project tools and node modules


# Clone and setup
git clone https://github.com/templ-project/typescript.git my-project
cd my-project

# Install all dependencies
mise run deps:sync

# Verify setup
mise run validate

Project Structure

├── .github/
│   └── workflows/        # CI/CD pipelines
├── .husky/               # Git hooks
├── .scripts/             # Build/lint helper scripts

├── src/
│   ├── index.ts          # Main entry point
│   └── lib/
│       ├── greeter.ts    # Example module with TypeScript types
│       └── greeter.spec.ts # Unit tests (co-located)
├── dist/                 # Build output (gitignored)
├── docs/                 # MkDocs source pages
├── mise.toml             # Configuration and tasks
├── .mise.toml            # Tool versions & hooks
├── package.json          # Node.js dependencies
├── tsconfig.json         # TypeScript configuration
├── vitest.config.ts      # Test configuration
├── eslint.config.mjs     # ESLint configuration
├── prettier.config.mjs   # Prettier configuration
└── mkdocs.yml            # MkDocs configuration

Building

The template uses a two-step build process:

1. tsc - Type-checks and emits declaration files (.d.ts)
2. esbuild - Bundles for multiple targets

npm run build
# or: npm run build

Outputs:

• dist/index.js - Node.js ESM build artifact
• dist/index.d.ts - TypeScript declaration file

Testing

Tests are co-located with source files using the .spec.ts suffix:

// src/lib/greeter.spec.ts
import { describe, it, expect } from "vitest";
import { hello } from "./greeter";

describe("hello", () => {
  it("returns greeting", () => {
    expect(hello("World")).toBe("Hello, World!");
  });
});

Run tests:

npm run test                # Run all tests
npm run test:coverage       # Run with coverage report

Code Quality

Pre-commit Hooks

Every commit is validated with:

• Code formatting (Prettier)
• Linting (ESLint)
• Type checking (TypeScript)
• Unit tests (Vitest)

CI runs additional checks:

• Test coverage
• Duplicate code detection
• License compliance

Configure hooks in:

• .husky/pre-commit - Hook script
• .lintstagedrc.yml - File patterns and commands

Configuration

All configuration uses shared packages for consistency:

| File | Purpose | | --------------------- | ----------------------------------------------------- | | .mise.toml | Tool versions (Node, Python, ShellCheck) | | mise.toml | Configuration and tasks | | tsconfig.json | TypeScript config (extends @templ-project/tsconfig) | | eslint.config.mjs | ESLint config (uses @templ-project/eslint) | | prettier.config.mjs | Prettier config (uses @templ-project/prettier) | | vitest.config.ts | Vitest test configuration | | mkdocs.yml | MkDocs site navigation and theme settings | | .jscpd.json | Duplicate detection settings | | .licensee.json | License compliance settings |

Using as a Library

// ES Modules (recommended)
import { hello, Greeter } from "@templ-project/typescript-template";

const greeting = hello("World");
console.log(greeting); // "Hello, World!"

// ESM from built output
import { hello } from "./dist/index.js";

CI/CD Pipeline

The GitHub Actions pipeline runs on Linux, macOS, and Windows:

| Workflow | Trigger | Jobs | | ---------------- | ----------------------- | ---------------------------------- | | ci.yml | Push/PR to main/develop | Matrix orchestrator | | ci.quality.yml | Called by ci.yml | lint, test, build, duplicate-check | | ci.version.yml | Push to main | Semantic version bump | | ci.release.yml | After version bump | Create GitHub release |

License

MIT © Templ Project

Support

• Report Issues
• Read the Docs
• Star on GitHub