tessl/npm-unocss

The instant on-demand Atomic CSS engine for generating styles dynamically without parsing, AST, or scanning.

—

Pending

Overview

Eval results

Files

Source Code Transformers

Name: tessl/npm-unocss
Author: tessl

Source code transformers process source code to enable advanced UnoCSS features and syntax. They analyze and transform code before CSS generation, enabling features like CSS directives, variant groups, and specialized syntax patterns.

Capabilities

Directives Transformer

Enables CSS directives like @apply, @screen, and @theme in CSS files.

/**
 * CSS directives transformer for @apply, @screen, @theme directives
 * @param options - Configuration options
 * @returns Source code transformer
 */
function transformerDirectives(options?: TransformerDirectivesOptions): SourceCodeTransformer;

interface TransformerDirectivesOptions {
  /** Enable @apply directive */
  applyVariable?: string[];
  /** Custom CSS directives */
  customDirectives?: Record<string, (utils: any) => string>;
  /** Enable @screen directive */
  screen?: boolean;
  /** Enable @theme directive */
  theme?: boolean;
  /** Enforce theme function usage */
  enforceVarType?: boolean;
  /** Variables to throw warnings for */
  throwOnMissing?: boolean;
}

Usage Examples:

import { defineConfig, transformerDirectives } from "unocss";

export default defineConfig({
  transformers: [
    transformerDirectives({
      applyVariable: ['--at-apply', '--uno-apply', '--uno'],
      screen: true,
      theme: true
    })
  ]
});

/* Input CSS with directives */
.btn {
  @apply py-2 px-4 font-semibold rounded-lg shadow-md;
}

.container {
  @screen sm {
    max-width: 640px;
  }
}

.text-primary {
  color: theme('colors.blue.500');
}

Variant Group Transformer

Enables variant group syntax for grouping utilities with common variants.

/**
 * Variant group transformer for hover:(bg-red text-white) syntax
 * @param options - Configuration options
 * @returns Source code transformer
 */
function transformerVariantGroup(options?: TransformerVariantGroupOptions): SourceCodeTransformer;

interface TransformerVariantGroupOptions {
  /** Separators for variant groups */
  separators?: string[];
  /** Maximum parsing depth */
  depth?: number;
  /** Transform only specific files */
  include?: string | RegExp | (string | RegExp)[];
  /** Exclude specific files */
  exclude?: string | RegExp | (string | RegExp)[];
}

Usage Examples:

import { defineConfig, transformerVariantGroup } from "unocss";

export default defineConfig({
  transformers: [
    transformerVariantGroup({
      separators: [':', '-'],
      depth: 5
    })
  ]
});

<!-- Input HTML with variant groups -->
<div class="hover:(bg-blue-500 text-white) focus:(ring-2 ring-blue-300)">
  Hover and focus effects
</div>

<!-- Transforms to -->
<div class="hover:bg-blue-500 hover:text-white focus:ring-2 focus:ring-blue-300">
  Hover and focus effects
</div>

Attributify JSX Transformer

Enables attributify mode in JSX/TSX files.

/**
 * Attributify JSX transformer for React/Vue JSX
 * @param options - Configuration options
 * @returns Source code transformer
 */
function transformerAttributifyJsx(options?: AttributifyJsxOptions): SourceCodeTransformer;

interface AttributifyJsxOptions {
  /** Blocklist of attributes to ignore */
  blocklist?: (string | RegExp)[];
  /** Include only specific attributes */
  include?: (string | RegExp)[];
  /** Enable for specific frameworks */
  frameworks?: ('react' | 'vue' | 'svelte')[];
}

Usage Examples:

import { defineConfig, transformerAttributifyJsx } from "unocss";

export default defineConfig({
  transformers: [
    transformerAttributifyJsx({
      frameworks: ['react', 'vue']
    })
  ]
});

