creating-a-package

name	creating-a-package
description	Scaffold a new workspace package in the c15t monorepo. Use when adding a package under packages/, wiring up rslib builds, vitest, turbo, exports maps, or deciding whether a package joins the linked changeset group.

Creating a c15t Package

Copy the shape of an existing package rather than inventing one. packages/logger is the minimal template; packages/core shows prebuild/version generation and bundled docs; packages/react shows subpath exports, CSS entrypoints, and browser tests.

Checklist

1. Directory: packages/<name> (auto-included by the root workspaces globs). Kebab-case file names throughout — Biome errors otherwise.

2. package.json — match the house shape:

   • "name": "@c15t/<name>", same version as the linked group if it will join it, "type": "module", "sideEffects": false where true, Apache-2.0 license, repository.directory set.
   • Exports map pointing at build output:

     "exports": { ".": { "types": "./dist-types/index.d.ts", "import": "./dist/index.js", "require": "./dist/index.cjs" } },
     "main": "./dist/index.cjs", "module": "./dist/index.js", "types": "./dist-types/index.d.ts",
     "files": ["dist", "dist-types"]
     

   • Standard scripts (copy from logger): build (rslib + normalize-dist-types.mjs), dev (rslib watch, --no-dts --no-clean), check-types (tsc --noEmit), lint (bun biome lint ./src), fmt, test (vitest run, add --passWithNoTests until tests exist). Core SDK packages additionally run prepack (bun ../../scripts/verify-package-artifacts.ts) — add it if the package ships to end users.
   • Workspace deps use "workspace:*". Dev deps include @c15t/typescript-config and, if tested, @c15t/vitest-config.

3. rslib.config.ts: ESM + CJS, dts.distPath: './dist-types' on the ESM lib only, source.exclude for test globs, getRsdoctorPlugins() from ../shared/rslib-utils. If the package needs a runtime version string, add the prebuild genversion script like core (src/version.ts is generated — gitignore it).

4. tsconfig.json: extend @c15t/typescript-config/base.json (or next.json/node.json). Don't relax strictness.

5. vitest.config.ts: extend @c15t/vitest-config base config; add the package to root vitest.workspace.ts if it should run in the workspace suite. Browser tests follow packages/react/vitest.config.ts (@vitest/browser-playwright, Chromium).

6. turbo.json: the generic build/test/lint tasks cover most packages. Add a package-specific entry only if outputs differ (e.g. bundled docs add AGENTS.md + docs/** to build outputs) or the demo should watch it (@c15t/example-demo#dev.with).

7. Changesets: decide whether it joins the linked group in .changeset/config.json (core SDK packages that must version together) or versions independently (utilities like logger/schema/ui).

8. README: user-facing published packages get a generated README.md — create readme.json (see packages/react/readme.json) and run bun run generate:readmes; don't hand-write README.md. Internal utility packages (like schema/ui today) may skip it.

9. Bundled docs (only for user-facing SDK packages): add a config entry in scripts/generate-package-docs.ts and include "AGENTS.md", "docs" in files plus a build:docs script.

10. knip.json: add one if the package has intentional unused-export patterns; run bun run knip to check.

Verify

bun install
bun turbo run build check-types lint test --filter=@c15t/<name>
bun pm pack --dry-run --cwd packages/<name>