diff --git a/README.md b/README.md index 30a303c..44b349b 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,17 @@ # babel-plugin-react-css-modules -[![GitSpo Mentions](https://gitspo.com/badges/mentions/gajus/babel-plugin-react-css-modules?style=flat-square)](https://gitspo.com/mentions/gajus/babel-plugin-react-css-modules) [![Travis build status](http://img.shields.io/travis/gajus/babel-plugin-react-css-modules/master.svg?style=flat-square)](https://travis-ci.org/gajus/babel-plugin-react-css-modules) [![NPM version](http://img.shields.io/npm/v/babel-plugin-react-css-modules.svg?style=flat-square)](https://www.npmjs.org/package/babel-plugin-react-css-modules) [![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical) [![Gitter](https://img.shields.io/gitter/room/babel-plugin-react-css-modules/Lobby.svg?style=flat-square)](https://gitter.im/babel-plugin-react-css-modules/Lobby) [![Twitter Follow](https://img.shields.io/twitter/follow/kuizinas.svg?style=social&label=Follow)](https://twitter.com/kuizinas) +> # Looking for maintainers +> +> This project is not actively maintained by the original author. However, I am happy to nominate new maintainers. +> If you wish to contribute to `babel-plugin-react-css-modules`, please begin by raising PRs that fix existing issues. +> PRs must pass CI/CD tests, include tests (if they change behavior or fix a bug), and include documentation. + Transforms `styleName` to `className` using compile time [CSS module](#css-modules) resolution. @@ -163,7 +168,7 @@ NODE_ENV=production ./test ## How does it work? 1. Builds index of all stylesheet imports per file (imports of files with `.css` or `.scss` extension). -1. Uses [postcss](https://github.com/postcss/postcss) to parse the matching CSS files. +1. Uses [postcss](https://github.com/postcss/postcss) to parse the matching CSS files into a lookup of CSS module references. 1. Iterates through all [JSX](https://facebook.github.io/react/docs/jsx-in-depth.html) element declarations. 1. Parses the `styleName` attribute value into anonymous and named CSS module references. 1. Finds the CSS class name matching the CSS module reference: @@ -194,7 +199,7 @@ Configure the options for the plugin within your `.babelrc` as follows: |`context`|`string`|Must match webpack [`context`](https://webpack.js.org/configuration/entry-context/#context) configuration. [`css-loader`](https://github.com/webpack/css-loader) inherits `context` values from webpack. Other CSS module implementations might use different context resolution logic.|`process.cwd()`| |`exclude`|`string`|A RegExp that will exclude otherwise included files e.g., to exclude all styles from node_modules `exclude: 'node_modules'`| |`filetypes`|`?FiletypesConfigurationType`|Configure [postcss syntax loaders](https://github.com/postcss/postcss#syntaxes) like sugarss, LESS and SCSS and extra plugins for them. || -|`generateScopedName`|`?GenerateScopedNameConfigurationType`|Refer to [Generating scoped names](https://github.com/css-modules/postcss-modules#generating-scoped-names). If you use this option, make sure it matches the value of `localIdentName` in webpack config. See this [issue](https://github.com/gajus/babel-plugin-react-css-modules/issues/108#issuecomment-334351241) |`[path]___[name]__[local]___[hash:base64:5]`| +|`generateScopedName`|`?GenerateScopedNameConfigurationType`|Refer to [Generating scoped names](https://github.com/css-modules/postcss-modules#generating-scoped-names). If you use this option, make sure it matches the value of `localIdentName` [in webpack config](https://webpack.js.org/loaders/css-loader/#localidentname). See this [issue](https://github.com/gajus/babel-plugin-react-css-modules/issues/108#issuecomment-334351241) |`[path]___[name]__[local]___[hash:base64:5]`| |`removeImport`|`boolean`|Remove the matching style import. This option is used to enable server-side rendering.|`false`| |`webpackHotModuleReloading`|`boolean`|Enables hot reloading of CSS in webpack|`false`| |`handleMissingStyleName`|`"throw"`, `"warn"`, `"ignore"`|Determines what should be done for undefined CSS modules (using a `styleName` for which there is no CSS module defined). Setting this option to `"ignore"` is equivalent to setting `errorWhenNotFound: false` in [react-css-modules](https://github.com/gajus/react-css-modules#errorwhennotfound). |`"throw"`| @@ -239,7 +244,7 @@ To add support for different CSS syntaxes (e.g. SCSS), perform the following two npm install postcss-scss --save-dev ``` -2. Add a filetype syntax mapping to the Babel plugin configuration +2. Add a `filetypes` syntax mapping to the Babel plugin configuration. For example for SCSS: ```json "filetypes": { @@ -249,7 +254,7 @@ To add support for different CSS syntaxes (e.g. SCSS), perform the following two } ``` - And optionaly specify extra plugins + And optionally specify extra plugins: ```json "filetypes": { @@ -262,7 +267,9 @@ To add support for different CSS syntaxes (e.g. SCSS), perform the following two } ``` - Postcss plugins can have options specified by wrapping the name and an options object in an array inside your config + > NOTE: [`postcss-nested`](https://github.com/postcss/postcss-nested) is added as an extra plugin for demonstration purposes only. It's not needed with [`postcss-scss`](https://github.com/postcss/postcss-scss) because SCSS already supports nesting. + + Postcss plugins can have options specified by wrapping the name and an options object in an array inside your config: ```json "plugins": [ @@ -490,3 +497,32 @@ To enable live reloading of the CSS: > Note: > > This is a [webpack](https://webpack.github.io/) specific option. If you are using `babel-plugin-react-css-modules` in a different setup and require CSS live reloading, raise an issue describing your setup. + +### I get a "Cannot use styleName attribute for style name '`[X]`' without importing at least one stylesheet." error + +First, ensure that you are correctly importing the CSS file following the [conventions](#conventions). + +If you are correctly importing but using different CSS (such as SCSS), this is likely happening because your CSS file wasn't able to be successfully parsed. You need to [configure a syntax loader](#configurate-syntax-loaders). + +### I get a "Could not resolve the styleName '`[X]`' error but the class exists in the CSS included in the browser. + +First, verify that the CSS is being included in the browser. Remove from `styleName` the reference to the CSS class that's failing and view the page. Search through the `