TypeScript SDK

The TypeScript SDK lets frontend and backend TypeScript code author type-safe SDUI specs. Platform packages export shared expression helpers, while generated catalog subpaths export components, actions, rendering, introspection, and validation.

Packages and imports

Core authoring helpers come from the platform package:

import { createSpec, equals, truthy, and_ } from '@rippling/pebble-sdui-web';

Catalog-specific builders come from generated catalog subpaths:

import {
  Button,
  Text,
  VStack,
  render,
  showNotification,
  validate,
} from '@rippling/pebble-sdui-web/catalogs/custom-apps';

Quick start

import { createSpec, truthy } from '@rippling/pebble-sdui-web';
import {
  Button,
  Text,
  VStack,
  render,
  showNotification,
  validate,
} from '@rippling/pebble-sdui-web/catalogs/custom-apps';

interface AppState {
  userName: string;
  isReady: boolean;
}

const { $state, $template } = createSpec<AppState>({
  state: {
    userName: 'Alice Nguyen',
    isReady: true,
  },
});

const root = VStack({
  id: 'root',
  props: { gap: 12 },
  visible: truthy($state('isReady')),
  children: [
    Text({
      props: {
        text: $template`Hello ${$state('userName')}`,
      },
    }),
    Button({
      props: {
        label: 'Continue',
        appearance: 'PRIMARY',
      },
      on: {
        press: showNotification({
          message: 'Continuing',
          variant: 'success',
        }),
      },
    }),
  ],
});

const spec = render({
  root,
  state: {
    userName: 'Alice Nguyen',
    isReady: true,
  },
});

const errors = validate(spec);
if (errors.length > 0) {
  throw new Error(`Invalid spec:\n${errors.join('\n')}`);
}

Authoring steps

1. Define a TypeScript state interface.
2. Create state helpers with createSpec<State>({ state }).
3. Import components/actions from one generated catalog subpath.
4. Compose a component tree with generated builder functions.
5. Use $state(), $bindState(), $template, $cond(), and repeat() for dynamic behavior.
6. Call the catalog render({ root, state }).
7. Call the catalog validate(spec) for generated, hand-authored, or externally consumed specs.

Human authoring benefits

• Editor autocomplete for component props and event names.
• TypeScript validates state paths and expression result types.
• Component builders enforce whether children and on are allowed.
• Action creators enforce action params.
• Catalog render() stamps platform/catalog metadata.

LLM authoring benefits

• Catalog introspection gives exact names and schemas.
• SDK code is easier to validate and repair than raw JSON.
• Generated builders prevent many invalid tree shapes.
• Validation errors provide deterministic repair feedback.

More TypeScript docs

• components-actions-rendering.md
• state-expressions.md