js-library-packaging

js-library-packaging

Pack placement. engineering-base. The step asked for it to be suggested by the react and typescript packs, and the skill schema carries no suggested_by key — so the intent is recorded here rather than expressed in frontmatter that would fail validation. A React or TypeScript consumer receives this skill through engineering-base, which both of those packs require.

The JavaScript twin of composer-packages. A component is a file; a library is a package with a public surface, and that surface is declared in package.json rather than inferred. Most of the failures below are silent at author time and loud at the consumer's — which is why the surface is read, not assumed.

The Iron Law

`react` AND `react-dom` ARE peerDependencies. NEVER dependencies.
`types` IS THE FIRST KEY OF EVERY CONDITIONS OBJECT.
DECIDE buildable-VS-source-consumed BEFORE WRITING THE EXPORTS MAP.
NEVER HAND-BUMP A VERSION.

When to use

A package in the repository is imported by another package, or is about to be published: an exports map is being written or changed, a hook fails at runtime with "invalid hook call", an install fails on a workspace: range, a release needs cutting, or the buildable-vs-source question has not been answered yet.

Procedure

1. Answer buildable-vs-source-consumed FIRST. It determines the exports map, the files list, and whether a build step exists at all — deciding it after writing the map means rewriting the map.
   • Source of truth: is the package published to a registry, or only consumed inside this workspace?
   • Verify: the exports targets all point into one of the two worlds (src/ or the build directory), never a mix.
2. Read the surface rather than asserting it. Run the check below over the package root.
   • Source of truth: package.json — exports, dependencies, peerDependencies, files, private, publishConfig.
   • Verify: zero error-severity findings.
3. Fix peer placement before anything else. A library carrying react in dependencies gives the consumer a second copy of React.
   • Verify: react and react-dom appear under peerDependencies only.
4. Order the conditions. types first, then import / require.
   • Verify: the check reports no types-not-first.
5. Cut the release through the repository's own mechanism — never by editing a version field. See § Release.
   • Verify: the version change is produced by the tool the repository already carries.