The ts-package-template follows a well-organized directory structure designed for TypeScript package development. Here's a comprehensive overview of the project layout:

Directory Overview

./
├── ./.vscode/
│   └── settings.json
├── ./src/
│   └── index.ts
├── ./test/
│   └── index.test.ts
├── ./scripts/
│   └── git-cliff.toml
├── biome.json
├── CHANGELOG.md
├── cliff.toml
├── lefthook.yml
├── LICENSE
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
├── tsconfig.json
├── tsconfig.build.json
├── tsdown.config.ts
└── vitest.config.js

Root Directory Files

Configuration Files

Documentation Files

IDE Configuration

Source Code Structure

/src/ Directory

The main source code directory where your TypeScript package code resides.

src/
└── index.ts

• index.ts: The main entry point of your package. This is where you export your public API.
• Add additional TypeScript files as needed for your package functionality.

/test/ Directory

The test directory containing your unit tests.

test/
└── index.test.ts

• index.test.ts: Test file for the main index.ts module.
• Add additional test files as needed for your package.

/scripts/ Directory

Additional configuration files and scripts.

scripts/
└── git-cliff.toml

• git-cliff.toml: Additional git-cliff configuration (referenced in package.json scripts).

Key Configuration Files Explained

TypeScript Configuration

The template uses two TypeScript configuration files:

1. tsconfig.json: Main configuration with development settings

   • Target: ESNext
   • Module: ESNext
   • Strict mode enabled
   • Bundler mode settings
   • Path aliases configured

2. tsconfig.build.json: Build-specific configuration

   • Extends main tsconfig.json
   • Sets output directory to dist
   • Additional strict null checks

Bundler Configuration

tsdown.config.ts: Configuration for the Rolldown bundler with tsdown plugin

• Entry point: src/index.ts
• Output format: ESM (ECMAScript Modules)
• TypeScript declaration files: Enabled
• Source maps: Disabled (for production)

Testing Configuration

vitest.config.js: Configuration for Vitest

• Test file pattern: **/*.test.ts
• Global test environment variables enabled

Code Quality Configuration

biome.json: Configuration for Biome

• Extends ultracite/biome/core configuration
• VCS integration enabled
• File includes: src/**/*.ts
• Assist features enabled

Git Hooks Configuration

lefthook.yml: Configuration for lefthook

• Pre-commit hooks configured
• Runs ultracite fix on staged files
• Supports various file types (JS, TS, JSON, CSS)

File Patterns and Conventions

Naming Conventions

• TypeScript files: Use .ts extension
• Test files: Use .test.ts suffix
• Configuration files: Use appropriate extensions (.json, .toml, .yml)

Import Paths

The template configures path aliases for easier imports:

// Instead of relative paths
import { sum } from '../../src/index';

// You can use path aliases
import { sum } from '~/src/index';
// or
import { sum } from '@/index';

Module Resolution

• Uses TypeScript's moduleResolution: "bundler"
• Supports ES modules with "type": "module" in package.json
• Uses verbatimModuleSyntax for accurate module syntax

Adding New Files

When adding new files to your project:

1. Source files: Add to /src/ directory
2. Test files: Add to /test/ directory with .test.ts suffix
3. Configuration files: Add to root or appropriate subdirectories
4. TypeScript files: Ensure they're included in tsconfig.json