playbooks

home / skills / onmax / nuxt-skills / ts-library

ts-library skill

/skills/ts-library

This skill helps you author high-quality TypeScript libraries by guiding project setup, exports, tooling, API design, tests, and release workflows.

npx playbooks add skill onmax/nuxt-skills --skill ts-library

Review the files below or copy the command above to add this skill to your agents.

Files (10)
SKILL.md
2.4 KB
---
name: ts-library
description: Use when authoring TypeScript libraries - covers project setup, package exports, build tooling (tsdown/unbuild), API design patterns, type inference tricks, testing, and release workflows. Patterns extracted from 20+ high-quality ecosystem libraries.
license: MIT
---

# TypeScript Library Development

Patterns for authoring high-quality TypeScript libraries, extracted from studying unocss, shiki, unplugin, vite, vitest, vueuse, zod, trpc, drizzle-orm, and more.

## When to Use

- Starting a new TypeScript library (single or monorepo)
- Setting up package.json exports for dual CJS/ESM
- Configuring tsconfig for library development
- Choosing build tools (tsdown, unbuild)
- Designing type-safe APIs (builder, factory, plugin patterns)
- Writing advanced TypeScript types
- Setting up vitest for library testing
- Configuring release workflow and CI

**For Nuxt module development:** use `nuxt-modules` skill

## Quick Reference

| Working on...         | Load file                                                          |
| --------------------- | ------------------------------------------------------------------ |
| New project setup     | [references/project-setup.md](references/project-setup.md)         |
| Package exports       | [references/package-exports.md](references/package-exports.md)     |
| tsconfig options      | [references/typescript-config.md](references/typescript-config.md) |
| Build configuration   | [references/build-tooling.md](references/build-tooling.md)         |
| API design patterns   | [references/api-design.md](references/api-design.md)               |
| Type inference tricks | [references/type-patterns.md](references/type-patterns.md)         |
| Testing setup         | [references/testing.md](references/testing.md)                     |
| Release workflow      | [references/release.md](references/release.md)                     |
| CI/CD setup           | [references/ci-workflows.md](references/ci-workflows.md)           |

## Key Principles

- ESM-first: `"type": "module"` with `.mjs` outputs
- Dual format: always support both CJS and ESM consumers
- `moduleResolution: "Bundler"` for modern TypeScript
- tsdown for most builds, unbuild for complex cases
- Smart defaults: detect environment, don't force config
- Tree-shakeable: lazy getters, proper `sideEffects: false`

_Token efficiency: Main skill ~300 tokens, each reference ~800-1200 tokens_

Overview

This skill helps authors build production-ready TypeScript libraries with practical patterns for project setup, exports, build tooling, API design, testing, and releases. It distills conventions used by 20+ high-quality ecosystem libraries so you can adopt ESM-first, dual-format, and type-safe workflows quickly. Use it to standardize tooling and avoid common pitfalls when publishing packages.

How this skill works

The skill inspects common library concerns: package exports, tsconfig and module resolution, build tool choice (tsdown or unbuild), output formats, and test configuration. It recommends concrete file layouts, export maps, and build pipelines, and provides API design patterns (builder, factory, plugin) plus advanced type inference techniques. It also outlines CI/release workflows and test setups for reliable releases.

When to use it

  • Starting a new TypeScript library (single package or monorepo)
  • Configuring package.json exports for both CJS and ESM consumers
  • Choosing a build toolchain (tsdown for typical libraries, unbuild for complex needs)
  • Designing type-safe public APIs and advanced type inference
  • Setting up vitest-based testing and automated release CI

Best practices

  • Prefer ESM-first sources with dual outputs (ESM and CJS) and clear export maps
  • Use moduleResolution: "Bundler" and strict tsconfig options for predictable types
  • Keep runtime abstractions minimal; expose tree-shakeable APIs and mark sideEffects: false
  • Choose tsdown for most builds; switch to unbuild when rollups, polyfills, or multiple targets are required
  • Provide smart defaults and runtime environment detection rather than forcing user config

Example use cases

  • Create a library that publishes both .mjs and .cjs builds while keeping accurate type declarations
  • Design a plugin API with a factory pattern to preserve inference and extensibility
  • Set up CI to run vitest, type checks, and automated release on tags
  • Migrate an older CJS package to ESM-first while maintaining compatibility for consumers
  • Structure a monorepo with consistent tsconfigs and per-package export maps

FAQ

Should I always publish both CJS and ESM?

Prefer ESM-first sources but provide CJS builds if you need to support older tooling or Node versions. Use export maps to control conditional resolution.

When to choose tsdown vs unbuild?

Start with tsdown for straightforward libraries; choose unbuild when you need multiple targets, complex rollups, or extra bundler features.