skovy/typed-scss-modules


🎁 Generate type definitions (.d.ts) for CSS Modules using SCSS

https://skovy.dev/object-factories-for-testing-in-typescript/

License: MIT

Language: TypeScript

Keywords: cli, css-modules, generator, sass, scss, scss-modules, typescript


🎁 typed-scss-modules

All Contributors Build Status npm version

Generate TypeScript definitions (.d.ts) files for CSS Modules that are written in SCSS (.scss). Check out this post to learn more about the rationale and inspiration behind this package.

Example

For example, given the following SCSS:

@import "variables";

.text {
  color: $blue;

  &-highlighted {
    color: $yellow;
  }
}

The following type definitions will be generated:

export const text: string;
export const textHighlighted: string;

Basic Usage

Run with npm package runner:

npx tsm src

Or, install globally:

yarn global add typed-scss-modules
tsm src

Or, install and run as a devDependency:

yarn add -D typed-scss-modules
yarn tsm src

Advanced Usage

For all possible commands, run tsm --help.

The only required argument is the directoy where all SCSS files are located. Running tsm src will search for all files matching src/**/*.scss. This can be overridden by providing a glob pattern instead of a directory. For example, tsm src/*.scss

--watch (-w)

  • Type: boolean
  • Default: false
  • Example: tsm src --watch

Watch for files that get added or are changed and generate the corresponding type definitions.

--ignoreInitial

  • Type: boolean
  • Default: false
  • Example: tsm src --watch --ignoreInitial

Skips the initial build when passing the watch flag. Use this when running concurrently with another watch, but the initial build should happen first. You would run without watch first, then start off the concurrent runs after.

--ignore

  • Type: string[]
  • Default: []
  • Example: tsm src --watch --ignore "**/secret.scss"

A pattern or an array of glob patterns to exclude files that match and avoid generating type definitions.

--includePaths (-i)

  • Type: string[]
  • Default: []
  • Example: tsm src --includePaths src/core

An array of paths to look in to attempt to resolve your @import declarations. This example will search the src/core directory when resolving imports.

--implementation

  • Type: "node-sass" | "sass"
  • Default: If an option is passed, it will always use the provided package implementation. If an option is not passed, it will first check if node-sass is installed. If it is, it will be used. Otherwise, it will then check if sass is installed. If it is, it will be used. Finally, falling back to node-sass if all checks and validations fail.
  • Example: tsm src --implementation sass

--aliases (-a)

  • Type: object
  • Default: {}
  • Example: tsm src --aliases.~some-alias src/core/variables

An object of aliases to map to their corresponding paths. This example will replace any @import '~alias' with @import 'src/core/variables'.

--aliasPrefixes (-p)

  • Type: object
  • Default: {}
  • Example: tsm src --aliasPrefixes.~ node_modules/

An object of prefix strings to replace with their corresponding paths. This example will replace any @import '~bootstrap/lib/bootstrap' with @import 'node_modules/bootstrap/lib/bootstrap'. This matches the common use-case for importing scss files from node_modules when sass-loader will be used with webpack to compile the project.

--nameFormat (-n)

  • Type: "camel" | "kebab" | "param" | "dashes" | "none"
  • Default: "camel"
  • Example: tsm src --nameFormat camel

The class naming format to use when converting the classes to type definitions.

  • camel: convert all class names to camel-case, e.g. App-Logo => appLogo.
  • kebab/param: convert all class names to kebab/param case, e.g. App-Logo => app-logo (all lower case with '-' separators).
  • dashes: only convert class names containing dashes to camel-case, leave others alone, e.g. App => App, App-Logo => appLogo. Matches the webpack css-loader camelCase 'dashesOnly' option.
  • none: do not modify the given class names (you should use --exportType default when using --nameFormat none as any classes with a - in them are invalid as normal variable names). Note: If you are using create-react-app v2.x and have NOT ejected, --nameFormat none --exportType default matches the class names that are generated in CRA's webpack's config.

--listDifferent (-l)

  • Type: boolean
  • Default: false
  • Example: tsm src --listDifferent

List any type definition files that are different than those that would be generated. If any are different, exit with a status code 1.

--exportType (-e)

  • Type: "named" | "default"
  • Default: "named"
  • Example: tsm src --exportType default

The export type to use when generating type definitions.

named

Given the following SCSS:

.text {
  color: blue;

  &-highlighted {
    color: yellow;
  }
}

The following type definitions will be generated:

export const text: string;
export const textHighlighted: string;

default

Given the following SCSS:

.text {
  color: blue;

  &-highlighted {
    color: yellow;
  }
}

The following type definitions will be generated:

export interface Styles {
  text: string;
  textHighlighted: string;
}

export type ClassNames = keyof Styles;

declare const styles: Styles;

export default styles;

This export type is useful when using kebab (param) cased class names since variables with a - are not valid variables and will produce invalid types or when a class name is a TypeScript keyword (eg: while or delete). Additionally, the Styles and ClassNames types are exported which can be useful for properly typing variables, functions, etc. when working with dynamic class names.

Examples

For examples, see the examples directory:

Contributors

Thanks goes to these wonderful people (emoji key):

Spencer Miskoviak
Spencer Miskoviak

🐛 📝 💻 💡 🤔 🚇 🚧 👀 🛡️ ⚠️
Janeene Beeforth
Janeene Beeforth

🐛 💻 📖
Eric Ferreira
Eric Ferreira

💻 📖
Luis Lopes
Luis Lopes

💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Alternatives

This package was heavily influenced on typed-css-modules which generates TypeScript definitions (.d.ts) files for CSS Modules that are written in CSS (.css).

This package is currently used as a CLI. There are also packages that generate types as a webpack loader.

Project Statistics

Sourcerank 10
Repository Size 2.91 MB
Stars 65
Forks 10
Watchers 1
Open issues 6
Dependencies 1,916
Contributors 6
Tags 3
Created
Last updated
Last pushed

Top Contributors See all

Spencer Miskoviak dependabot[bot] allcontributors[bot] dawnmist erkalicious Luis Lopes

Packages Referencing this Repo

typed-scss-modules
TypeScript type definition generator for SCSS CSS Modules
Latest release 1.1.0 - Updated - 65 stars
@jabuco/typed-scss-modules
TypeScript type definition generator for SCSS CSS Modules
Latest release 0.2.0 - Updated - 65 stars

Recent Tags See all

v1.1.0 January 19, 2020
v1.0.1 December 08, 2019
v1.0.0 December 08, 2019

Something wrong with this page? Make a suggestion

Last synced: 2019-12-08 21:10:37 UTC

Login to resync this repository