Quick Start

Create a new integration package or add Astryx to one you already publish.

Quick start

Make the package

An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, then install the Astryx CLI and Core for development.

bash
mkdir acme-widgets && cd acme-widgets
npm init -y
npm pkg set name=@acme/astryx-widgets
npm pkg set 'exports={}' --json
npm install -D @astryxdesign/cli @astryxdesign/core

Start with "exports": {}: each component and template you add then writes the public import that integration verify resolves.
Run the CLI as npx astryx, which runs the @astryxdesign/cli you installed as a devDependency.
Component commands read Core, so they need @astryxdesign/core installed.

Add your first integration item

An integration can ship several kinds of items. Start with a component named AcmeCarousel.

bash
npx astryx integration add component AcmeCarousel

text
component contribution added
[ok] AcmeCarousel
Declare component root ./components in astryx.integration.mjs.
- components/AcmeCarousel.doc.mjs
- components/AcmeCarousel.tsx
- package.json
- astryx.integration.mjs

integration add creates the component source, its .doc.mjs, the package export, and astryx.integration.mjs. Update the generated doc so the CLI understands the component, then write the component itself.

Read it back the way an app will.

bash
npx astryx component AcmeCarousel

You now have an integration package with one exported component.

Verify and pack the package

Run integration verify to check that an app would see the component, then make the .tgz file you install next. --pack-destination .. writes it beside the package folder, so the next pack does not ship it.

bash
npx astryx integration verify
npm pack --pack-destination ..

text
Integration package ready
[ok] @acme/astryx-widgets@1.0.0
4 packed files; 3/3 required files present.

integration verify packs the package, unpacks it into a temporary app, and checks that the component resolves through its public import there. It publishes nothing and leaves no .tgz file, so npm pack writes ../acme-astryx-widgets-1.0.0.tgz for the next step.

Use it in an app

Install Core, the CLI, and your .tgz file in a new app. The app loads your package because it is a dependency, with no config.

bash
cd ..
mkdir my-app && cd my-app
npm init -y
npm install @astryxdesign/core @astryxdesign/cli ../acme-astryx-widgets-1.0.0.tgz
npx astryx component AcmeCarousel

text
**Import:** `import {AcmeCarousel} from '@acme/astryx-widgets/components/AcmeCarousel';`

The next sections explain each package field and the integration file. To build the real component, continue with astryx docs cli/integrations/building-blocks/components.

Fill in package.json

An integration is an ordinary npm package. These six fields control how it is named, developed, checked, and published.

peerDependencies are packages the app supplies. devDependencies are packages you use while building the integration.

Field	Set it to	Why
`name`	Your package name, such as `@acme/astryx-widgets`	Each add writes it into the `import` of the doc it generates. Rename before you add, or update each `import` after.
`version`	The release you publish, such as `1.0.0`	Apps see it; `astryx.integration.mjs` never repeats it.
`exports`	Start with `{}`	Each component and template add writes its public import here, and `integration verify` resolves it.
`files`	Optional: the paths to publish	Keeps private files out. When the list exists, each add appends its root and `astryx.integration.mjs`.
`peerDependencies`	`@astryxdesign/cli`; add `@astryxdesign/core` when your code imports it	The app supplies these packages for your integration.
`devDependencies`	`@astryxdesign/cli` and `@astryxdesign/core`	Lets you run the CLI and build components while working on the integration.

Peer ranges and releases are covered in astryx docs cli/integrations/ship/versioning; files and publishing in astryx docs cli/integrations/ship/publishing.

The integration file

The first integration add creates astryx.integration.mjs, and each later add updates it. You do not need to write or edit this file during the quick start.

Files in the package

package.json defines the npm package, including its name, version, dependencies, published files, and exports.
astryx.integration.mjs tells the CLI where the package keeps each kind of integration item.
The integration item files live under those roots. For example, a component can have AcmeWidget.tsx for its source and AcmeWidget.doc.mjs for its documentation.

Fields in the integration file

astryx.integration.mjs

javascript
/** @type {import('@astryxdesign/cli/authoring').AstryxIntegration} */
export default {
  components: './components',
};

The file tells the CLI where this package keeps its integration items. Edit it only when you want a custom root or another optional setting. Paths are relative to package.json, and later adds keep a custom path you already set.

Field	Type	Required	Description
providerId	string	no	The name that marks this package as the source of everything it contributes. Leave it out to use the package name from package.json. Set it to the old name only during a rename, so the IDs of what the package already contributed stay the same. If two packages use the same name here, the one you are working on wins; otherwise the one the CLI reads first wins, and the CLI warns about the other. Example: '@acme/widgets'.
components	string	no	The folder that holds your components and their docs, relative to package.json. Example: './src/components'.
templates	string	no	The folder that holds your templates, relative to package.json. Example: './src/templates'.
codemods	string	no	The folder that holds your codemods, relative to package.json. Example: './codemods'.
docs	string	no	The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} in it shows up in `astryx docs` next to the built-in topics; a topic can also set `replaces` or `extends` to take over a built-in topic or add to it. Example: './docs'.
themes	string	no	The folder that holds your themes, relative to package.json, with one folder per theme. Each theme folder has the theme source and a matching .doc.mjs file with the same name. Installed themes show up in `astryx theme list` and can be copied with `astryx theme add`. Example: './themes'.
agentDocs	{ append?: readonly string[] }	no	Lines of guidance your package adds to the end of the agent instructions the CLI manages. The CLI owns the heading, labels, bullets, and which files it writes. Example: { append: ['Run acme verify.'] }.
issuesUrl	string	no	Where to file issues/feedback for this integration. Example: 'https://github.com/acme/widgets/issues'.

From Astryx Integration: astryx docs authoring integration

Use the CLI

You can edit the package files by hand, but the CLI handles the normal workflow. These links always open the canonical command docs.

astryx integration add: Add one working contribution to an integration package. Read it with astryx docs cli/commands/integration-add.

astryx integration verify: Check the package the way npm will publish it, before you publish. Read it with astryx docs cli/commands/integration-verify.

astryx doctor integration: Check an integration package while authoring it. Read it with astryx docs cli/commands/doctor-integration.