idelji-builder-component-library v0.3.2

Idelji Builder Component Library

A professional React component library that wraps Ant Design components for use with Builder.io. This library provides a set of reusable components with built-in theming support and seamless Builder.io integration.

Features

• 🎨 Dark/Light theme support with the AdvancedThemeProvider
• 🧩 Pre-configured Ant Design components for Builder.io
• 📝 Form components with built-in validation
• 🔌 Seamless integration with Builder.io visual editor
• 📦 Modern build setup with TypeScript and Sass support
• 🔄 React Context-based Builder.io integration

Installation

npm install idelji-builder-component-library
# or
yarn add idelji-builder-component-library

Peer Dependencies

This library requires the following peer dependencies:

{
  "@ant-design/icons": ">=5.0.0",
  "@builder.io/react": ">=8.0.0",
  "@builder.io/sdk": ">=6.0.0",
  "antd": ">=5.0.0",
  "react": ">=18.0.0",
  "react-dom": ">=18.0.0"
}

Getting Started: Using the Library in Your App

Step 1: Set Up the Theme Provider

Wrap your application with the AdvancedThemeProvider to enable dark/light theme support:

import { AdvancedThemeProvider } from 'idelji-builder-component-library';

function App() {
  return (
    <AdvancedThemeProvider defaultDarkMode={false}>
      <YourApp />
    </AdvancedThemeProvider>
  );
}

Step 2: Use Components in Your React Code

Import and use components directly in your React application:

import { Input, Select, Form } from 'idelji-builder-component-library';

function MyForm() {
  return (
    <Form 
      onFinish={values => console.log(values)}
      layout="vertical"
    >
      <Input
        formItem={{
          name: 'email',
          label: 'Email',
          rules: [{ required: true, message: 'Please enter your email!' }]
        }}
        placeholder="Enter your email"
      />
      
      <Select
        formItem={{
          name: 'country',
          label: 'Country'
        }}
        options={[
          { value: 'us', label: 'United States' },
          { value: 'ca', label: 'Canada' }
        ]}
      />
      
      <button type="submit">Submit</button>
    </Form>
  );
}

Step 3: Set Up Builder.io Integration

There are two recommended ways to integrate Builder.io with your app:

Option 1: Using BuilderProvider (Recommended)

Wrap your application with the BuilderProvider component and pass your API key:

// src/main.jsx or src/index.jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { BuilderProvider } from 'idelji-builder-component-library';

const BUILDER_API_KEY = 'YOUR_BUILDER_API_KEY';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <BuilderProvider apiKey={BUILDER_API_KEY} options={{ useDefaultStyles: true }}>
      <AdvancedThemeProvider defaultDarkMode={false}>
        <App />
      </AdvancedThemeProvider>
    </BuilderProvider>
  </React.StrictMode>
);

Then use Builder components anywhere in your app:

// src/App.jsx
import React from 'react';
import { BuilderEntry, useBuilder } from 'idelji-builder-component-library';

function App() {
  // Access Builder.io state
  const { isInitialized, apiKey } = useBuilder();
  
  return (
    <div className="app">
      {/* Your app content */}
      
      {/* Builder.io content area */}
      <BuilderEntry model="page" />
    </div>
  );
}

Option 2: Dynamic Initialization

Initialize Builder.io dynamically using the useBuilder hook:

// src/App.jsx
import React, { useEffect } from 'react';
import { BuilderProvider, BuilderEntry, useBuilder } from 'idelji-builder-component-library';

function AppContent() {
  const { initBuilder, isInitialized } = useBuilder();
  const BUILDER_API_KEY = 'YOUR_BUILDER_API_KEY';
  
  useEffect(() => {
    if (!isInitialized) {
      initBuilder(BUILDER_API_KEY, { useDefaultStyles: true });
    }
  }, [initBuilder, isInitialized]);
  
  return (
    <div className="app">
      {/* Your app content */}
      
      {/* Builder.io content area */}
      {isInitialized && <BuilderEntry model="page" />}
    </div>
  );
}

function App() {
  return (
    <BuilderProvider>
      <AppContent />
    </BuilderProvider>
  );
}

Step 4: Configure Builder.io to Use Your Components

To make your components available in the Builder.io visual editor:

