@mojojoejo/vite-plugin-virtual-css-variables NPM

@mojojoejo/vite-plugin-virtual-css-variables

Vite plugin for importing CSS variables from a JavaScript object.

📦 Install

Using npm:

npm install --save-dev @mojojoejo/vite-plugin-virtual-css-variables

Using yarn:

yarn add --dev @mojojoejo/vite-plugin-virtual-css-variables

Using pnpm:

pnpm add --save-dev @mojojoejo/vite-plugin-virtual-css-variables

🚀 Usage

Using `<link>` element

<html>
  <head>
    <link rel="stylesheet" href="virtual:variables.css" />
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

// vite.config.ts
import pluginCssVariables from "@mojojoejo/vite-plugin-virtual-css-variables";

export default {
  plugins: [
    pluginCssVariables({
      moduleId: "virtual:variables.css",
      variables: {
        "color-primary": "#0668E1",
      },
    }),
  ],
};

// => index.css
// :root {
//   --color-primary: #0668E1;
// }

Using imported module

<!-- index.html -->
<html>
  <body>
    <div id="root"></div>
    <script type="module" src="src/variables.ts"></script>
  </body>
</html>

// src/variables.ts
import "virtual:variables-module.css";

// vite.config.ts
import pluginCssVariables from "@mojojoejo/vite-plugin-virtual-css-variables";

export default {
  plugins: [
    pluginCssVariables({
      moduleId: "virtual:variables-module.css",
      variables: {
        "color-primary": "#0668E1",
      },
    }),
  ],
};

// => index.css
// :root {
//   --color-primary: #0668E1;
// }

Nested variable keys

For nested variable maps, subsequent keys will be concatenated with a separator string, defaulting to "-". A default key can be used when including child keys to provide a "default" value, without the separator string or a child key.

<!-- index.html -->
<html>
  <body>
    <div id="root"></div>
    <script type="module" src="src/variables.ts"></script>
  </body>
</html>

// src/variables.ts
import "virtual:variables-module.css";

// vite.config.ts
import pluginCssVariables from "@mojojoejo/vite-plugin-virtual-css-variables";

export default {
  plugins: [
    pluginCssVariables({
      moduleId: "virtual:variables-module.css",
      variables: {
        color: {
          blue: {
            default: "#0000FF",
            500: "#0668E1",
          }
          red: "#FF0000",
        },
      },
    }),
  ],
};

// => index.css
// :root {
//   --color-blue: #0000FF;
//   --color-blue-500: #0668E1;
//   --color-red: #FF0000;
// }

Multiple CSS variable objects

<!-- index.html -->
<html>
  <body>
    <div id="root"></div>
    <script type="module" src="src/variables.ts"></script>
  </body>
</html>

// src/variables.ts
import "virtual:variables-module.css";

// config/external.ts
export default {
  color: {
    primary: "#0000FF",
  },
};

// vite.config.ts
import pluginCssVariables from "@mojojoejo/vite-plugin-virtual-css-variables";
import externalVariables from "./config/external.ts";

export default {
  plugins: [
    pluginCssVariables({
      moduleId: "virtual:variables-module.css",
      variables: [
        {
          "color-primary": "#0668E1",
        },
        externalVariables,
      ],
    }),
  ],
};

// => index.css
// :root {
//   --color-primary: #0000FF;
// }

Multiple virtual modules

<!-- index.html -->
<html>
  <body>
    <div id="root"></div>
    <script type="module" src="src/variables.ts"></script>
  </body>
</html>

// src/variables.ts
import "virtual:primary.css";
import "virtual:secondary.css";

// vite.config.ts
import pluginCssVariables from "@mojojoejo/vite-plugin-virtual-css-variables";

export default {
  plugins: [
    pluginCssVariables([
      {
        moduleId: "virtual:primary.css",
        variables: {
          "color-primary": "#0000FF",
        },
      },
      {
        moduleId: "virtual:secondary.css",
        variables: {
          "color-primary": "#FF0000",
        },
      },
    ]),
  ],
};

// => index.css
// :root {
//   --color-primary: #0000FF;
// }
// :root {
//   --color-secondary: #FF0000;
// }

Custom formatting

See Options for advanced formatting options of virtual module output.

<!-- index.html -->
<html>
  <body>
    <div id="root"></div>
    <script type="module" src="src/variables.ts"></script>
  </body>
</html>

// src/variables.ts
import "virtual:variables-module.css";

// vite.config.ts
import pluginCssVariables from "@mojojoejo/vite-plugin-virtual-css-variables";

export default {
  plugins: [
    pluginCssVariables({
      moduleId: "virtual:variables-module.css",
      variables: {
        "color-primary": "#0668E1",
      },
      pretty: false,
    }),
  ],
};

// => index.css
// :root {--color-primary: #0668E1;}

⚙️ Options

Requires moduleId and variables options to be set. Can supply options as array to include multiple virtual modules.

interface Options {
  /**
   * Virtual module ID of CSS variables file.
   */
  moduleId: string;
  /**
   * Recursive map of CSS variable names and values.
   */
  variables: CssVariablesMap | CssVariablesMap[];
  /**
   * String that separates nested keys to form variable names.
   *
   * default: "-"
   */
  separator?: string;
  /**
   * CSS selector that will contain all CSS variables.
   *
   * default: ":root"
   */
  selector?: string;
  /**
   * Pretty print CSS variables and selectors. Configurable through `useTabs`
   * and `tabSize` options.
   *
   * default: true
   */
  pretty?: boolean;
  /**
   * Use tabs instead of spaces to indent lines in output. Requires `pretty`
   * option to be enabled.
   *
   * default: false
   */
  useTabs?: boolean;
  /**
   * Number of spaces to indent lines in output. Requires `pretty` option to be
   * enabled and `useTabs` option to be disabled.
   *
   * default: 2
   */
  tabSize?: number;
}