vite-plugin-dynamic-sass-themes

A Vite plugin for dynamically compiling and applying SASS themes in your Vite project. This plugin allows you to manage multiple SASS themes, compile them on-the-fly, and dynamically update the styles in the browser without a full page reload.

---

Features

• Dynamic Theme Compilation: Automatically compiles SASS themes from a specified directory.
• Hot Module Replacement (HMR): Updates styles in the browser without reloading the page.
• Customizable Options: Configure themes directory, output directory, logging, and SASS options.
• TypeScript Support: Includes TypeScript declarations for the virtual module.

---

Installation

Install the plugin using npm, pnpm, or yarn:

1# npm
2npm install vite-plugin-dynamic-sass-themes --save-dev
3
4# pnpm
5pnpm add vite-plugin-dynamic-sass-themes --save-dev
6
7# yarn
8yarn add vite-plugin-dynamic-sass-themes --dev
9

---

Usage

1. Add the Plugin to vite.config.ts

Configure the plugin in your vite.config.ts file:

1import { defineConfig } from "vite";
2import dynamicSassThemePlugin from "vite-plugin-dynamic-sass-themes";
3
4export default defineConfig({
5  plugins: [
6    dynamicSassThemePlugin({
7      themesDir: "src/themes", // Relative path to themes directory
8      outputDir: "public/themes", // Relative path to output directory
9      log: true, // Enable logging
10      sassOptions: {
11        style: "compressed", // Minify CSS output
12        sourceMap: true, // Generate source maps
13      },
14    }),
15  ],
16});

---

2. Import the Client-Side Code

In your main entry file (e.g., main.ts or main.js), import the client-side code:

1import "virtual:dynamic-sass-themes-client";

---

3. Declare the Virtual Module in vite-env.d.ts

If you don’t already have a vite-env.d.ts file, create one in the root of your project. Then, add the following declaration for the virtual module:

1/// <reference types="vite/client" />
2
3// Declare the virtual module
4declare module "virtual:dynamic-sass-themes-client" {
5  const clientCode: string;
6  export default clientCode;
7}

---

4. Ensure vite-env.d.ts is Included in tsconfig.json

Make sure your tsconfig.json includes the vite-env.d.ts file:

1{
2  "compilerOptions": {
3    "types": ["vite/client"]
4  },
5  "include": ["src", "vite-env.d.ts"]
6}

---

Example Project Structure

Here’s how your project structure should look:

my-project/
├── src/
│   ├── main.ts
│   └── themes/
│       ├── light/
│       │   └── theme.scss
│       └── dark/
│           └── theme.scss
├── vite-env.d.ts
├── vite.config.ts
├── tsconfig.json
├── package.json
└── ...

---

How It Works

Plugin Side

• The plugin watches for changes to .scss files in the themesDir.
• When a .scss file changes, it compiles the file and sends the compiled CSS to the client via a custom HMR event (vite-plugin-dynamic-sass-themes:update).

Client Side

• The client-side code is injected as a virtual module (virtual:dynamic-sass-themes-client).
• When the HMR event is received, the client-side code dynamically updates the <style> element with the new CSS.

---

Testing

1. Add the declaration to vite-env.d.ts in your project.
2. Ensure vite-env.d.ts is included in tsconfig.json.
3. Run your Vite development server.
4. Modify a .scss file in your themesDir.
5. Observe that the browser updates the styles dynamically without reloading the page, and TypeScript no longer throws an error.

---

Options

The plugin accepts the following options:

Option	Type	Default	Description
themesDir	string	"src/themes"	Directory containing theme SASS files.
outputDir	string	"public/themes"	Output directory for compiled CSS.
log	boolean	true	Enable/disable logging.
sassOptions	object	{}	Additional SASS options (e.g., style, sourceMap).

---

Contributing

If you find any issues or have suggestions for improvements, feel free to open an issue or submit a pull request.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Happy theming! 🎨