Managing Packages

Deprecate or unpublish a published package with the same npm commands you already use. Both are recorded as new immutable versions, so nothing is lost and every change is reversible.

Deprecating a package

Mark a package as deprecated so anyone installing it sees a warning and the component shows a deprecated badge on Bit Cloud:

npm deprecate @my-org/design.button "use @my-org/design.button2 instead"

Lift the deprecation by passing an empty message:

npm deprecate @my-org/design.button ""

Deprecation applies to the package (component) as a whole.

Installs print a standardized notice (with the replacement id, when you name one) — npm's free-text message is not stored.

The Bit Cloud badge updates immediately; the npm warning can take up to an hour to appear.

Unpublishing a package

Remove a package so it can no longer be installed:

npm unpublish @my-org/design.button --force

It is a soft delete — the component is hidden and installs return 404.

History is preserved, so the removal is reversible (restore it from the component page).

Publishing access governs unpublishing: you need write access to the scope.

Only whole-package unpublish is supported — single-version unpublish is not, because published versions are immutable. To steer users off one version, deprecate it instead.

How deprecate and unpublish work

Both commands are recorded as new immutable versions through the regular export pipeline — no rebuild is triggered, and prior versions stay intact. That is why deprecate and unpublish are fully reversible and never rewrite what was already published.

Documentation

Your component's documentation comes straight from the package — no extra step:

Overview — the package README.md is rendered as the component's overview page.

Description & labels — description from package.json becomes the component description, and keywords become searchable labels on Bit Cloud.

Doc files — any file named *.docs.* (e.g. button.docs.mdx) is recognized as documentation.

Compositions

Compositions are live, rendered examples of your component. To include them, ship a file named *.composition.* (or *.compositions.*) in your package:

// button.composition.tsx
export const Primary = () => <Button variant="primary">Click me</Button>;
export const Disabled = () => <Button disabled>Can't click</Button>;

Each exported identifier (Primary, Disabled) becomes a composition on the component. Compositions are detected at publish from the file's exports; the fully-rendered preview is produced by the Ripple CI build.

Files are recognized by name, so they must be included in the published tarball. Packages that ship only dist/ won't contain README.md, *.docs.*, or composition files unless you add them to the package's files list. Naming also classifies files: *.composition(s).* → compositions, *.docs.* → docs, *.spec.* / *.test.* → tests; everything else is runtime source.

Choosing a Bit env

Every mirrored component gets a Bit env — the environment that builds, compiles and tests it on Ripple CI and powers its preview and docs. If you publish without specifying one, the default JavaScript env (bitdev.general/envs/js-env) is applied automatically, so any package just works.

To use a different env — say a React env so the component gets React tooling and previews — add a top-level bitEnv field to your package.json:

{
  "name": "@my-org/design.button",
  "bitEnv": "bitdev.react/react-env"
}

Omitted — defaults to the JavaScript env. Nothing to configure.

Common choices: bitdev.general/envs/js-env, bitdev.node/node-env, bitdev.react/react-env.