Welcome

Introducing vite-plugin-sass-dts, a powerful plugin that helps you create type definitions automatically when using CSS modules the type-safe way. This guide will walk you through its installation and usage.

Demo

Installation

To get started, install the plugin using the following command:

bash
npm i -D vite-plugin-sass-dts

For version 1.3.27 or later, please ensure to use the latest sass-embedded package as it has been confirmed that the sass package is not compatible.

Options

The plugin comes with several configurable options:

• enabledMode (string[]): Controls the generation of d.ts files for your CSS modules. Valid values: development, production (default is [development]).
• global.generate (boolean): Output the common style set in additionalData as a global type definition file.
• global.outputFilePath (string): Specifies the output file of the global common style with an absolute path.
• typeName.replacement (function): Customize the output type name (default is classname key as a string).
• outputDir (string): Specifies the output directory for declaration files (default is the source directories).
• sourceDir (string): Your source code directory path for generating declaration files.
• esmExport (boolean): Indicates the ESM style export type.
• prettierFilePath (string): Path to the Prettier configuration file.

Add it to vite.config.ts

You can integrate the plugin in your vite.config.ts file like so:

ts
import { defineConfig } from 'vite';
import sassDts from 'vite-plugin-sass-dts';

export default defineConfig({
  plugins: [sassDts()],
});

Usage

Creating a d.ts file is straightforward. Simply save your SCSS file during development. Here’s how you can do it:

ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import sassDts from 'vite-plugin-sass-dts';
import path from 'path';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: '@use @styles as common;',
        importer(...args) {
          if (args[0] !== '@styles') return;
          return { file: path.resolve(__dirname, './src/assets/styles') };
        },
      },
    },
  },
  plugins: [
    react(),
    sassDts({
      enabledMode: ['development', 'production'],
      global: {
        generate: true,
        outputFilePath: path.resolve(__dirname, './src/style.d.ts'),
      },
      sourceDir: path.resolve(__dirname, './src'),
      outputDir: path.resolve(__dirname, './dist'),
    }),
  ],
});

Run your project using:

bash
npm run dev

Now, save your SCSS files located in src/assets/styles_index.scss and src/App.module.scss. By saving these files, a corresponding d.ts file will be created in your specified output directory.

Understanding the Code

Think of your project as a bakery, where each SCSS file is a different cookie recipe. When a SCSS file is saved (like baking a new batch of cookies), the plugin automatically creates a d.ts file that acts as a recipe card, outlining all the cookie (CSS class) names and properties that you can safely use throughout your project. This streamlines your workflow and eliminates the risk of selecting a cookie type (CSS class) that doesn’t exist, ensuring that your code is both efficient and type-safe!

Troubleshooting

If you run into issues, consider the following troubleshooting steps:

• Ensure you have the correct versions of sass-embedded installed.
• Check your vite.config.ts file for typos or misconfigurations.
• Consult the plugin’s GitHub repository for detailed documentation.
• For more insights, updates, or to collaborate on AI development projects, stay connected with fxis.ai.

Final Thoughts

At fxis.ai, we believe that such advancements are crucial for the future of AI, as they enable more comprehensive and effective solutions. Our team is continually exploring new methodologies to push the envelope in artificial intelligence, ensuring that our clients benefit from the latest technological innovations.