CLI Components

Codella provides three pre-built components that you can scaffold into your projects.

Installation

Prerequisites

• Node.js 16+ installed
• An existing React project (or create one with create-react-app or vite)

Install the CLI

# Using npm
npm install -D @codella-software/cli

# Using pnpm
pnpm add -D @codella-software/cli

# Using yarn
yarn add --dev @codella-software/cli

Install Core Dependencies

# Install the core utilities
npm install @codella-software/utils

# If using React components, also install React integration
npm install @codella-software/react

Using the CLI

# List available components
codella list

# Add a component to your project
codella add <component-name>

# Available components: dynamic-table, form-renderer, private-outlet, table-filters, rich-content

PrivateOutlet

A React Router component that protects routes by checking authentication state and managing login redirects.

Features:

• ✅ Auth state checking before rendering protected routes
• ✅ Loading state display during authentication verification
• ✅ Automatic redirects for unauthenticated users
• ✅ Intended path preservation via localStorage
• ✅ Support for custom loader components
• ✅ Works with Firebase, Auth0, NextAuth, or any auth provider

Usage:

codella add private-outlet

import { PrivateOutlet } from '@/components/codella/private-outlet';
import { useAuth } from '@/hooks/useAuth';
import { Routes, Route } from 'react-router';

export function AppRoutes() {
  const { user, isLoading } = useAuth();

  return (
    <Routes>
      {/* Public route */}
      <Route path="/login" element={<LoginPage />} />
      
      {/* Protected routes */}
      <Route
        element={
          <PrivateOutlet
            isAuthenticated={!!user}
            isLoading={isLoading}
            loginPath="/login"
          />
        }
      >
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/settings" element={<Settings />} />
      </Route>
    </Routes>
  );
}

DynamicTable

A full-featured table component with sorting, filtering, pagination, and row selection.

Features:

• ✅ Column sorting (ascending/descending)
• ✅ Column filtering with operators
• ✅ Pagination with customizable page size
• ✅ Row selection with checkboxes
• ✅ Empty and loading states
• ✅ Responsive design with Tailwind CSS

Usage:

codella add dynamic-table

import { DynamicTable } from './components/DynamicTable';
import { useTableService } from '@codella-software/react';

export function DataTable() {
  const table = useTableService({
    columns: [
      { key: 'id', label: 'ID' },
      { key: 'name', label: 'Name' },
    ],
    data: [...],
    sortable: true,
    pagination: { pageSize: 10 },
  });

  return <DynamicTable {...table} />;
}

FormRenderer

A multi-step form component with validation and field support.

Features:

• ✅ Multi-step form support
• ✅ Field validation with error messages
• ✅ Conditional fields based on dependencies
• ✅ Multiple field types
• ✅ Submit handling

Usage:

codella add form-renderer

import { FormRenderer } from './components/FormRenderer';
import { useFormBuilder } from '@codella-software/react';

export function SignupForm() {
  const form = useFormBuilder({
    fields: [
      { name: 'email', type: 'email', label: 'Email' },
      { name: 'password', type: 'password', label: 'Password' },
    ],
  });

  return <FormRenderer {...form} onSubmit={handleSubmit} />;
}

TableFilters

An advanced filtering UI for tables with sort controls.

Features:

• ✅ Multiple filter types (text, date, number, select)
• ✅ Filter operators
• ✅ Sort direction toggle
• ✅ Active filter display
• ✅ Clear filters button

Usage:

codella add table-filters

import { TableFilters } from './components/TableFilters';

export function FilterPage() {
  const table = useTableService({ ... });
  
  return (
    <>
      <TableFilters {...table} />
      <DynamicTable {...table} />
    </>
  );
}

RichContent

A full-featured rich text editor with formatting toolbar, undo/redo, support for headings, lists, images, and more. Includes both editor and form field integration components.

Features:

• ✅ Text formatting (bold, italic, underline, strikethrough, code)
• ✅ Block types (paragraphs, headings, lists, images, blockquotes, code blocks)
• ✅ Undo/Redo with configurable history
• ✅ Image upload support
• ✅ FormBuilder field integration (CustomFieldProps compatible)
• ✅ HTML/JSON/PlainText serialization
• ✅ Keyboard shortcuts support
• ✅ Extensible middleware hooks
• ✅ Available in base and shadcn/ui variants

Usage:

codella add rich-content

The scaffolding creates:

• rich-content/rich-content-editor.tsx - Main editor component with formatting toolbar
• rich-content/rich-content-toolbar.tsx - Toolbar with formatting buttons
• rich-content/rich-content.tsx - Complete editor composition
• form-builder/fields/RichContentField.tsx - CustomFieldProps-compatible form field for use in forms
• Example forms showing integration (blog-post-form.tsx or email-template-form.tsx depending on variant)

Basic Editor Example:

import { RichContent } from '@/components/codella/rich-content';
import { useRef } from 'react';

export function MyEditor() {
  const editorRef = useRef<HTMLDivElement>(null);

  return (
    <div>
      <h1>Write Your Post</h1>
      <RichContent editorRef={editorRef} />
    </div>
  );
}

Form Field Example:

import { FormBuilder } from '@codella-software/utils';
import { RichContentField } from '@/components/codella/form-builder/fields';

