@euis/wasm

WebAssembly bindings for the Euis (Euis) compiler. This package provides a high-performance CSS compiler that runs in any JavaScript environment - Node.js, browsers, and cloud-based IDEs like Lovable, StackBlitz, and CodeSandbox.

Installation

npm install @euis/wasm

Or with yarn:

yarn add @euis/wasm

Or with pnpm:

pnpm add @euis/wasm

Quick Start

import { EuisCompiler } from '@euis/wasm';

// Create a compiler instance
const compiler = new EuisCompiler();

// Compile Euis to CSS
const source = `
$colors.primary: #3b82f6;

.button {
  background: $colors.primary;
  padding: 12px 24px;
  border-radius: 8px;
}
`;

const config = JSON.stringify({
  minify: false,
  source_maps: 'Inline',
  tree_shaking: false,
});

const result = compiler.compile(source, config);

console.log(result.css);
// Output: .button { background: #3b82f6; padding: 12px 24px; border-radius: 8px; }

if (result.errors.length > 0) {
  console.error('Compilation errors:', result.errors);
}

API Reference

EuisCompiler

The main compiler class that provides methods for compiling, parsing, formatting, and validating Euis code.

Constructor

const compiler = new EuisCompiler();

Creates a new compiler instance. The instance can be reused for multiple compilations.

compile(source: string, config_json: string): CompileResult

Compiles Euis source code to CSS.

Parameters:

• source (string): Euis source code to compile
• config_json (string): JSON string containing compiler configuration

Returns: CompileResult object with the following properties:

• css (string): Compiled CSS output
• js (string | undefined): Optional JavaScript runtime code (when using Typed OM)
• source_map (string | undefined): Source map as JSON string
• errors (Array): Array of compilation errors
• warnings (Array): Array of compilation warnings
• stats (object): Compilation statistics

Example:

const source = `
$spacing.md: 16px;

.card {
  padding: $spacing.md;
  margin: calc($spacing.md * 2);
}
`;

const config = JSON.stringify({
  minify: true,
  source_maps: 'Inline',
  deduplicate: true,
  tokens: {
    spacing: { md: '16px' }
  }
});

const result = compiler.compile(source, config);

if (result.errors.length === 0) {
  console.log('Compiled CSS:', result.css);
  console.log('Stats:', result.stats);
} else {
  result.errors.forEach(error => {
    console.error(`Error at ${error.line}:${error.column}: ${error.message}`);
  });
}

parse(source: string): any

Parses Euis source code into an Abstract Syntax Tree (AST).

Parameters:

• source (string): Euis source code to parse

Returns: AST as a JavaScript object, or an object with parse errors

Example:

const source = `
.button {
  color: blue;
}
`;

const ast = compiler.parse(source);
console.log(JSON.stringify(ast, null, 2));

format(source: string): string

Formats Euis source code with consistent style.

Parameters:

• source (string): Euis source code to format

Returns: Formatted Euis source code as a string

Example:

const unformatted = `.button{color:blue;padding:8px;}`;
const formatted = compiler.format(unformatted);

console.log(formatted);
// Output:
// .button {
//   color: blue;
//   padding: 8px;
// }

validate(source: string, config_json: string): any

Validates Euis source code without performing full compilation. Useful for linting and editor integrations.

Parameters:

• source (string): Euis source code to validate
• config_json (string): JSON string containing compiler configuration

Returns: Object containing validation errors and warnings

Example:

const source = `
.button {
  color: $colors.undefined;
  invalid-property: value;
}
`;

const config = JSON.stringify({
  tokens: {
    colors: { primary: '#3b82f6' }
  }
});

const result = compiler.validate(source, config);

if (result.errors && result.errors.length > 0) {
  result.errors.forEach(error => {
    console.error(`Validation error: ${error.message}`);
  });
}

compile_w3c_tokens(json_content: string, target: string): any

Compiles W3C Design Tokens JSON to platform-specific code.

Parameters:

• json_content (string): W3C Design Tokens JSON content
• target (string): Target platform - one of: CSS, IOS, Android, AndroidKotlin, Flutter, TypeScript, Docs

Returns: Object containing generated code files for the target platform

Example:

const tokens = JSON.stringify({
  colors: {
    primary: {
      $value: '#3b82f6',
      $type: 'color'
    }
  },
  spacing: {
    md: {
      $value: '16px',
      $type: 'dimension'
    }
  }
});

const result = compiler.compile_w3c_tokens(tokens, 'CSS');
console.log(result);
// Output: CSS custom properties generated from tokens

Configuration Options

The config_json parameter accepts a JSON string with the following options:

{
  // Enable CSS minification
  minify?: boolean;  // default: false
  
  // Enable tree-shaking (remove unused styles)
  tree_shaking?: boolean;  // default: false
  
  // Generate Typed OM JavaScript runtime
  typed_om?: boolean;  // default: false
  
  // Source map generation: 'Inline', 'External', or 'Disabled'
  source_maps?: string;  // default: 'Inline'
  
  // Enable deduplication of identical rules
  deduplicate?: boolean;  // default: true
  
  // List of class names that are used (for tree-shaking)
  used_classes?: string[];  // default: []
  
  // Paths to scan for used classes
  content_paths?: string[];  // default: []
  
  // Class names to always keep (never tree-shake)
  safelist?: string[];  // default: []
  
  // Design tokens
  tokens?: {
    colors?: Record<string, string>;
    spacing?: Record<string, string>;
    typography?: Record<string, string>;
    breakpoints?: Record<string, string>;
  };
}

