@aria-ui/cli

A CLI and programmatic API that generates typed framework wrappers for @aria-ui/elements (or any custom-element library built with @aria-ui/core).

@aria-ui/elements ships native Web Components. The CLI reads your component source files with ts-morph, extracts each component's props and events, and emits idiomatic wrapper components for the framework of your choice.

Supported frameworks

• React
• Preact
• Solid
• Vue
• Svelte

Installation

npm install --save-dev @aria-ui/cli
# or
pnpm add -D @aria-ui/cli

typescript is an optional peer dependency — install it if it isn't already in your project.

CLI usage

npx aria-ui build \
  --tsconfig ./tsconfig.json \
  --entry node_modules/@aria-ui/elements/src/listbox/index.ts \
  --output ./src/components/listbox \
  --framework react \
  --import-source @aria-ui/elements/listbox

Flags

| Flag | Required | Description | | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | --tsconfig | yes | Path to a tsconfig.json that can resolve the entry file. | | --entry | yes | Path to the entry file that re-exports the components you want wrapped. | | --output | yes | Output directory for the generated wrapper files. | | --framework | yes | One of react, preact, solid, vue, svelte. | | --import-source | yes | Module specifier the generated code uses to import the underlying elements (e.g. @aria-ui/elements/listbox). | | --prefix | no | Custom-element tag prefix. Defaults to aria-ui. |

Programmatic API

import { build } from '@aria-ui/cli'

await build({
  tsconfig: './tsconfig.json',
  entry: './node_modules/@aria-ui/elements/src/listbox/index.ts',
  output: './src/components/listbox',
  framework: 'react',
  importSource: '@aria-ui/elements/listbox',
  prefix: 'aria-ui',
})

Wrapper extensions

You can customize how wrappers are generated by passing wrapperExtensions. Each extension can match specific components and inject imports, setup statements, render-prop expressions, or framework-specific overrides.

import { build, propFallback, type WrapperExtension } from '@aria-ui/cli'

const idFallback: WrapperExtension = propFallback({
  prop: 'id',
  frameworks: {
    react: { importSource: 'react', importName: 'useId', callExpression: 'useId()' },
  },
})

await build({
  // ...
  wrapperExtensions: [idFallback],
})

A WrapperExtension looks like:

interface WrapperExtension {
  name: string
  match?: (context: WrapperMatchContext) => boolean
  apply(context: WrapperApplyContext): void
}

The WrapperApplyContext exposes helpers such as addImport, addSetupStatement, setRenderPropsExpression, setReactPropOverride, and addSvelteScriptStatement. The built-in propFallback extension is a good reference for how to write your own.

What it generates

Given a component like ListboxRoot with the props value, multiple, etc. and the events valueChange and valuesChange, the React generator emits a wrapper that:

• Maps each prop to the right HTML attribute or JS property based on its declared type.
• Converts each DOM event into a React-style onValueChange callback whose argument is the original event (so event.detail is preserved).
• Forwards ref to the underlying custom element.
• Re-exports the prop and event types from the source package.

The generated files are formatted with oxfmt so they look at home in your project.

License

MIT