vite-plugin-uxdsl

The official Vite plugin for UXDSL — seamlessly integrating .uxdsl files into your Vite projects.

Visit the Official Documentation & Playground

Overview

vite-plugin-uxdsl provides a fast and efficient way to process .uxdsl files within your Vite development and build workflows. It acts as a custom loader, transforming your UXDSL syntax into standard CSS, allowing Vite to bundle it effectively. This is the recommended and most actively supported integration for UXDSL in modern frontend projects.

Features

• Zero-Config (Optional): Works out of the box with minimal setup for common use cases.
• Hot Module Replacement (HMR): Enjoy instant CSS updates without page refreshes during development.
• Optimized Builds: Integrates smoothly with Vite's highly optimized production builds.
• Full UXDSL Feature Support: Leverage all UXDSL features like theme functions, responsive utilities, and smart mixins.

Installation

npm install vite-plugin-uxdsl uxdsl-core --save-dev

Usage

1. Configure the Plugin

Add vite-plugin-uxdsl to your vite.config.js or vite.config.ts:

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

export default defineConfig({
  plugins: [
    vitePluginUxdsl({
      // Optional: Custom breakpoints (defaults shown)
      breakpoints: {
        xs: 0,
        sm: 480,
        md: 768,
        lg: 1024,
        xl: 1280,
      },
      // Optional: Pass other options directly to uxdsl-core
    }),
  ],
});

2. Import Your Styles

In your application's main entry file (e.g., main.js, main.ts, App.jsx, App.tsx), import your .uxdsl stylesheet:

// main.js or App.jsx
import './index.uxdsl';
// or
import './app.uxdsl';

3. TypeScript Support

If you are using TypeScript, you may encounter a Cannot find module... error (TS2307) when importing .uxdsl files. To fix this, you need to provide a type declaration.

If vite-env.d.ts exists: Add the following to your vite-env.d.ts file:

If vite-env.d.ts does not exist: Create a new file (e.g., src/uxdsl-env.d.ts or uxdsl-env.d.ts at your project root) and add the following content:

/// <reference types="vite/client" />

declare module '*.uxdsl' {
  const content: string;
  export default content;
}

Ensure your tsconfig.json's include array covers this new file (e.g., "include": ["src/**/*.ts", "src/**/*.d.ts"]).

Options

The plugin accepts options that are passed directly to uxdsl-core's processing engine:

• breakpoints: An object defining custom responsive breakpoints (e.g., { sm: 480, md: 768 }).
• Any other valid options for the processUxdsl function from uxdsl-core.

License

MIT © Ricardo Santoyo