Replace a Core template

Use with care: replace a Core template only when every app using this integration should receive your source for an existing Core id by default. An alternative, a product-specific variation, or a different kind of template gets its own id instead (astryx docs cli/integrations/building-blocks/templates/start-a-template).

• Sharing a Core id without replaces does not replace Core. It makes the bare id ambiguous, so astryx template <id> fails until the app adds --package, and doctor integration templates reports an accidental collision.
• A replacement can keep the Core id or use its own. replaces is what makes it the default.

Find the exact Core id and kind first.

bash
npx astryx --json template --list --package @astryxdesign/core

javascript
/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
export default {
  type: 'page',
  name: 'acme-app-shell',
  displayName: 'Acme App Shell',
  description:
    'An Acme application shell with product navigation, account controls, and a responsive content region.',
  replaces: 'shell-side-nav',
  isReady: true,
  category: 'Shell - Left Sidebar',
};

From TemplateDoc: astryx docs authoring template-doc

Declare replaces on the template doc, never in astryx.integration.mjs.

Declare the CLI floor from the field above as an optional peer (astryx docs cli/integrations/ship/versioning).

json
{
  "peerDependencies": {
    "@astryxdesign/cli": ">=0.7.0"
  },
  "peerDependenciesMeta": {
    "@astryxdesign/cli": {
      "optional": true
    }
  }
}

integration verify reports replaces_needs_cli when that peer is missing or too old. Without it, an older CLI drops that template and hides your doc topics.

bash
# Receives the active replacement
npx astryx template shell-side-nav src/app
​
# Receives the original Core template
npx astryx template shell-side-nav --package @astryxdesign/core src/app

When several integrations replace the same Core template, one wins:

• An integration explicitly listed in astryx.config.mjs wins over one that is only installed and picked automatically.
• When several explicitly configured integrations replace the same target, the one listed later wins and Astryx reports the ambiguity.
• When no integration is configured explicitly, the package listed later in the app's package.json dependencies wins. Configure the intended integration explicitly instead of relying on that order.

bash
npx astryx doctor integration templates

Replacement resolution is safe by default. A missing source, invalid doc, missing target, wrong kind, or conflicting declaration never hands the Core id to a questionable replacement: Astryx reports the issue and keeps the Core template. Fix every issue before publishing.