Skip to content

chore(docs): Add error FAQs to docs #283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 11, 2020
Merged

chore(docs): Add error FAQs to docs #283

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 35 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,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:
Expand Down Expand Up @@ -239,7 +239,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": {
Expand All @@ -249,7 +249,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": {
Expand All @@ -262,7 +262,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": [
Expand Down Expand Up @@ -490,3 +492,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 `<style>` tags that have been added to the `<head>` and find the one related to your CSS module. Copy the code into your editor and search for the class name.

Once you've verified that the class is being rendered in CSS, the likely cause is that the `babel-plugin-react-css-modules` is unable to find your CSS class in the parsed code. If you're using different CSS (such as SCSS), verify that you have [configured a syntax loader](#configurate-syntax-loaders).

However, if you're using a syntaxes such as [`postcss-scss`](https://github.com/postcss/postcss-scss) or [`postcss-less`](https://github.com/webschik/postcss-less), they do not compile down to CSS. So if you are programmatically building a class name (see below), webpack will be able to generate the rendered CSS from SCSS/LESS, but `babel-plugin-react-css-modules` will not be able to parse the SCSS/LESS.

A SCSS example:

```scss
$scales: 10, 20, 30, 40, 50;

@each $scale in $scales {
.icon-#{$scale} {
width: $scale;
height: $scale;
}
}
```

`babel-plugin-react-css-modules` will not receive `icon-10` or `icon-50`, but `icon-#{$scale}`. That is why you receive the error that `styleName` `"icon-10"` cannot be found.