Skip to content

Commit

Permalink
merge docs-patch-1
Browse files Browse the repository at this point in the history
  • Loading branch information
@tusharsnx
tusharsnx committed Jun 3, 2022
1 parent 874e8b8 commit ceae302
Showing 1 changed file with 74 additions and 56 deletions.
130 changes: 74 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,33 @@


# Introduction

This is a babel plugin to transform all your string classes into css-module classes automatically.
This is a babel plugin to transform all your string classes into css-module classes automatically.

Its lets you use css-module classes without style object.
It is faster to write, improves code readability and supports multiple css-module using [named-module](#introducing-named-css-modules)

Its lets you write css-module classes just like normal classes (without using style objects). Its faster to write and improves code readability.
You can import multiple css-modules with different names and then use it as [named-module](#introducing-named-css-modules). supports \*sass/scss modules also.
Also supports \*sass/scss modules.

*\*you may need to use sass-loader with webpack*
_\*you may need to use sass-loader with webpack_

# Installation

Install the plugin using npm:
- Install the plugin with npm:

```sh
npm install --save-dev jsx-css-module-transforms
npm install --save-dev jsx-css-module-transforms
```

after installing, If you are using babel, add this to your plugins:
- If you are using babel, add this to your plugins:

```jsonc
// .babelrc

{
"plugins": [
"module:jsx-css-module-transforms",
]
"plugins": ["module:jsx-css-module-transforms"]
}
```

Or, for Webpack, modify the babel-loader options to include the plugin:
- For Webpack, modify the babel-loader options to include the plugin:

```js
// webpack.config.js
Expand All @@ -46,8 +46,9 @@ module.exports = {
}
```

> Note: *The plugin expects source code with **JSX**, plugins that executes before might transform JSX even before it reaches to the plugin.
> If plugin isn't working or throwing unexpected errors, try keeping it at the beginning of the list.*
> Note: _The plugin relies on the **JSX** syntax. Other plugins that executes early might transform JSX
> before it reaches to the plugin which might cause some problems. jsx-css-module-transforms plugin needs
> to be placed before(ideally, at the beginning) other plugins that transform JSX._
# Usage

Expand All @@ -56,36 +57,43 @@ We can import the css-module like normal css import without any import variable.
```jsx
import "./m1.module.css"
```
The plugin will automatically change this import statement to use style object,
which will then be used to access the css-module classes.

The plugin will automatically change the import statement to include style object,
which will be used to access the css-module classes.

```jsx
import _style from "./m1.module.css" // modified
```

If we now want to use the css-module, we have to write all our css classes using style object that we just imported:
If we want to use the css-module, we need to write all our css classes using
style object that we just imported:

```jsx
import _style from "./m1.module.css"

function Component() {
return <h1 className={`${_style.foo} ${_style.bar}`}> ..... </h1>
return <h1 className={`${_style.foo} ${_style.bar}`}> ... </h1>
}
```
This sometimes can get too verbose and hurts **code readibility**. It would be nice if we could write our classes as strings and not having to deal with any style objects.

*remember, because of style objects we need to introduce template strings and object notations within our `className` attribute.*
This sometimes can get too verbose and hurts **code readibility**.
It would be nice if we could write classnames within a string and not
having to deal with any style objects.


With the help of plugin, we don't have to use style object anymore, instead we can specify our classes by just using strings:

With the help of the plugin, we don't have to use style object anymore, instead we can specify our classes just using strings:
```jsx
import "./m1.module.css"

function Component() {
return <h1 className="foo bar"> ..... </h1>
return <h1 className="foo bar"> ... </h1>
}
```
This looks more readable and is faster to write as well.
The plugin will modify our code to use css-module and its style object automatically without us having to do anything:

This looks more readable and is faster to write as well.
__jsx-css-modules-transforms__ will modify the code to use css-module and its style object automatically without
us having to do anything:

```jsx
// modified
Expand All @@ -96,15 +104,20 @@ function Component() {
}
```

**By default, If plugin found any `'*.module.css'` import, it will transform all our css classes to use style objects.**
The transformed code uses object bracket-notation instead of dot-notation as this allows
us to use `-` (dash) within our classnames (eg. `className="foo-bar"`).

If we want to use global css classes, we need to add `':g'` at the end of the class. This will tell plugin not to transform these classes and keep them as is:
## Global Styles

By default, If plugin finds **any** `'*.module.css'` import, it will transform **all** the css classes
to use style objects. To use global css classnames, we need to add `':g'` at the end of the classname.
This tells plugin not to transform these classes and keep them as is:

```jsx
import "./m1.module.css"

function Component() {
return <h1 className="foo bar:g baz"> .... </h1>
return <h1 className="foo bar:g baz"> ... </h1>
}
```

Expand All @@ -113,25 +126,26 @@ function Component() {
import _style from "./m1.module.css"

function Component() {
return <h1 className={`${_style["foo"]} bar ${_style["baz"]}`}> .... </h1>
return <h1 className={`${_style["foo"]} bar ${_style["baz"]}`}> ... </h1>
}
```

In this example, `'bar'` might be declared in the global stylesheet while `'foo'` and `'baz'` are scoped to the imported module.
In this example, `'bar'` might be declared in the global style-sheet, while `'foo'` and `'baz'` are
scoped to the imported css module.


*The transformed code will use object indexing instead of dot-notation, this helps us to use dashes within our class names (eg. `className="foo-bar baz"`) or else, we would have to use camel-case pattern while using css classes.*
## Usage With Already Imported CSS-Module

## Usage With Already Imported CSS-Module
If you are already using CSS-Modules, the plugin will transform string (containing classnames)
that is given to any `className` attr. For example:

If you were already been using css-module with style objects, the plugin will see it and transform other css-classes accordingly.
for example:
```jsx
import style from "./component.module.css"

function Component() {
return (
<div className={style.foo}>
<h1 className="bar baz"> .... </h1>
<div className={style.foo}>
<h1 className="bar baz"> ... </h1>
</div>
)
}
Expand All @@ -143,47 +157,51 @@ import style from "./component.module.css"

function Component() {
return (
<div className={style.foo}>
<h1 className={`${style["bar"]} ${style["baz"]}`}> .... </h1>
<div className={style.foo}>
<h1 className={`${style["bar"]} ${style["baz"]}`}> ... </h1>
</div>
)
}
```


# Introducing Named CSS-Modules

In most cases, we would be using single css-module inside our components but sometimes
it might make sense to import bunch of css-modules and use them together.
In most cases, we would be using single CSS-Module inside a component but sometimes,
It might make sense to create reusable CSS-Modules and apply them in multiple different components.

We can give names to our css-module imports, and then use it to apply specific css classes from different modules

eg. we can import two module and use them like:
In order to work with named CSS-Modules, we need to give names to each css-module import
by adding `:<module-name>` at the end of the path:

```jsx
// original

import "./layout.module.css:layout"
import "./component.module.css:comp"
import "./component.module.css:com"
```

To access CSS-Module class, simply add `:<module-name>` at the end of the classname that specifies which CSS-Module
to use for the class:

```jsx
function Component() {
return (
<div className="foo:layout bar:comp baz:layout">
<h1 className="grid-1:layout"> ... </h1>
</div>
<ul className="food-items:layout">
<li className="food-item:com"> ... </li>
<li className="food-item:com"> ... </li>
</ul>
)
}
```
Transformed code would look like this:

// modified

```jsx
import _layout from "./layout.module.css"
import _comp from "./component.module.css"
import _com from "./component.module.css"

function Component() {
return (
<div className={`${_layout["foo"]} ${_comp["bar"]} ${_layout["baz"]}`}>
<h1 className={`${_layout["grid-1"]}`}></h1>
</div>
<ul className={`${_layout["food-items"]}`}>
<li className={`${_com["food-item"]}`}> ... </li>
<li className={`${_com["food-item"]}`}> ... </li>
</ul>
)
}
```

0 comments on commit ceae302

Please sign in to comment.