gatsby-plugin-scss-typescript

🛠️

---

Includes Gatsby V2 drop-in webpack support for SCSS stylesheets modules & automatic generation of accompanying typing declaration (.d.ts) files.

Install

yarn add --dev sass gatsby-plugin-scss-typescript

or

npm install --save-dev sass gatsby-plugin-scss-typescript

Usage

1. Include the plugin in your gatsby-config.js file.

// gatsby-config.js
plugins: ['gatsby-plugin-scss-typescript'];

2. Write your SCSS, import & use them as normal.

// component.ts
import * as styles from './styles.module.scss';

Only files that include the .module.scss extensions shall be treated as module files, and hence have typings generated at build time. .scss files shall be loaded using the regular css-loader with no additional magic.

Options

The default gatsby rule loaders are used where possible, see the gatsby webpack utils for more info.

declartionOptions

The declarationOptions key is passed to typings-for-css-modules-loader.

cssLoaderOptions

The cssLoaderOptions key is passed to the css-loader, with a few defaults from gatsby.

sassLoaderOptions

The sassLoaderOptions key is passed to the sass-loader.

cssMinifyOptions

The cssMinifyOptions key is passed to the OptimizeCssAssetsPlugin.

cssExtractOptions

The cssExtractOptions key is passed to the MiniCssExtractPlugin.

Example

// in gatsby-config.js
plugins: [
    {
        resolve: 'gatsby-plugin-scss-typescript',
        options: {
            cssLoaderOptions: {
                importLoaders: 1,
                localIdentName: '[name]_[local]___[contenthash:base64:5]_[emoji:1]',
            },
            sassLoaderOptions: {
                includePaths: [path.resolve(__dirname, './src/styles/scss')],
            },
            cssMinifyOptions: {
                assetNameRegExp: /\.optimize\.css$/g,
                canPrint: true,
            },
            cssExtractOptions: {
                filename: '[name].css',
                chunkFilename: '[id].css',
            },
        },
    },
];

FAQs

The plugin has generated a bunch of .d.ts files?!

Firstly, thats not really a question, but we can take a stab at it.

Yes, it does generate a bunch of files, one for each .module.scss file imported by a react component.

What do the .d.ts file do?

Thats better as a question. These are Typescript declaration files, they essentially describe a js module, such that TS can expect the details that are declared.

In this case they are describing what the scss will look like once it has been turned into a js module.

This is what is happening under the surface, when you write:

import styles from './styles.module.scss';

You are importing a js module that can be transpiled from your scss using a webpack loader.

Do I need these declaration files?

No.

Well, maybe. You can have type safe css without these declaration files using typescript-plugin-css-modules in your tsconfig.json.

For those who prefer to throw caution to the wind, you can use this:

declare module '*.scss' {
    const content: { [className: string]: string };

    export default content;
}

You animal. 🦁

I'm not seeing any files being created?

Make sure your file are suffixed with .module.scss, the plugin won't generate declarations for regular .scss files by design. This is to give the most power to you!

Do I need any other gatsby plugins to enable scss with my project?

No, and make sure you don't have other scss plugins like gatsby-plugin-sass installed, they'll just disagree. gatsby-plugin-scss-typescript achieves the same thing plus the type generation.

You will need sass as a dependency of your project though!