Skip to content

project rulesBackend and APIstypescript

TypeScript Library Rules

Project rules for publishing a TypeScript package: exports map, bundled types, semver discipline, tree-shaking and tests against the built output.

npx workspacetemplates add typescript-library-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file25 lines · 1.4 KBFile
# Project rules: TypeScript library

## Layout
- Source in `src/`, one `src/index.ts` that re-exports the public API. Anything not re-exported is private; do not add deep-import paths.
- Build with tsup, tsdown or tsc to `dist/`. Commit no build output.

## Package contract
- Describe entry points in the `exports` map with `types`, `import` and `require` conditions (types first). Keep `main` and `types` as fallbacks.
- Set `"sideEffects": false` when true, and list `files` explicitly so only `dist`, README and license ship.
- Dependencies are for runtime needs only. Frameworks the user already has go in `peerDependencies`.

## Types
- Enable `strict` and `declaration`. Prefer `unknown` over `any`, and never leak internal types in signatures.
- Export types with `export type`. Use `import type` inside the library.

## Versioning
- Removing or narrowing an export, or changing a signature, is a major bump. New optional features are minor. Record every change in CHANGELOG.md.
- Mark old APIs with `@deprecated` and a replacement before deleting them.

## Tests
- Unit tests with Vitest beside the code. Add a smoke test that imports the built package the way a consumer would.
- Run `npx publint` and `npx @arethetypeswrong/cli --pack` to catch export mistakes.

## Before finishing
Run `npm run lint`, `npm run typecheck`, `npm test` and `npm run build`. Report any change to the public API explicitly.

What it does

Writing a library is different from writing an app, because every exported name becomes a promise to strangers. These rules teach the agent to treat the public surface as a contract.

They cover how the package is described to bundlers and compilers, what a safe change looks like under semver, and how to prove that the built files work before a release.

Example

you › Add a retry option to the fetchJson helper

agent › The agent adds an optional field to the existing options type, keeps the old call signature working, exports the new type from index.ts, adds tests, notes a minor bump in the changelog, and runs publint.

Questions

Does this assume a specific bundler?
No. It names tsup and tsc as examples, but the rules concern the package contract, which is the same whichever tool produces dist.
Why check the built package and not just source?
Most publishing bugs live in the exports map and the generated declarations, which only show up when you import the packed output.
  • ASP.NET Core Web API Rules

    Project rulesdotnet

    Free
  • Django Rules

    Project rulespython

    Free
  • Flask Rules

    Project rulespython

    Free
  • Go Service Rules

    Project rulesgo

    Free