const form = new FormBuilder({
  fields: [
    {
      name: 'title',
      type: 'text',
      label: 'Title',
    },
    {
      name: 'content',
      type: 'custom',
      label: 'Content',
      component: RichContentField, // Use rich content in forms
    },
  ],
});

With Custom Config:

import { RichContent } from '@/components/codella/rich-content';
import { useRef } from 'react';

export function ConfiguredEditor() {
  const editorRef = useRef<HTMLDivElement>(null);

  return (
    <RichContent
      editorRef={editorRef}
      config={{
        maxHistorySteps: 100,
        allowedMarks: ['bold', 'italic', 'underline'],
        allowedBlocks: ['paragraph', 'heading', 'list', 'image'],
        imageUploadHandler: async (file) => {
          const formData = new FormData();
          formData.append('file', file);
          const res = await fetch('/api/upload', {
            method: 'POST',
            body: formData,
          });
          const data = await res.json();
          return { url: data.url };
        },
      }}
    />
  );
}

Variants:

The CLI offers two design variants:

Base Variant - Minimal styling with lucide icons

codella add rich-content --variant base

Shadcn/ui Variant - Modern design with shadcn/ui components

codella add rich-content --variant shadcn

See the Rich Content Editor documentation for complete API reference, middleware hooks, serializers, and advanced examples.

Configuration

The CLI scaffolds components based on your codella.config.json file. This configuration controls component generation and output.

Creating Configuration

First, initialize your project with:

codella init

This creates a codella.config.json file in your project root:

{
  "ui": "shadcn",
  "typescript": true,
  "outputDir": "@/components/codella",
  "aliases": {
    "@": "./src"
  },
  "theme": {
    "primary": "#3b82f6",
    "secondary": "#6b7280"
  }
}

Configuration Options

ui - UI Framework

Determines which component variant is scaffolded.

Supported values:

• "shadcn" - shadcn/ui styled components (default)
• "mui" - Material-UI components
• "antd" - Ant Design components
• "base" - Plain HTML with Tailwind CSS

{
  "ui": "shadcn"
}

typescript - TypeScript Support

Generates .tsx files with full type safety or .jsx files.

{
  "typescript": true
}

outputDir - Component Output Directory

Where scaffolded components are placed in your project.

{
  "outputDir": "@/components/codella"
}

Use path aliases for cleaner imports, or specify relative paths:

{
  "outputDir": "src/features/ui-components"
}

aliases - Path Aliases

Maps import aliases used in your project (from tsconfig.json or custom).

{
  "aliases": {
    "@": "./src",
    "components": "./src/components",
    "utils": "./src/lib/utils",
    "hooks": "./src/hooks"
  }
}

These aliases control how components import dependencies. For example, with the above aliases, a component might import:

import { useTableService } from '@codella-software/react'
import { DynamicTable } from '@/components/codella/dynamic-table'
import { CustomButton } from '@/components/ui/button'
import { formatDate } from '@/utils/date'

theme (optional) - Tailwind Colors

Tailwind CSS theme colors for component styling. Auto-extracted from your tailwind.config.js during initialization.

{
  "theme": {
    "primary": "#3b82f6",
    "secondary": "#6b7280",
    "accent": "#a855f7",
    "background": "#ffffff",
    "foreground": "#000000",
    "muted": "#e5e7eb",
    "muted-foreground": "#6b7280"
  }
}

Components use these colors for styling. Update the theme to match your brand colors.

Modifying Configuration

After creating codella.config.json, you can edit it manually:

Change the UI framework:

{
  "ui": "mui"
}

Add new aliases:

{
  "aliases": {
    "types": "@/types",
    "constants": "@/constants"
  }
}

Update output directory:

{
  "outputDir": "@/features/ui"
}

Update theme colors:

{
  "theme": {
    "primary": "#ff0000",
    "secondary": "#00ff00"
  }
}

After editing, new components scaffolded with codella add will use the updated configuration.

Configuration Examples

Next.js with shadcn/ui:

{
  "ui": "shadcn",
  "typescript": true,
  "outputDir": "@/components/codella",
  "aliases": {
    "@/*": "./*"
  }
}

Vite + React with Material-UI:

{
  "ui": "mui",
  "typescript": true,
  "outputDir": "src/components/codella",
  "aliases": {
    "@": "./src"
  }
}

Create React App with Ant Design:

{
  "ui": "antd",
  "typescript": true,
  "outputDir": "src/components",
  "aliases": {
    "@": "./src"
  }
}

Auto-Detection

During codella init, the CLI automatically detects:

1. UI Framework - Checks package.json for framework dependencies
2. TypeScript - Looks for tsconfig.json
3. Path Aliases - Reads from tsconfig.json or jsconfig.json
4. Theme Colors - Extracts from tailwind.config.js if available
5. Output Directory - Uses sensible defaults based on detected aliases

To use auto-detected values without prompts:

codella init --yes

To customize, use interactive mode:

codella init

Customization

All components are single-file, fully customizable. You own the code completely.

To customize, simply edit the component file in your output directory (configured in codella.config.json) and make your changes. Use Tailwind CSS classes or add your own styles as needed.