// Input JSX with attributify syntax
function Button() {
  return (
    <button
      bg="blue-500 hover:blue-600"
      text="white"
      p="x-4 y-2"
      rounded="md"
    >
      Click me
    </button>
  );
}

Compile Class Transformer

Compiles utility classes at build time for performance optimization.

/**
 * Class compilation transformer for build-time optimization
 * @param options - Configuration options
 * @returns Source code transformer
 */
function transformerCompileClass(options?: CompileClassOptions): SourceCodeTransformer;

interface CompileClassOptions {
  /** Class compilation trigger */
  trigger?: string | RegExp;
  /** Prefix for compiled classes */
  classPrefix?: string;
  /** Enable hash generation */
  hashFn?: (str: string) => string;
  /** Keep original classes */
  keepOriginal?: boolean;
}

Usage Examples:

import { defineConfig, transformerCompileClass } from "unocss";

export default defineConfig({
  transformers: [
    transformerCompileClass({
      trigger: ':uno:',
      classPrefix: 'uno-'
    })
  ]
});

<!-- Input HTML with compile trigger -->
<div class=":uno: text-center py-4 px-8 bg-blue-500 text-white rounded-lg shadow-md">
  Compiled utilities
</div>

<!-- Transforms to optimized single class -->
<div class="uno-abc123">
  Compiled utilities
</div>

Transformer Interface

SourceCodeTransformer Interface

interface SourceCodeTransformer {
  /** Transformer name */
  name: string;
  /** Enforce transformer order */
  enforce?: 'pre' | 'post';
  /** Transform function */
  transform: (
    code: string,
    id: string,
    context: TransformContext
  ) => Awaitable<string | TransformResult | void>;
  /** Async transform function */
  transformAsync?: (
    code: string,
    id: string,
    context: TransformContext
  ) => Promise<string | TransformResult | void>;
}

interface TransformContext {
  /** UnoCSS generator instance */
  uno: UnoGenerator;
  /** Extracted tokens */
  tokens: Set<string>;
  /** Invalidate callback */
  invalidate?: () => void;
}

interface TransformResult {
  /** Transformed code */
  code: string;
  /** Source map */
  map?: any;
  /** Additional tokens to extract */
  tokens?: Set<string>;
}

Multiple Transformer Usage

Combining Transformers

import { 
  defineConfig, 
  transformerDirectives, 
  transformerVariantGroup,
  transformerAttributifyJsx,
  transformerCompileClass
} from "unocss";

export default defineConfig({
  transformers: [
    // Order matters - pre-transformers first
    transformerVariantGroup(),
    transformerAttributifyJsx(),
    transformerDirectives(),
    transformerCompileClass()
  ]
});

Framework-Specific Setups

// React/Next.js setup
export default defineConfig({
  transformers: [
    transformerVariantGroup(),
    transformerAttributifyJsx({
      frameworks: ['react']
    }),
    transformerDirectives()
  ]
});

// Vue setup
export default defineConfig({
  transformers: [
    transformerVariantGroup(),
    transformerAttributifyJsx({
      frameworks: ['vue']
    }),
    transformerDirectives()
  ]
});

// CSS-only setup
export default defineConfig({
  transformers: [
    transformerDirectives({
      applyVariable: ['--uno-apply'],
      screen: true,
      theme: true
    })
  ]
});

Common Use Cases

CSS Framework Migration

// Transformers for migrating from Tailwind
export default defineConfig({
  transformers: [
    transformerDirectives(), // @apply support
    transformerVariantGroup() // Variant grouping
  ]
});

Component Library Development

// Transformers for building component libraries
export default defineConfig({
  transformers: [
    transformerCompileClass({
      trigger: /uno-compile:/,
      keepOriginal: false
    }),
    transformerAttributifyJsx()
  ]
});

Performance Optimization

// Transformers for production optimization
export default defineConfig({
  transformers: [
    transformerCompileClass({
      trigger: ':compile:',
      classPrefix: 'c-'
    })
  ]
});

Install with Tessl CLI