Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/debens/gatsby-plugin-scss-typescript
GatsbyJS plugin for using SCSS Modules and generating Typescript declaration files 🛠️
https://github.com/debens/gatsby-plugin-scss-typescript
gatsby gatsby-plugin sass scss typescript webpack
Last synced: 3 months ago
JSON representation
GatsbyJS plugin for using SCSS Modules and generating Typescript declaration files 🛠️
- Host: GitHub
- URL: https://github.com/debens/gatsby-plugin-scss-typescript
- Owner: Debens
- License: mit
- Created: 2019-02-14T16:29:41.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T04:23:03.000Z (almost 2 years ago)
- Last Synced: 2024-10-02T03:23:47.791Z (3 months ago)
- Topics: gatsby, gatsby-plugin, sass, scss, typescript, webpack
- Language: TypeScript
- Size: 1.32 MB
- Stars: 9
- Watchers: 2
- Forks: 2
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
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.
```javascript
// gatsby-config.js
plugins: ['gatsby-plugin-scss-typescript'];
```
2. Write your SCSS, import & use them as normal.
```javascript
// 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](https://github.com/webpack-contrib/css-loader) with no additional magic.
## Options
The default gatsby rule loaders are used where possible, see the [gatsby webpack utils](https://github.com/gatsbyjs/gatsby/blob/0deda7b5646b3eb8db1b1873faf13553311c4878/packages/gatsby/src/utils/webpack-utils.js) for more info.
## declartionOptions
The `declarationOptions` key is passed to [typings-for-css-modules-loader](https://github.com/TeamSupercell/typings-for-css-modules-loader#options).
### cssLoaderOptions
The `cssLoaderOptions` key is passed to the [css-loader](https://github.com/webpack-contrib/css-loader), with a few [defaults](https://github.com/gatsbyjs/gatsby/blob/0deda7b5646b3eb8db1b1873faf13553311c4878/packages/gatsby/src/utils/webpack-utils.js#L392-L403) from gatsby.
### sassLoaderOptions
The `sassLoaderOptions` key is passed to the [sass-loader](https://github.com/webpack-contrib/sass-loader).
### cssMinifyOptions
The `cssMinifyOptions` key is passed to the [OptimizeCssAssetsPlugin](https://github.com/NMFR/optimize-css-assets-webpack-plugin).
### cssExtractOptions
The `cssExtractOptions` key is passed to the [MiniCssExtractPlugin](https://github.com/gatsbyjs/gatsby/blob/0deda7b5646b3eb8db1b1873faf13553311c4878/packages/gatsby/src/utils/webpack-utils.js#L482-L487).
### Example
```javascript
// 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](https://microsoft.github.io/TypeScript-New-Handbook/chapters/type-declarations/), 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:
```ts
import styles from './styles.module.scss';
```
You are importing a js module that can be transpiled from your scss using a [webpack loader](https://webpack.js.org/loaders/).
#### Do I need these declaration files?
No.
Well, maybe. You can have type safe css without these declaration files using [typescript-plugin-css-modules](https://github.com/mrmckeb/typescript-plugin-css-modules) in your `tsconfig.json`.
For those who prefer to throw caution to the wind, you can use this:
```ts
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!