Skip to content
ALNEAS Ecosystem

react-ai

@alneas/react-ai

Section titled “@alneas/react-ai”

English | 日本語

Headless React components and hooks for generative UI, proposal review and human-reviewed action workflows. MIT licensed. This public repository is the canonical source; the package depends on the published @alneas/ai-core.

Terminal window
npm install @alneas/react-ai react react-dom

Requires Node.js >=24 for Node consumers and React/React DOM 18.x or 19.x. Use the /generative-ui, /proposal and /action exports for individual domains. The root export includes all three. ESM, CommonJS and TypeScript declarations ship in the npm archive. Components are headless: the application owns rendering, credentials, persistence, callbacks and action authorization.

import {
  createGenerativeUIRegistry,
  defineGenerativeUIComponent,
  GenerativeUIRenderer,
} from '@alneas/react-ai/generative-ui';


const greeting = defineGenerativeUIComponent({
  type: 'greeting',
  dataSchema: {
    type: 'object', properties: { text: { type: 'string', maxLength: 200 } },
    required: ['text'], additionalProperties: false,
  },
  validate: data => typeof data.text === 'string'
    ? { ok: true, data: { text: data.text } } : { ok: false },
  component: ({ data }) => <p>{data.text}</p>,
});
const registry = createGenerativeUIRegistry([greeting]);
export function Greeting({ input }: { input: unknown }) {
  return <GenerativeUIRenderer input={input} registry={registry} />;
}

Register components explicitly. Model output supplies JSON data, never executable HTML, arbitrary component code, credentials or callbacks. Validators must be pure and synchronous. dataSchema uses the ai-core’s documented inline JSON Schema subset; structural validation does not replace application authorization or business rules. The registry exposes documentSchema only when every registration has a schema. See ai-core’s schema usage guide and source JSDoc for supported schema keywords, limits and API details.

See CONTRIBUTING.md for tests and RELEASING.md for independent CI and npm publication.

DOM interaction regression tests run with React 19 and an isolated React 18.3.1 install. They cover StrictMode registration, latest callbacks, unmount cancellation, rapid apply clicks, proposal/batch switching, hydration and error boundaries. React peers are limited to supported major versions 18 and 19. These tests use jsdom, while portable storage has separate native Chromium coverage.

Verification covers React 18.3 and 19: actual GenerativeUIRenderer + ScreenActionProvider/hooks SSR → hydration → click → document rerender → unmount, as well as hook interaction tests. Packed consumers type-check the base renderer exports against both React type versions, ESM/CJS, with and without Node types and without the optional SDK. The SDK entry is additionally checked with AI SDK 7.0.105 and Node types. Server and client must use the same initial immutable input and registry. Registered component validators must be pure and registered components must themselves be SSR/hydration-compatible; the library cannot make application-owned browser-only components server-safe.

React 18 and 19 are supported; React 18.3.1 has a dedicated compatibility suite.

Consumer AI guidance ships in dist/ai/SKILL.md and package-context.json. Preview the package-scoped additions to your project instructions with the following command. Add --write after reviewing the preview; existing instructions are preserved.

Terminal window
node node_modules/@alneas/react-ai/dist/ai/setup.mjs --project .