Replace a Core component

Use a component replacement only when an integration must intentionally own a Core component identity.

Decide whether to replace

Most components should not use replaces. Give a new component its own name and let apps choose it explicitly. Replace Core only when your component must become the default for one Core identity everywhere the integration is active.

Use it when

Your component intentionally serves the same role as one specific Core component.
Every app that loads the integration should get your component from unqualified component detail, lists, search, swizzle, and issue routing.
You have tested both the replacement and explicit access to the original Core component.

Do not use it when

Your component is an alternative, variant, wrapper, or product-specific extension. Give it a unique name instead.
You only need to resolve an accidental name collision.
You want the replacement in only one screen or workflow. Replacement applies across the app wherever the integration is active.

Set the replacement

components/AcmeSideNav.doc.mjs

javascript
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export default {
  type: 'component',
  name: 'AcmeSideNav',
  displayName: 'Acme Side Nav',
  replaces: 'SideNav',
  import: '@acme/astryx-widgets/components/AcmeSideNav',
  usage: {description: 'Product navigation for Acme apps.'},
  props: [],
};

Field	Type	Required	Description
replaces	string	no	Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, lists, search, swizzle, and issue routing. The Core original stays reachable with `--package @astryxdesign/core`. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.

From ComponentDoc: astryx docs authoring component-doc

replaces names the Core ComponentDoc identity, not its display label, import path, or a standalone hook.
Your component may keep a distinct name or use the same name as the target. A distinct name remains directly addressable on older CLIs that ignore replaces.
--package @astryxdesign/core always selects the original Core component.

Check replacement resolution

bash
npx astryx doctor integration components
npx astryx component SideNav
npx astryx component AcmeSideNav
npx astryx component SideNav --package @astryxdesign/core

A missing target, invalid value, second replacement for one target in the same package, or a replacement named after a different Core component is an error.
When several integrations replace one target, explicit configuration beats the automatic pick. Among explicitly configured integrations, the later package wins and Doctor warns.