BaroCSS API Reference

BaroCSS provides a comprehensive API for real-time CSS generation and utility-first styling. This section covers all the core APIs, runtime systems, and configuration options.

🚀 Quick Start

import { BrowserRuntime } from '@barocss/browser';
import { createContext } from '@barocss/kit';

// Initialize runtime
const runtime = new BrowserRuntime({
  config: {
    theme: {
      extend: {
        colors: {
          brand: '#3b82f6'
        }
      }
    }
  }
});

// Start watching DOM changes
runtime.observe(document.body, { scan: true });

📚 API Learning Path

Recommended Reading Order

Follow this path to understand BaroCSS APIs from basic to advanced concepts.

🎯 Step 1: Getting Started

Essential APIs for basic usage

• Context API - Theme and configuration management
• Configuration - Theme and behavior customization
• Browser Runtime - Browser-specific DOM integration
• Server Runtime - Server-side CSS generation

🔧 Step 2: Core Engine

Understanding how CSS is generated

• Parser API - Class name parsing and tokenization
• Engine API - CSS generation and AST processing

🛠️ Step 3: Customization

Creating custom utilities and modifiers

• Static Utility API - Creating fixed utilities
• Functional Utility API - Creating dynamic utilities
• Static Modifier API - Creating fixed modifiers
• Functional Modifier API - Creating dynamic modifiers
• Custom Utilities - Custom utilities and variants

🔬 Step 4: Advanced Concepts

Deep dive into internal mechanisms

• AST Processing API - Advanced AST manipulation functions

📖 Quick Reference

By Use Case

Browser Development

• Browser Runtime - DOM integration
• Context API - Configuration
• Static Utility API - Custom utilities

Server-Side Rendering

• Server Runtime - CSS generation
• Engine API - Core processing
• Configuration - Theme setup

Custom Development

• Static Utility API - Fixed utilities
• Functional Utility API - Dynamic utilities
• Static Modifier API - Fixed modifiers
• Functional Modifier API - Dynamic modifiers

Advanced Usage

• Parser API - Class parsing details
• AST Processing API - AST manipulation
• Engine API - Core functions

🎯 Main Entry Points

Browser Usage

// CDN
import { BrowserRuntime } from 'https://unpkg.com/@barocss/browser/dist/cdn/barocss.js';

// NPM
import { BrowserRuntime } from '@barocss/browser';

Server Usage

import { ServerRuntime } from '@barocss/server';
import { createContext, generateCss } from '@barocss/kit';

Core Usage

import { 
  createContext, 
  parseClassToAst, 
  generateCss,
  IncrementalParser 
} from '@barocss/kit';

🔧 Key Concepts

Context

The central configuration and theme management system that provides access to theme values and configuration options.

Engine

The core CSS generation system that parses class names, builds ASTs, and converts them to CSS rules.

Runtime

Environment-specific implementations that handle CSS injection (browser) or generation (server).

Custom Utilities

Global registry system for adding custom utilities, variants, and theme extensions.

📖 API Categories

Core Functions

• createContext(config) - Create a BaroCSS context
• parseClassToAst(className, ctx) - Parse class to AST
• generateCss(classList, ctx) - Generate CSS from classes
• IncrementalParser - Efficient class processing

Runtime Classes

• BrowserRuntime - Browser DOM integration
• ServerRuntime - Server-side processing
• ChangeDetector - DOM change monitoring

Custom Utilities

• staticUtility() - Register static utilities with fixed CSS
• functionalUtility() - Register dynamic utilities with value processing

Custom Modifiers

• staticModifier() - Register static modifiers with fixed selectors
• functionalModifier() - Register dynamic modifiers with pattern matching

Configuration

• Config interface - Configuration options
• Theme interface - Theme structure
• Theme extension and customization

🎨 Usage Patterns

Basic Styling

const runtime = new BrowserRuntime();
runtime.addClass('bg-blue-500 text-white p-4');

Custom Theme

const ctx = createContext({
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#eff6ff',
          500: '#3b82f6',
          900: '#1e3a8a'
        }
      }
    }
  }
});

Custom Utilities

import { staticUtility, functionalUtility } from '@barocss/kit';
import { decl } from '@barocss/kit';

// Register static utility
staticUtility('custom-bg', [
  decl('background-color', 'var(--custom-color)'),
  decl('border-radius', '8px')
]);

// Register functional utility
functionalUtility({
  name: 'custom-text',
  prop: 'color',
  handle: (value) => [decl('color', value)]
});

---

Ready to dive deeper? Start with the Context API to understand how BaroCSS manages themes and configuration.