@brightsy/component-dev-kit

Development kit for building custom Brightsy component libraries.

Installation

# npm
npm install --save-dev @brightsy/component-dev-kit

# pnpm
pnpm add -D @brightsy/component-dev-kit

# yarn
yarn add -D @brightsy/component-dev-kit

Peer dependencies (install if not already present):

npm install react vite @vitejs/plugin-react

Quick Start

1. Create a Component

// src/components/Button.tsx
import React from 'react';
import { defineComponent, BrightsyComponentConfig } from '@brightsy/component-dev-kit';

interface ButtonProps {
  text: string;
  href: string;
  variant?: 'primary' | 'secondary';
}

const ButtonComponent = ({ text, href, variant = 'primary' }: ButtonProps) => (
  <a href={href} className={`btn btn-${variant}`}>
    {text}
  </a>
);

export const Button = defineComponent<ButtonProps>({
  component: ButtonComponent,
  config: {
    label: 'Button',
    category: 'Interactive',
    fields: {
      text: { type: 'text', label: 'Button Text' },
      href: { type: 'text', label: 'Link URL' },
      variant: {
        type: 'radio',
        label: 'Style',
        options: [
          { label: 'Primary', value: 'primary' },
          { label: 'Secondary', value: 'secondary' },
        ],
      },
    },
    defaultProps: {
      text: 'Click me',
      href: '#',
      variant: 'primary',
    },
  },
  llmInstruction: `
Button: Interactive link styled as a button.
Props: { text: string, href: string, variant: 'primary'|'secondary' }
Example: { "type": "Button", "props": { "text": "Get Started", "href": "/signup", "variant": "primary" } }
`,
});

2. Create Library Entry Point

// src/index.tsx
import { createComponentLibrary } from '@brightsy/component-dev-kit';
import { Button } from './components/Button';
import { Card } from './components/Card';

const library = createComponentLibrary({
  Button,
  Card,
});

// Required exports for Brightsy
export default library.default;
export const componentConfigs = library.componentConfigs;
export const componentLLMInstructions = library.componentLLMInstructions;

3. Configure Vite

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { brightsyComponentLibrary } from '@brightsy/component-dev-kit/vite';

export default defineConfig({
  plugins: [
    react(),
    ...brightsyComponentLibrary({ name: 'my-components' }),
  ],
  build: {
    lib: {
      entry: 'src/index.tsx',
      formats: ['es'],
      fileName: () => 'index.js',
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
        },
      },
    },
  },
});

4. Build and Deploy

# Build the library
npm run build

# Deploy to your CDN or hosting
# Then register with Brightsy via API or MCP

API Reference

Types

BrightsyComponentConfig<Props>

Configuration for a component in the page builder:

interface BrightsyComponentConfig<Props> {
  label: string;           // Display name
  category?: string;       // Category for grouping
  icon?: string;           // Icon (emoji or name)
  fields: { ... };         // Field configurations
  defaultProps: Partial<Props>;
  zones?: { ... };         // For container components
}

FieldConfig

Union of all field types:

• TextFieldConfig - Text input
• TextareaFieldConfig - Multi-line text
• NumberFieldConfig - Number input
• RadioFieldConfig - Radio buttons
• SelectFieldConfig - Dropdown select
• CheckboxFieldConfig - Checkbox
• ArrayFieldConfig - List of items
• ObjectFieldConfig - Nested object
• CustomFieldConfig - Custom render
• ExternalFieldConfig - External data

LLMInstruction

A string describing the component for AI-assisted page building.

Functions

defineComponent(definition)

Define a component with all its parts (component, config, LLM instruction).

createComponentLibrary(components)

Create library exports from component definitions.

createComponentExports(components, configs, instructions?)

Create library exports from separate maps.

mergeLibraries(...libraries)

Merge multiple libraries into one.

generateLLMInstruction(name, config, description?)

Auto-generate LLM instruction from config.

validateLibrary(library)

Validate library structure.

Vite Plugin

brightsyComponentLibrary(options?)

Returns Vite plugins for component library development.

import { brightsyComponentLibrary } from '@brightsy/component-dev-kit/vite';

// Options:
{
  name?: string;      // Library name
  entry?: string;     // Entry file (default: 'src/index.tsx')
  outDir?: string;    // Output dir (default: 'dist')
  sourcemap?: boolean; // Generate sourcemaps (default: true)
  external?: string[];  // Additional externals
  css?: boolean;      // Include CSS (default: true)
}

createBrightsyLibraryConfig(options?)

Returns a complete Vite config object.

Using Theme Variables

Use CSS variables for theming:

const MyComponent = () => (
  <div style={{
    color: 'var(--color-text)',
    backgroundColor: 'var(--color-surface)',
    padding: 'var(--spacing-md)',
    borderRadius: 'var(--border-radius-md)',
    fontFamily: 'var(--font-family-primary)',
  }}>
    Themed content
  </div>
);

Fetching Data

Use the useClient hook from @brightsy/page-builder:

import { useClient } from '@brightsy/page-builder';

export const ProductList = ({ recordType }: { recordType: string }) => {
  const client = useClient();
  const [products, setProducts] = useState([]);

  useEffect(() => {
    client.cda.recordType(recordType).get().then(setProducts);
  }, [client, recordType]);

  return (
    <ul>
      {products.map(p => <li key={p.id}>{p.data.name}</li>)}
    </ul>
  );
};

License

MIT