npm package: @rainbowindex/node
Description: Node.js integration for Rainbow Index
Author: Rainbow Index Contributors
Latest version: 0.1.4
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# @rainbowindex/node

Node.js integration for Rainbow Index. Provides file system access, module resolution, and Lightning CSS optimization.

This package is the foundation for build tool integrations. It handles everything that requires Node.js: reading files,
resolving imports, and optimizing output. Most projects interact with it indirectly through the
[Vite plugin](./../vite), [CLI](./../cli), or [PostCSS plugin](./../postcss). Direct use is helpful when building custom
tooling or integrating with non-standard build systems.

## Installation

```bash
npm install @rainbowindex/node
```

## Usage

### Compile CSS

```typescript
import { compile } from "@rainbowindex/node";

const result = await compile({
    css: `
    @import "rainbowindex";

    @theme {
      --color-primary: oklch(0.6 0.2 250);
    }
  `,
    candidates: ["p-4", "bg-primary", "hover:bg-primary/80"],
    base: process.cwd(),
});

console.log(result.css);
console.log(result.classes); // Classes that were compiled
console.log(result.dependencies); // Resolved @import paths
```

### Optimize CSS

```typescript
import { optimize } from "@rainbowindex/node";

const result = optimize(css, {
    minify: true,
    file: "output.css",
});

console.log(result.code);
console.log(result.map); // Source map (if requested)
```

### Resolve Modules

```typescript
import { resolve } from "@rainbowindex/node";

// Resolve relative path
const file1 = await resolve("./styles.css", { base: __dirname });

// Resolve from node_modules
const file2 = await resolve("rainbowindex/theme.css", { base: __dirname });
```

## API Reference

### `compile(options)`

Compile CSS content with Rainbow Index.

```typescript
interface CompileOptions {
    /** Input CSS content */
    css: string;
    /** List of utility class candidates */
    candidates?: string[];
    /** Base directory for resolving imports */
    base?: string;
    /** Source file being compiled (for source maps) */
    from?: string;
    /** Generate source map */
    sourceMap?: boolean;
    /** Custom CSS resolver */
    customCssResolver?: (id: string, base: string) => Promise<string | null>;
    /** Callback when a dependency is found */
    onDependency?: (path: string) => void;
    /** Process @import statements (default: true) */
    processImports?: boolean;
}

interface CompileResult {
    /** The compiled CSS output */
    css: string;
    /** List of classes that were compiled */
    classes: string[];
    /** The design system used */
    designSystem: DesignSystem;
    /** Source patterns for scanning */
    sources: ScannerSource[];
    /** Root source pattern */
    root: ScannerSource | null;
    /** All resolved dependencies (imported files) */
    dependencies: string[];
    /** Build the CSS from candidates (for incremental builds) */
    build: (candidates: string[]) => string;
}
```

### `optimize(css, options)`

Optimize CSS using Lightning CSS.

```typescript
interface OptimizeOptions {
    /** Minify the output */
    minify?: boolean;
    /** Output filename (for source maps) */
    file?: string;
    /** Generate source map */
    map?: string;
}

interface OptimizeResult {
    /** Optimized CSS */
    code: string;
    /** Source map (if requested) */
    map?: string;
}
```

### `resolve(specifier, options)`

Resolve a module specifier to a file path.

```typescript
interface ResolveOptions {
    /** Base directory for resolution */
    base?: string;
    /** File extensions to try */
    extensions?: string[];
    /** Main fields in package.json */
    mainFields?: string[];
}
```

## @import Resolution

The compile function automatically resolves and inlines `@import` statements:

```css
/* These are resolved and inlined */
@import "rainbowindex";
@import "./components/button.css";
@import "../shared/tokens.css";

/* External URLs are preserved */
@import "https://fonts.googleapis.com/css?family=Roboto";
```

Resolution order:

1. Custom resolver (if provided)
2. Relative paths
3. Node modules (package.json exports/style/main fields)

## Circular Import Detection

The compiler detects and warns about circular imports:

```css
/* a.css */
@import "./b.css";

/* b.css */
@import "./a.css"; /* Warning: Circular import detected */
```

## License

MIT