Introduction to typed-scss-modules
Overview
The typed-scss-modules project offers a powerful tool for web developers using SCSS in their projects. It automatically generates TypeScript definitions (.d.ts files) for CSS Modules written in SCSS (.scss), which bridges the gap between CSS stylesheets and TypeScript's type system. This is particularly beneficial for developers aiming to use CSS Modules in TypeScript projects while maintaining type safety and improving code intelligence.
Why Use typed-scss-modules?
The primary goal of typed-scss-modules is to provide automatic TypeScript definitions for SCSS files to ensure that class names used in stylesheets have corresponding TypeScript types. This minimizes the risk of runtime errors due to typos and enhances the development experience by offering type safety and autocompletion features in IDEs. Moreover, it supports best practices in modern web development by bringing tooling advantages to CSS, similar to how TypeScript does for JavaScript.
Basic Usage
Using typed-scss-modules is straightforward. It can be installed locally in a project as a development dependency or globally on a system. Once installed, users can run a single command pointing to the directory containing SCSS files to generate the necessary TypeScript definitions.
Installation and Command Usage
To install as a development dependency use:
yarn add -D typed-scss-modules
yarn typed-scss-modules src
For global installation:
yarn global add typed-scss-modules
typed-scss-modules src
Alternatively, using npm:
npm install -D typed-scss-modules
npx typed-scss-modules src
CLI Options
The tool is highly configurable through its command-line interface options:
- Watch Mode (
--watchor-w): Continuously monitors SCSS files for changes and updates the TypeScript definitions accordingly. - Ignore Initial (
--ignoreInitial): Skip the initial file conversion, useful when starting the watcher after manual or other automated initial processing. - Ignore Pattern (
--ignore): Exclude specific files from being processed by providing glob patterns. - Include Paths (
--includePathsor-i): Specify directories to resolve@importdeclarations, aiding in SCSS file management. - Type Naming and Export (
--nameFormat,--exportType): Customize how class names are formatted in TypeScript files and how types are exported. - Quote Type (
--quoteTypeor-q): Choose between single or double quotes for class name definition, synchronizing with your project's coding style. - Logging (
--logLevel): Control the verbosity of the console output, ranging from verbose to silent.
Advanced Features
- Configuration Files: Instead of always using CLI options, configuration files can be set up in the project's root directory with supported names such as
typed-scss-modules.config.ts. This facilitates easy sharing and maintenance of project-specific settings. - Custom Importer: For projects with custom SCSS importers, support is available to maintain consistency with existing build processes.
- Output Management (
--outputFolder): Organize generated files into dedicated directories, keeping project structure clean and manageable.
Examples
The project repository includes several examples showcasing different configurations and usages:
- Basic Setup: Demonstrating the minimal required setup.
- Default Export: Illustration of using the default export type for projects demanding greater flexibility in class naming.
- Custom Configuration: Examples where custom importers and additional configurations are applied, highlighting the tool's versatility.
Community and Contributors
The project acknowledges multiple contributors who have enhanced its features and maintained its reliability. Furthermore, there are community resources such as documentation and tutorials to help users get the most out of the tool. The project uses a standard emoji key for contributions to easily recognize various types of contributions such as bug reports, code, documentation, and ideas.
In conclusion, the typed-scss-modules tool is an invaluable asset for developers looking to integrate TypeScript's robust typing capabilities with SCSS in their projects, ensuring a seamless development experience and high code quality.