Windi JS

Appearance

Return to top
On this page

Integration for Vite

JavaScript
TypeScript
vanilla
preact
react
svelte
vue

Install

Install the package:

bash
npm install --save-dev windijs @windijs/utilities @windijs/variants @windijs/plugin-utils

Setup

Configure Vite

First, add windijs plugin to your vite plugins.

TIP

  1. Read Configuration Guide for the configuration of Windi JS.
  2. Refer to Options Section for the configuration of the plugin.
vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";
import windiConfig from "./windi.config"; // optional

export default defineConfig({
  plugins: [
    windijs({
      config: windiConfig, // optional
    }),
  ],
});

Configure Vanilla

In this step, you need to set cssInJsLoader, and import useArrayHelper to support inline utilities.

main.js
js
import { cssInJsLoader, useArrayHelper, useStyleLoader } from "windijs";

useArrayHelper();
useStyleLoader(cssInJsLoader);

document.querySelector("#app").innerHTML = `<div>Hello World</div>`;

Try it

Now you can try some utilities and variants to see if this plugin works.

main.js
js
const logo = [bg.blue[400].opacity(30), lg(bg.green[400].opacity(40))];

document.querySelector("#app").innerHTML = `
  <div>
    <a href="https://vitejs.dev" target="_blank">
      <img src="/vite.svg" class="logo ${bg.indigo[500].opacity(50)}" alt="Vite logo" />
    </a>
    <a href="https://www.typescriptlang.org/" target="_blank">
      <img class="logo vanilla ${logo}" alt="TypeScript logo" />
    </a>
    <h1>Vite + TypeScript</h1>
  </div>
`;

Options

The following is the type reference of plugin options.

ts
type PluginOptions = {
  alias?: Record<string, string>;
  config?: Config;
  env?: {
    config?: EntryOptions;
    utilities?: EntryOptions;
    variants?: EntryOptions;
    rootEntry?: string;
    nodeModulesEntry?: string;
    globalEntry?: string | false;
    moduleEntry?: string | false;
    configEntry?: string | false;
  };
  include?: string[];
  exclude?: string[];
};

type EntryOptions = {
  lib?: string;
  module?: boolean;
  global?: boolean;
};

alias

Define alias for imports (utilities / variants), default is {}.

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      alias: {
        p: "_p", // rename utility `p` to `_p`,
        text: "t", // rename utility `text` to `t`
        dark: "onDark", // rename variant `dark` to `onDark`
        hover: "hv": // rename variant `hover` to `hv`
      },
    })
  ]
})

config

Customize windi configuration, default is {}.

With Config Object

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      config: {
        theme: {
          colors: {
            red: "#f00",
            blue: "#00f"
          }
        }
      },
    }
  ]
})

With Config File

vite.config.js
js
import { defineConfig } from "vite";
import windiConfig from "./windi.config";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      config: windiConfig,
    }
  ]
})

env

Define plugin environment, defaults are as follows:

ts
const DefaultEnv = {
  rootEntry: "./",
  configEntry: "./windi.config",
  globalEntry: "./src/windi-global.d.ts",
  moduleEntry: "./src/windi-module.d.ts",
  nodeModulesEntry: "./node_modules",
  config: {
    lib: "windijs",
    module: true,
    global: false,
  },
  utilities: {
    lib: "@windijs/utilities",
    module: true,
    global: true,
  },
  variants: {
    lib: "@windijs/variants",
    module: true,
    global: true,
  },
};

rootEntry

The root entry of this plugin. If specified, the value of configEntry, globalEntry, moduleEntry, nodeModulesEntry will be resolved relative to this directory.

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      env: {
        rootEntry: "./packages/frontend",

        // The path of `configEntry` would be `path.resolve("./packages/frontend", "./windi.config")`
        // The path of `globalEntry` would be `path.resolve("./packages/frontend", "./src/windi-global.d.ts")`,
        // The path of `moduleEntry` would be `path.resolve("./packages/frontend", "./src/windi-module.d.ts")`,
        // The path of `nodeModulesEntry` would be `path.resolve("./packages/frontend", "./node_modules")`,

      }
    }
  ]
})

configEntry

The config entry of this plugin, priority is lower than rootEntry.

TIP

The path should not include file extension. For example, ./src/windi.config.js should be written as ./src/windi.config.

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      env: {
        configEntry: "./src/windi.config",
      }
    }
  ]
})

globalEntry

File path for writing global types, priority is lower than rootEntry. If the value is false, no global types will be generated.

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      env: {
        globalEntry: "./src/types/windi-global.d.ts",
      }
    }
  ]
})

moduleEntry

File path for writing virtual module types, priority is lower than rootEntry. If the value is false, no virtual module types will be generated.

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      env: {
        globalEntry: "./src/types/windi-module.d.ts",
      }
    }
  ]
})

nodeModulesEntry

The node_modules entry of this plugin, priority is lower than rootEntry. We need this option to find the location of the utilities or variants lib you installed.

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      env: {
        nodeModulesEntry: "./packages/frontend/node_modules",
      }
    }
  ]
})

utilities

Define the utilities environment.

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      env: {
        lib: "@windijs/utilities", // package name of utilities lib, default is `@windijs/utilities`.
        module: true, // enable virtual module type generation for utilities, default is `true`.
        global: false, // enable global type generation for utilities, default is `true`.
      }
    }
  ]
})

variants

Define the variants environment.

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      env: {
        lib: "@windijs/variants", // package name of variants lib, default is `@windijs/variants`.
        module: true, // enable virtual module type generation for variants, default is `true`.
        global: false, // enable global type generation for variants, default is `true`.
      }
    }
  ]
})

config

Define the config environment.

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      env: {
        lib: "windijs", // package name of config lib, default is `windijs`.
        module: true, // enable virtual module type generation for configurations, default is `true`.
        global: false, // enable global type generation for configurations, default is `false`.
      }
    }
  ]
})

include

Glob patterns for including files that should be matched, default is ["./src/**/*.{vue,jsx,tsx}"].

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      include: ["./src/**/*.{js,ts}"]
    }
  ]
})

exclude

Glob patterns for excluding files that should not be matched, default is ["**/node_modules"].

vite.config.js
js
import { defineConfig } from "vite";
import windijs from "@windijs/plugin-utils/vite";

export default defineConfig({
  plugins: [
    windijs({
      exclude: ["./frontend/node_modules"]
    }
  ]
})

Released under the MIT License.

Copyright © 2022-present Raven Satir