skills.rest
GonkaGate
GonkaGateOFFICIAL
Explore all skills by this author →
Website𝕏@gonkagateGitHub

typescript-public-api-design

Designs and reviews exported TypeScript function signatures, module entrypoints, and public type surfaces.

1|1|Updated Apr 8, 2026
Search Tags:#typescript#api design#compatibility#declaration files#public api#library design#package exports
One-click install
npx skills add https://github.com/GonkaGate/opencode-setup --skill typescript-public-api-design-gonkagate
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: typescript-public-api-design
Source: https://github.com/GonkaGate/opencode-setup/tree/main/.agents/skills/typescript-public-api-design
Command: npx skills add https://github.com/GonkaGate/opencode-setup --skill typescript-public-api-design-gonkagate

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Public TypeScript APIs accumulate accidental complexity: sprawling exports, unstable inferred declaration types, unclear overload sets, and breaking changes shipped without a compatibility story. This Skill applies disciplined public-surface reasoning so library and backend-module APIs stay minimal, stable, and consumer-friendly over time. ## Core Features & Use Cases - Public Surface Mapping: Identifies supported import paths via package.json exports, exported symbols, and emitted .d.ts declarations as the true public contract. - Signature Shape Decisions: Chooses between overloads, unions, generics, options objects, and discriminated unions based on consumer inference and call-site ergonomics. - Compatibility Classification: Labels proposed changes as non-breaking, conditionally breaking, or breaking, with explicit consumer impact and evolution/deprecation strategies. - Use Case: When refactoring a library's entrypoint or adding a new exported function, use this Skill to audit the declaration surface, pick the smallest honest public shape, and define a safe deprecation path for the old API. ## Quick Start Ask the AI to review your package's exported functions and package.json exports field and recommend a minimal, compatibility-safe public API design.

Frequently Asked Questions about typescript-public-api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a public API for a TypeScript library?▼

Start by defining supported import paths through package.json exports, then curate the minimal set of exported symbols consumers need. Give exported functions explicit return types to stabilize emitted declarations, and prefer unions or options objects over unnecessary overloads.

When should I use overloads versus union types in TypeScript?▼

Use a union when argument shapes vary but the return type stays the same. Use overloads only when distinct call forms intentionally produce different result types, placing more specific overloads before general ones.

How do I know if a TypeScript API change is breaking?▼

Classify from the consumer side: removing exports, tightening parameter types, or blocking deep imports via exports is breaking. Adding optional options or new subpaths is usually non-breaking, while union additions can break exhaustive switches.

Does package.json exports affect which import paths are public?▼

Yes, the exports field defines the supported import paths and is the authoritative public contract. Files existing in the repository do not make them public; deep imports not listed in exports are internal implementation details.

Why do emitted .d.ts files matter for API design?▼

Emitted declarations are what consumers actually compile against, so inferred return types can leak internal helpers or shift across TypeScript versions. Explicit public return types keep the declaration surface stable and readable.

When should I not use this public API design approach?▼

This Skill does not cover internal implementation style, advanced conditional or mapped type machinery, runtime validation of untrusted input, or ESM/CJS compiler-runtime interop. Those concerns belong to adjacent TypeScript specialties.

Related Skills

Explore More Software Engineering Skills→
anthrilanthril
3

npm-package-audit

Audit npm package.json fields, exports maps, and build configuration.

Official
Advanced
jrc1883jrc1883

deploy-npm

Automate npm package publishing with package.json validation and semver gating.

Community
Advanced
tylerbutlertylerbutler

api-reports

Regenerate API Extractor reports and manage release tags in a monorepo.

Community
Advanced
JNZader-VaultJNZader-Vault

zod-validation

Validate TypeScript data structures at runtime using Zod schemas.

Official
Intermediate