Open-source library with a deliberate public API, semver discipline, changelog-driven releases, and welcoming contributor docs.
Maintaining an open source library means balancing API stability, contributor-friendly docs, CI discipline, and semver — and your AI assistant should respect release boundaries, not treat every PR like a greenfield app. TailorMD's OSS Library recipe captures those expectations in CLAUDE.md, AGENTS.md, and Cursor rules built for published packages.
Tell TailorMD your language ecosystem, package manager, test runner, docs site, and release tooling. The generator produces a project brief covering public API surface rules, changelog discipline, breaking-change policy, and contributor workflows. Optional skills give repeatable code review and release checklists your assistant can follow.
This recipe is free on the web — generate, preview, copy, or download without an account. Whether you maintain a npm package, PyPI library, or Rust crate, the output adapts to your selections while keeping the same OSS-minded non-negotiables: no drive-by breaking changes, tested public APIs, and documentation that matches behavior. Regenerate when you adopt changesets, add a docs framework, or switch CI providers.
Answer a few questions about your stack. Copy CLAUDE.md or download a zip — no API key required.
npx tailormd init oss-library# my-lib TailorMD recipe: **OSS Library**. A TypeScript package other people depend on. The public API is a contract; every release either keeps it or bumps the version to say it didn't. ## Stack - **Language:** TypeScript - **Package manager:** npm - **Tests:** Vitest - **Releases:** Changesets + semver - **License:** MIT ## Folder map ``` src/ # implementation; only the public surface is exported from the entry index.* # the public API — everything re-exported here is a contract tests/ # unit tests mirroring src; public-behavior tests examples/ # runnable usage examples, kept compiling docs/ # API docs and guides CHANGELOG.md # human-readable, one entry per user-facing change README.md # what/why, install, quickstart, links LICENSE # MIT ``` ## Non-negotiables Public API discipline - Treat the entry point (`index`) as the contract. Anything exported is supported; keep internals unexported. - Breaking a public signature, removing an export, or changing documented behavior = a major version bump. No exceptions. - Deprecate before you remove: mark it, warn at runtime where feasible, document the replacement, remove in the next major. - No new runtime dependency without strong justification. Every dependency is your users' problem too; prefer zero-dep. Quality and safety - Public API is fully typed (TypeScript) and documented with examples that actually run. - Ship no secrets, no credentials, and no local paths. Publish only build artifacts + types + README + LICENSE (curate the files allowlist). - Support the documented runtime/version range; test against the whole matrix in CI, not just your machine. - Keep the bundle lean and side-effect-free where possible so consumers can tree-shake. ## Naming and style - Public names are stable, descriptive, and consistent; renaming a public export is a breaking change. - Follow the language's idioms and formatter (Prettier/ESLint, ruff, rustfmt). CI enforces format. - Errors thrown to users are typed/documented with actionable messages. ## Semver rules - **patch:** bug fix, no API change, no new behavior consumers must adopt. - **minor:** additive, backward-compatible (new export, new optional arg, new option). - **major:** any breaking change to a documented API or behavior. - Pre-1.0: still communicate breakage clearly; treat minor as "may break" and document it. ## Changelog and releases (Changesets) - Every user-facing change carries a changelog entry describing impact, not implementation. - Group entries as Added / Changed / Deprecated / Removed / Fixed / Security. - Releases are automated and reproducible; tag the commit, publish from CI, and attach release notes. - Never publish from a dirty tree or a non-CI machine for production releases. ## Contributor experience - README covers install, a 60-second quickstart, and a link to full docs. - CONTRIBUTING documents setup, how to run tests, and the PR/changeset flow. - Keep good first issues labeled; respond to issues with a repro request template. - Every PR includes tests and (if user-facing) a changelog entry. ## Commands ```bash npm install # install deps npm run build # build dist + types npm run lint # lint + format check npm run test # Vitest npm run docs # regenerate API docs ``` ## Testing strategy - Test the public API by behavior, not internals; internals can change freely, contracts cannot. - Cover edge cases, error paths, and documented examples; treat a failing example as a failing test. - Run the full support matrix (runtime/OS versions) in CI. - Add a regression test with every bug fix so it never returns. ## Ship checklist - [ ] Build + types succeed; lint/format clean - [ ] Vitest passes across the support matrix in CI - [ ] Public API change classified correctly (patch/minor/major) - [ ] Deprecations documented with a migration path; nothing removed without a prior major - [ ] Changelog entry added (impact-focused); README/docs updated - [ ] Published artifact contains only intended files (no secrets, no source-only cruft) - [ ] Release tagged and published from CI, not a laptop