template-typescript-lib

Project template for TypeScript libraries optimized for tree-shaking.

Features

• ESM-only with proper exports configuration
• Tree-shaking optimized (see Tree Shaking)
• Types: TypeScript via tsgo
• Tests: Vitest
• Linting: oxlint + actionlint
• Formatting: dprint
• Package validation: publint + attw
• Publishing: Dripip
• CI: GitHub Actions

Quick Start

corepack enable

GitHub Template

gh repo create mylib --template jasonkuhrt/template-typescript-lib --clone --public && \
cd mylib && \
pnpm install && \
pnpm bootstrap

Then setup a repo secret called NPM_TOKEN for CI publishing.

Manual Clone

gh repo clone jasonkuhrt/template-typescript-lib mylib && \
cd mylib && \
pnpm install && \
pnpm bootstrap

Tree Shaking

This template is configured for aggressive tree-shaking. Bundlers (webpack, esbuild, rollup, vite) can eliminate unused code when consumers import from your library.

Configuration

Field	Value	Purpose
type	"module"	ESM output (required for tree-shaking)
sideEffects	false	Tells bundlers all modules are pure
exports	Explicit entry points	Black-boxes package internals

TypeScript Settings

Option	Purpose
verbatimModuleSyntax	Preserves ES module syntax for bundlers
isolatedModules	Ensures code is compatible with single-file transpilers

Validation

Two tools validate your package works correctly for consumers:

• publint - Checks packaging for compatibility across environments
• attw - Checks TypeScript types resolve correctly across module resolution modes

Run both with pnpm check.

Code Patterns

Prefer named exports

Named exports tree-shake more reliably than default exports. Default exports can cause issues with CommonJS interop.

// Preferred
export const foo = () => {}
export const bar = () => {}

// Avoid
export default { foo, bar }

Pure annotations

For module-level function calls (HOCs, factories), the /*#__PURE__*/ annotation tells bundlers the call is side-effect free. See Terser and UglifyJS docs.

sideEffects

Bundlers cannot always statically determine if code has side effects. The sideEffects field hints to bundlers that your modules are "pure" and safe to prune if unused.

Important: If you add modules with side effects (e.g., CSS imports, polyfills, or code that runs on import), update sideEffects to an array:

{
  "sideEffects": ["./src/polyfill.js", "**/*.css"]
}

Barrel Files

Barrel files (index.ts files that re-export from other modules) can inhibit tree-shaking in some bundlers. This template uses a single entry point which is acceptable for small libraries.

For larger libraries, consider:

• Multiple entry points via exports field
• Avoiding deep re-export chains
• Testing your bundle size with bundlephobia or pkg-size

References

• Webpack Tree Shaking Guide
• Tree-Shaking: A Reference Guide (Smashing Magazine)
• package.json exports field (Node.js)
• Building TypeScript Libraries (Arrange Act Assert)
• Are The Types Wrong?

Details

• TypeScript
• Linting
• Testing
• Formatting
• npm Scripts
• CI
• Zed Settings

TypeScript

• Strict settings via @tsconfig/strictest
• Node 22 target via @tsconfig/node22
• Build cache in node_modules/.cache
• Output includes declaration, declarationMap, sourceMap for optimal consumer DX
• Source published for go-to-definition support

Linting

• oxlint: Rust-based, ~100x faster than ESLint
• actionlint: GitHub Actions workflow validation

Testing

Vitest - fast, ESM-native test runner.

Formatting

dprint - fast Rust-based formatter.

npm Scripts

Parallel execution via pnpm pattern matching:

Script	Description
check	Run all checks in parallel
check:format	Verify formatting
check:lint	Run oxlint
check:types	Type check with tsgo
check:package	Validate package with publint
check:exports	Validate exports with attw
check:ci	Lint GitHub Actions workflows
fix	Run all fixes in parallel
fix:format	Fix formatting
fix:lint	Auto-fix lint issues
build	Build with tsgo
test	Run tests

CI

PR workflow:

• actionlint, format, lint, types, publint checks
• Tests on ubuntu/macos/windows, Node 22

Trunk workflow:

• Automated canary release via Dripip

Zed Settings

Configure tsgo globally in ~/.config/zed/settings.json:

{
  "languages": {
    "TypeScript": {
      "language_servers": ["tsgo", "!vtsls", "oxc"]
    }
  }
}

---