1. Log in to your Builder.io account
2. Navigate to the Models tab in the left sidebar
3. Select the model you want to use (e.g., "Page")
4. Click on Model Settings (gear icon)
5. Go to the Custom Components tab
6. Click Add Custom Component
7. Enter your development server URL (e.g., http://localhost:5173)
8. Save your changes

For production: 1. Deploy your app with the Builder.io integration 2. Update the URL in Builder.io settings to point to your production URL 3. Make sure your production app loads the component library and initializes Builder.io

Now your components will be available in the Builder.io editor's component panel!

Advanced Usage

Using the useBuilder Hook

The useBuilder hook provides access to the Builder.io context, which includes:

• isInitialized: Boolean indicating if Builder.io has been initialized
• apiKey: The current Builder.io API key
• initBuilder: Function to initialize Builder.io

import { useBuilder } from 'idelji-builder-component-library';

function BuilderStatus() {
  const { isInitialized, apiKey, initBuilder } = useBuilder();
  
  return (
    <div>
      <p>Builder.io Status: {isInitialized ? 'Initialized' : 'Not Initialized'}</p>
      {apiKey && <p>Using API Key: {apiKey.substring(0, 6)}...</p>}
      
      {!isInitialized && (
        <button onClick={() => initBuilder('YOUR_API_KEY', { useDefaultStyles: true })}>
          Initialize Builder
        </button>
      )}
    </div>
  );
}

Using API Key Override

You can override the API key for specific Builder components:

import { BuilderEntry, BuilderPreview } from 'idelji-builder-component-library';

function MultiTenantContent() {
  const TENANT_A_KEY = 'TENANT_A_API_KEY';
  const TENANT_B_KEY = 'TENANT_B_API_KEY';
  
  return (
    <div>
      <h2>Tenant A Content</h2>
      <BuilderEntry model="page" apiKeyOverride={TENANT_A_KEY} />
      
      <h2>Tenant B Content</h2>
      <BuilderPreview model="page" entry="specific-entry" apiKeyOverride={TENANT_B_KEY} />
    </div>
  );
}

Using BuilderPreview for Specific Content

You can use the BuilderPreview component to render specific Builder.io content entries:

import { BuilderPreview } from 'idelji-builder-component-library';

function ContentPreview() {
  return (
    <BuilderPreview
      model="page"
      entry="your-entry-id" // The ID of the specific content entry
      darkMode={false}
    />
  );
}

Using BuilderDebugger for Troubleshooting

The BuilderDebugger component is a development tool that helps diagnose Builder.io integration issues. It displays detailed information about the Builder.io context and SDK state.

import { BuilderDebugger } from 'idelji-builder-component-library';

function App() {
  return (
    <div>
      {/* Your app content */}
      
      {/* Add the debugger during development */}
      {process.env.NODE_ENV === 'development' && (
        <BuilderDebugger apiKey="YOUR_BUILDER_API_KEY" />
      )}
      
      {/* Builder.io content */}
      <BuilderEntry model="page" />
    </div>
  );
}

The BuilderDebugger component:

1. Displays context state: Shows if Builder.io is initialized and what API key is being used
2. Shows SDK state: Displays the current state of the Builder.io SDK
3. Can initialize Builder: If you provide an apiKey prop, it can initialize Builder.io if not already initialized
4. Shows loading state: Indicates when Builder.io is in the process of initializing

This is particularly useful when:

• Diagnosing initialization issues
• Verifying that the correct API key is being used
• Checking if the Builder.io SDK is properly initialized
• Troubleshooting content loading problems

Note: The BuilderDebugger component is intended for development use only and should not be included in production builds.

Extending the Library

Adding a New Component

To add a new component to the library, follow these steps:

1. Create the component file:

// src/components/form/MyNewComponent.tsx
import React from 'react';
import { SomeAntComponent } from 'antd';
import { registerComponent } from '../../utils/builderIntegration';

export interface MyNewComponentProps {
  // Define your props here
  label?: string;
  // ...other props
}

export const MyNewComponent: React.FC<MyNewComponentProps> = ({
  label,
  // ...other props
}) => {
  return (
    <SomeAntComponent>
      {label}
      {/* Your component implementation */}
    </SomeAntComponent>
  );
};

// Register with Builder.io
registerComponent('MyNewComponent', MyNewComponent, {
  description: 'Description of your component',
  inputs: [
    {
      name: 'label',
      type: 'string',
      defaultValue: 'Default Label'
    }
    // Add more input fields as needed
  ]
});

export default MyNewComponent;

2. Export the component in the category index file:

// src/components/form/index.ts
export * from './Input';
export * from './Select';
// ... other exports
export * from './MyNewComponent'; // Add your new component

3. Build the library:

npm run build

Modifying an Existing Component

To modify an existing component:

1. Find the component file in src/components/[category]/
2. Make your changes to the component implementation
3. Update the Builder.io registration if needed
4. Rebuild the library with npm run build

Available Components

The library includes the following component categories:

Form Components

• Input - Text input field with form integration
• Select - Dropdown select with options
• DatePicker - Date selection component
• Checkbox - Checkbox input
• Radio - Radio button input
• Form - Form wrapper with validation

Layout Components

Various layout components for organizing content

Feedback Components

Alerts, modals, and notifications

Navigation Components

Menus, tabs, and breadcrumbs

Builder.io Components

• BuilderComponent - Wrapper component for Builder.io
• BuilderEntry - Entry point for Builder.io content
• BuilderPreview - Component for previewing specific Builder.io content
• BuilderProvider - Context provider for Builder.io integration
• BuilderDebugger - Development tool for diagnosing Builder.io integration issues

Troubleshooting

Components Not Showing in Builder.io

If your components aren't appearing in the Builder.io editor:

1. Check Initialization: Make sure your app is wrapped with BuilderProvider and an API key is provided

2. Verify Registration: All components should have registerComponent() called at the end of their file

3. Check Network: Look for network errors in your browser's developer tools

4. Enable Debug Mode: Add ?builder.debug=true to your Builder.io editor URL

5. Use BuilderDebugger: Add the BuilderDebugger component to your app to diagnose initialization issues:

   import { BuilderDebugger } from 'idelji-builder-component-library';
   
   // Add this to your app during development
   <BuilderDebugger apiKey="YOUR_API_KEY" />

Builder.io Content Not Rendering

If Builder.io content isn't rendering:

1. Check API Key: Verify that you're using the correct API key

2. Check Context: Make sure your app is wrapped with BuilderProvider

3. Check Component Props: Ensure that BuilderEntry or BuilderPreview have the correct props

4. Check Console Errors: Look for any error messages in the browser console

Dark Mode Not Working

If dark mode isn't working properly:

1. Make sure your app is wrapped with AdvancedThemeProvider
2. Check that CSS variables are being properly applied
3. Verify that the useAdvancedTheme hook is used correctly if manually toggling themes

Development

Building the Library

# Install dependencies
npm install

# Build the library
npm run build

The build process will generate:

• CommonJS modules in dist/cjs
• ES modules in dist/esm
• TypeScript declarations in dist/types

License

MIT