tessl/npm-windicss

Next generation utility-first CSS framework with on-demand generation and Tailwind compatibility.

—

Pending

Overview

Eval results

Files

Configuration & Theming

Name: tessl/npm-windicss
Author: tessl

WindiCSS configuration system provides comprehensive theming, plugin management, and processor customization. The configuration follows the same principles as Tailwind CSS but with additional WindiCSS-specific features.

Capabilities

Configuration Interface

Main configuration object for customizing WindiCSS behavior, theme, and plugins.

interface Config {
  /** Theme configuration with colors, spacing, typography, etc. */
  theme?: Theme;
  /** Array of plugins to load */
  plugins?: Plugin[];
  /** Preset configurations to extend */
  presets?: Config[];
  /** Variant configuration per utility */
  variants?: Record<string, string[]> | string[];
  /** Custom shortcuts for frequently used class combinations */
  shortcuts?: Record<string, Shortcut>;
  /** Class name aliases for alternative naming */
  alias?: Record<string, string>;
  /** RegExp patterns to exclude from processing */
  exclude?: RegExp[];
  /** Make all utilities important, or important within a selector */
  important?: boolean | string;
  /** Prefix for all generated classes */
  prefix?: string;
  /** Separator for variants (default: ':') */
  separator?: string;
  /** Attributify mode configuration */
  attributify?: boolean | AttributifyOptions;
  /** Preflight/base styles configuration */
  preflight?: boolean | PreflightOptions;
  /** Core plugins to enable/disable */
  corePlugins?: string[] | Record<string, boolean>;
  /** Utility handlers for custom processing */
  handlers?: Record<string, any>;
}

Theme Configuration

Theme system for colors, spacing, typography, and other design tokens.

interface Theme {
  /** Extend the default theme */
  extend?: Record<string, any>;
  /** Color palette */
  colors?: Record<string, string | Record<string, string>>;
  /** Spacing scale */
  spacing?: Record<string, string>;
  /** Screen breakpoints */
  screens?: Record<string, string>;
  /** Font families */
  fontFamily?: Record<string, string | string[]>;
  /** Font sizes */
  fontSize?: Record<string, FontSize>;
  /** Font weights */
  fontWeight?: Record<string, string>;
  /** Line heights */
  lineHeight?: Record<string, string>;
  /** Letter spacing */
  letterSpacing?: Record<string, string>;
  /** Border radius */
  borderRadius?: Record<string, string>;
  /** Border widths */
  borderWidth?: Record<string, string>;
  /** Box shadows */
  boxShadow?: Record<string, string>;
  /** Z-index values */
  zIndex?: Record<string, string>;
  /** Opacity values */
  opacity?: Record<string, string>;
  /** Animation configurations */
  animation?: Record<string, string>;
  /** Keyframe definitions */
  keyframes?: Record<string, Record<string, Record<string, string>>>;
  /** CSS variables */
  vars?: Record<string, string>;
  [key: string]: any;
}

type FontSize =
  | string
  | [fontSize: string, letterSpacing?: string]
  | [fontSize?: string, options?: { letterSpacing?: string; lineHeight?: string }];

Usage Examples:

import Processor from "windicss";

// Basic theme extension
const processor = new Processor({
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          500: '#3b82f6',
          900: '#1e3a8a'
        },
        secondary: '#10b981'
      },
      spacing: {
        '18': '4.5rem',
        '88': '22rem'
      },
      fontFamily: {
        'custom': ['Inter', 'system-ui', 'sans-serif']
      }
    }
  }
});

// Complete theme override
const customTheme = {
  colors: {
    // Custom color system
    gray: {
      100: '#f5f5f5',
      500: '#737373',
      900: '#171717'
    }
  },
  spacing: {
    // Custom spacing scale
    'xs': '0.5rem',
    'sm': '1rem',
    'md': '1.5rem',
    'lg': '2rem'
  }
};

Plugin Configuration

Plugin system for extending WindiCSS with custom utilities, components, and variants.

type Plugin = PluginOutput | PluginWithOptions<any>;

interface PluginOutput {
  handler: PluginHandler;
  config?: Config;
}

interface PluginWithOptions<T> {
  (options?: T): PluginOutput;
  __isOptionsFunction: true;
  __pluginFunction: (options: T) => PluginHandler;
  __configFunction: (options: T) => Config;
}

type PluginHandler = (utils: PluginUtils) => void;

Usage Examples:

import Processor from "windicss";
import plugin from "windicss/plugin";
import typography from "windicss/plugin/typography";

const processor = new Processor({
  plugins: [
    // Built-in plugin
    typography,
    
    // Custom plugin without options
    plugin(({ addUtilities }) => {
      addUtilities({
        '.btn': {
          padding: '0.5rem 1rem',
          borderRadius: '0.375rem',
          fontWeight: '500'
        }
      });
    }),
    
    // Custom plugin with configuration
    plugin(({ addBase, theme }) => {
      addBase({
        'body': {
          color: theme('colors.gray.900'),
          backgroundColor: theme('colors.gray.50')
        }
      });
    }, {
      theme: {
        extend: {
          colors: {
            brand: '#ff6b6b'
          }
        }
      }
    })
  ]
});

