Framework-free install still pulls React 19 and the d3 chart stack

[jkrumm]

Follow-up to the 1.3.0 framework-free work. Verified against the published basalt-ui@1.3.0 from npm, installed into an empty directory with no React present.

What works

All 24 peers are optional — peerDependenciesMeta marks every one, and npm reports zero required peers. That part of the change is correct.

What it doesn't achieve

Optional peers don't reduce the install, because npm installs a package's full dependencies regardless of which subpath the consumer imports. A consumer that wants only the tokens gets:

$ npm i basalt-ui@1.3.0     # in an empty project, no react
added 56 packages
$ npm ls react
basalt-ui@1.3.0
└─┬ @visx/axis@4.0.0
  └── react@19.2.8

56 packages, 30 top-level, React 19 in the tree. The hard dependencies are @visx/* (×9), motion, remend, and three @fontsource-variable/*. @visx declares React as its own dependency, so it arrives transitively no matter what the peer metadata says.

So the documented framework-free path — install the package, import basalt-ui/tokens, emit CSS — still drags the entire React chart stack in for a static site that renders no components.

Two ways out

A. Move the chart and font deps to optional peers. Consistent with how @mantine/* is already handled, and it makes the dependency graph match the modularity the exports map already claims. Cost: basalt-ui/charts consumers install @visx/* themselves.

B. Document that the framework-free path shouldn't install the package at all. Now that dist/tokens.css is prebuilt and shipped and tokens:css exists, a static site can vendor the emitted file, or generate it in a repo that carries basalt as a devDependency, and ship zero runtime dependency. The install weight becomes irrelevant for the case it was blocking.

B is free and is what a static site actually wants; A is the more honest fix if basalt-ui/tokens is meant to be a supported runtime import. Currently docs/FRAMEWORK-FREE.md implies the install is lightweight, which measurement doesn't support either way.

Filed from the jkrumm.com side — see docs/basalt-astro.md in that repo for the original consumer evaluation.

[coderabbitai]

🔗 Related PRs

#7 - feat: improve package integration and documentation [closed]
#8 - feat: Astro 6 Fonts API integration and dependency upgrades [closed]
#13 - fix: unblock consumers on the shipped 1.0 agentic surface [merged]
#19 - feat: add basaltAppPlugin for PWA head, manifest, and icon metadata [merged]
#24 - feat: framework-free token consumption [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[jkrumm]

Fixed in #36 — option A, and B's documentation along with it.

The nine @visx/*, motion, remend and the three @fontsource-variable/* are now optional peers. dependencies is empty: a bare bun add basalt-ui installs exactly one package, down from 56.

The pack-test grew the gate that was missing — a scratch install with no peers at all, asserting @visx/scale is absent from the tree while basalt-ui/tokens still resolves and buildPaletteCss() still runs. Nothing tested that property before, which is precisely how the install weight drifted from the documented one.

docs/FRAMEWORK-FREE.md is rewritten. It led with installing the package; the vendor route now leads, because a static site shipping zero runtime dependency is what that route was always for.

One correction. React did not arrive because @visx declares it as a dependency — it declares it as a peer, confirmed in both its manifest and our lockfile. npm 7+ auto-installs peer dependencies, which is what npm ls react was showing. Doesn't change the conclusion or the fix; the weight removed here is the visx/d3/font tree itself, which was genuinely dependencies.

Worth saying the underlying judgement was right independent of all this: for a static site the correct pattern was always "generate once, vendor the file", and that was free before this change too.