Example with all options:

const config = JSON.stringify({
  minify: true,
  tree_shaking: true,
  typed_om: false,
  source_maps: 'Inline',
  deduplicate: true,
  used_classes: ['button', 'card', 'header'],
  safelist: ['active', 'disabled'],
  tokens: {
    colors: {
      primary: '#3b82f6',
      secondary: '#8b5cf6'
    },
    spacing: {
      sm: '8px',
      md: '16px',
      lg: '24px'
    }
  }
});

const result = compiler.compile(source, config);

Error Handling

All compilation errors include detailed information:

const result = compiler.compile(source, config);

if (result.errors.length > 0) {
  result.errors.forEach(error => {
    console.error({
      message: error.message,
      line: error.line,        // Line number (1-indexed)
      column: error.column,    // Column number (1-indexed)
      severity: error.severity // 'error' or 'warning'
    });
  });
}

Browser Compatibility

The Euis WASM compiler works in all modern browsers and JavaScript environments that support WebAssembly:

Browsers

| Browser | Minimum Version | Release Date | |---------|----------------|--------------| | Chrome | 57 | March 2017 | | Firefox | 52 | March 2017 | | Safari | 11 | September 2017 | | Edge | 16 | September 2017 |

Node.js

• Node.js 16.x or higher
• Works in both CommonJS and ES modules

Cloud Environments

Fully compatible with browser-based development environments:

• ✅ Lovable (formerly GPT Engineer)
• ✅ StackBlitz
• ✅ CodeSandbox
• ✅ Replit
• ✅ GitHub Codespaces
• ✅ Gitpod

Build Tools

Works seamlessly with modern JavaScript bundlers:

• ✅ Vite (recommended)
• ✅ Webpack 5+
• ✅ Rollup
• ✅ esbuild
• ✅ Parcel 2+

Usage with Vite

For Vite projects, use the official plugin instead of using this package directly:

npm install vite-plugin-euis

// vite.config.js
import { defineConfig } from 'vite';
import euis from 'vite-plugin-euis';

export default defineConfig({
  plugins: [
    euis({
      minify: true,
      sourceMaps: true,
    })
  ]
});

The plugin automatically handles WASM initialization and provides HMR support.

Performance

The WASM compiler is highly optimized:

• Compilation speed: 1-5ms for typical files
• WASM initialization: 10-50ms (one-time cost)
• Bundle size: ~150KB compressed
• Memory usage: Minimal, with automatic cleanup

TypeScript Support

This package includes TypeScript definitions generated by wasm-bindgen:

import { EuisCompiler } from '@euis/wasm';

const compiler: EuisCompiler = new EuisCompiler();

interface CompileResult {
  css: string;
  js?: string;
  source_map?: string;
  errors: CompilerError[];
  warnings: CompilerError[];
  stats: CompilationStats;
}

interface CompilerError {
  message: string;
  line?: number;
  column?: number;
  severity: 'error' | 'warning';
}

Troubleshooting

WASM initialization fails

If you see errors about WASM initialization:

1. Ensure your bundler supports WASM imports (Vite, Webpack 5+, Rollup do by default)
2. Check that you're using Node.js 16 or higher
3. In cloud environments, verify that node_modules is properly synced

Module not found

If you see Cannot find module '@euis/wasm':

1. Run npm install @euis/wasm to install the package
2. Clear your bundler cache and restart the dev server
3. Check that the package is listed in your package.json dependencies

Performance issues

If compilation is slow:

1. Reuse the same EuisCompiler instance (don't create new instances for each compilation)
2. Enable caching in your build tool
3. Consider using tree-shaking to reduce the amount of CSS processed

Examples

Basic Compilation

import { EuisCompiler } from '@euis/wasm';

const compiler = new EuisCompiler();
const source = `.button { color: blue; }`;
const config = JSON.stringify({ minify: false });

const result = compiler.compile(source, config);
console.log(result.css);

With Design Tokens

const source = `
.button {
  background: $colors.primary;
  padding: $spacing.md;
}
`;

const config = JSON.stringify({
  tokens: {
    colors: { primary: '#3b82f6' },
    spacing: { md: '16px' }
  }
});

const result = compiler.compile(source, config);

Tree-Shaking

const source = `
.button { color: blue; }
.card { padding: 16px; }
.unused { display: none; }
`;

const config = JSON.stringify({
  tree_shaking: true,
  used_classes: ['button', 'card']
});

const result = compiler.compile(source, config);
// Output only includes .button and .card styles

Format Code

const unformatted = `.button{color:blue;padding:8px;}`;
const formatted = compiler.format(unformatted);
console.log(formatted);

License

MIT

Links

• GitHub Repository
• Documentation
• Vite Plugin
• Report Issues