Shortcuts Configuration

Shortcuts allow defining reusable class combinations with custom names.

type Shortcut = string | Record<string, any>;

Usage Examples:

const processor = new Processor({
  shortcuts: {
    // String-based shortcuts
    'btn': 'px-4 py-2 rounded-lg font-medium transition-colors',
    'btn-primary': 'btn bg-blue-500 text-white hover:bg-blue-600',
    'card': 'bg-white shadow-lg rounded-xl p-6',
    
    // Object-based shortcuts with CSS properties
    'flex-center': {
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center'
    },
    'text-gradient': {
      background: 'linear-gradient(45deg, #3b82f6, #10b981)',
      WebkitBackgroundClip: 'text',
      WebkitTextFillColor: 'transparent'
    }
  }
});

// Usage in HTML
// <button class="btn-primary">Click me</button>
// <div class="card flex-center">Content</div>

Alias Configuration

Class name aliases provide alternative names for existing utilities.

interface AliasConfig {
  [aliasName: string]: string;
}

Usage Example:

const processor = new Processor({
  alias: {
    // Alternative naming
    'hstack': 'flex items-center',
    'vstack': 'flex flex-col',
    'center': 'flex items-center justify-center',
    
    // Shortened names
    'bg-primary': 'bg-blue-500',
    'text-muted': 'text-gray-600'
  }
});

Attributify Configuration

Configuration for attributify mode, allowing utility classes as HTML attributes.

interface AttributifyOptions {
  /** Prefix for attributify attributes */
  prefix?: string;
  /** Separator for variant and utility (default: ':') */
  separator?: string;
  /** Array of attributes to disable */
  disable?: string[];
}

Usage Examples:

// Enable attributify mode
const processor = new Processor({
  attributify: true
});

// Attributify with custom options
const processorWithOptions = new Processor({
  attributify: {
    prefix: 'w-',
    separator: '-',
    disable: ['container']
  }
});

// HTML examples:
// <div bg="blue-500" text="white" p="4">Basic attributify</div>
// <div w-bg="red-500" w-text="white">With prefix</div>
// <div bg="hover-blue-600">With variants</div>

Preflight Configuration

Configuration for CSS reset and base styles.

interface PreflightOptions {
  /** Classes to always include in preflight */
  safelist?: string | string[];
  /** Classes to exclude from preflight */
  blocklist?: string | string[];
  /** Tag name aliases for preflight */
  alias?: Record<string, string>;
  /** Enable all preflight features */
  enableAll?: boolean;
}

Usage Example:

const processor = new Processor({
  preflight: {
    safelist: ['container', 'btn', 'card'],
    blocklist: ['debug-*'],
    alias: {
      'hstack': 'div',
      'vstack': 'div'
    },
    enableAll: false
  }
});

Variant Configuration

Configuration for responsive, state, and custom variants.

type VariantConfig = Record<string, string[]> | string[];

Usage Examples:

// Global variants (apply to all utilities)
const processor = new Processor({
  variants: ['responsive', 'hover', 'focus', 'dark']
});

// Per-utility variants
const processorPerUtility = new Processor({
  variants: {
    backgroundColor: ['responsive', 'hover', 'focus', 'dark'],
    textColor: ['responsive', 'hover', 'focus'],
    borderWidth: ['responsive']
  }
});

Core Plugins Configuration

Enable or disable built-in WindiCSS utilities.

type CorePluginsConfig = string[] | Record<string, boolean>;

Usage Examples:

// Array format - only enable specific plugins
const processor = new Processor({
  corePlugins: [
    'margin',
    'padding', 
    'backgroundColor',
    'textColor'
  ]
});

// Object format - fine-grained control
const processorObject = new Processor({
  corePlugins: {
    // Enable
    margin: true,
    padding: true,
    backgroundColor: true,
    
    // Disable
    float: false,
    clear: false,
    skew: false
  }
});

Default Configurations

Access to built-in default configurations.

/**
 * Default WindiCSS configuration
 */
declare const defaultConfig: Config;

/**
 * Default WindiCSS theme
 */
declare const defaultTheme: Theme;

/**
 * Default color palette
 */
declare const colors: Record<string, string | Record<string, string>>;

Usage Example:

import { defaultConfig, defaultTheme, colors } from "windicss";

// Extend default configuration
const processor = new Processor({
  ...defaultConfig,
  theme: {
    ...defaultTheme,
    extend: {
      colors: {
        ...colors,
        brand: '#ff6b6b'
      }
    }
  }
});

Configuration Utilities

Helper functions for working with configurations.

/**
 * Type-safe configuration definition helper
 * @param config - Configuration object
 * @returns Same configuration with type safety
 */
function defineConfig(config: Config): Config;

Usage Example:

import { defineConfig } from "windicss/helpers";

export default defineConfig({
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6'
      }
    }
  },
  plugins: [
    // plugins here
  ]
});

Install with Tessl CLI