Skip to content

Commit 1388ae8

Browse files
ezhloboForbesLindesay
ezhlobo
authored and
ForbesLindesay
committed
Improve Documentation (#46)
1 parent 01caafa commit 1388ae8

1 file changed

Lines changed: 183 additions & 99 deletions

File tree

‎README.md‎

Lines changed: 183 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,145 +1,229 @@
1-
# babel-plugin-transform-react-pug
1+
# babel-plugin-transform-react-pug [![npm version](https://img.shields.io/npm/v/babel-plugin-transform-react-pug.svg)](https://www.npmjs.com/package/babel-plugin-transform-react-pug)
22

3-
The official means by which you can use pug in your react components, replaces the use of react-jade when moving to pug.
3+
Use Pug templates to write react components.
44

5-
This plugin transforms the pug inside of your react components.
5+
`babel-plugin-transform-react-pug` is a plugin for babel which transpiles pug syntax within template literals to jsx.
66

7-
## Installation
7+
Write your components this way:
8+
9+
```jsx
10+
export default const ReactComponent = props => pug`
11+
.wrapper
12+
if props.shouldShowGreeting
13+
p.greeting Hello World!
14+
15+
button(onClick=props.notify) Click Me
16+
`
817
```
9-
npm install babel-plugin-transform-react-pug --save-dev
10-
npm install babel-plugin-transform-react-jsx --save-dev
18+
19+
And it will be transpiled into:
20+
21+
```jsx
22+
export default const ReactComponent = props => (
23+
<div className="wrapper">
24+
{props.shouldShowGreeting && (
25+
<p className="greeting">Hello World</p>
26+
)}
27+
<button onClick={props.notify}>Click Me</button>
28+
</div>
29+
)
1130
```
31+
32+
* [Usage](#usage)
33+
* [Syntax](#syntax)
34+
* [Eslint integration](#eslint-integration)
35+
* [CSS Modules](#css-modules)
36+
* [Install](#install)
37+
* [create-react-app](#create-react-app)
38+
* [React Native](#react-native)
39+
* [How it works](#how-it-works)
40+
* [Limitations](#limitations)
41+
* [FAQ](#faq)
42+
* [Can I import template from other files?](#can-i-import-template-from-other-files)
43+
* [How to get syntax highlighting in IDE (or text editors)?](#how-to-get-syntax-highlighting-in-ide-or-text-editors)
44+
* [License](#license)
45+
1246
## Usage
13-
.babelrc
14-
```js
15-
{
16-
"plugins": [
17-
"transform-react-pug",
18-
"transform-react-jsx"
19-
]
20-
}
47+
48+
### Syntax
49+
50+
Full information of the syntax you can find in official documentation: [pugjs.org](https://pugjs.org/).
51+
52+
#### Basic example
53+
54+
```jsx
55+
const Component = props => pug` //- const Component = props => (
56+
div //- <div>
57+
if props.amount > MAX_AMOUNT //- {props.amount > MAX_AMOUNT ? (
58+
OtherComponent(fluid crucial) //- <OtherComponent fluid crucial />
59+
else //- ) : (
60+
p You can set bigger amount ;) //- <p>You can set bigger amount ;)</p>
61+
//- )}
62+
each item, index in props.items //- {props.items.map((item, index) => (
63+
div(key=item.id) //- <div key={item.id}>
64+
h3 Header #{index + 1} //- <h3>Header {index + 1}</h3>
65+
= item.body //- {item.body}
66+
//- </div>
67+
//- )}
68+
//- </div>
69+
//- )
70+
`;
71+
```
72+
73+
#### How to pass functions and other primitives
74+
75+
```jsx
76+
const Component = props => pug` //- const Component = props => (
77+
div //- <div>
78+
button( //- <button
79+
type="button" //- type="button"
80+
onClick=props.onClick //- onClick={props.onClick}
81+
) Click Me //- >Click Me</button>
82+
//-
83+
OtherComponent( //- <OtherComponent
84+
...props.objectWithPropsForChild //- {...props.objectWithPropsForChild}
85+
fluid //- fluid
86+
data-array=[1, 2, 3] //- data-array={[1, 2, 3]}
87+
) //- />
88+
//- </div>
89+
//- )
90+
`;
91+
```
92+
93+
#### Define local variables and use javascript in attributes
94+
95+
```jsx
96+
const Component = props => pug` //- const Component = props => (
97+
Fragment //- <Fragment>
98+
button( //- <button
99+
...one //- {...one}
100+
...two //- {...two}
101+
onClick=() => alert('Hello') //- onClick={() => alert('Hello')}
102+
text='number ' + 10 //- text={'number ' + 10}
103+
) //- ></button>
104+
//-
105+
- const variable = format(props.no) //-
106+
p Variable is #{variable} //- <p>Variable is {format(props.no)}</p>
107+
//- </Fragment>
108+
//- )
109+
`;
110+
```
111+
112+
#### Interpolation
113+
114+
If you'd prefer to use interpolation, you can. This is possible by using `${}` within your template.
115+
116+
```jsx
117+
const Component = props => pug`
118+
ul(className=${props.modifier})
119+
${props.items.map((item, index) => pug`li(key=${index}) ${item}`)}
120+
`;
21121
```
22122

23123
### Eslint integration
24124

25-
Install [eslint-plugin-react-pug](https://github.com/ezhlobo/eslint-plugin-react-pug) to be compatible with [eslint-plugin-react](https://github.com/yannickcr/eslint-plugin-react).
125+
Install [eslint-plugin-react-pug](https://github.com/ezhlobo/eslint-plugin-react-pug) if you use [eslint-plugin-react](https://github.com/yannickcr/eslint-plugin-react).
26126

27-
### Syntax Highlighting in Atom
127+
### CSS Modules
28128

29-
1. Install [language-babel](https://atom.io/packages/language-babel) and [language-pug-jade](https://atom.io/packages/language-pug-jade)
129+
It's not supported well yet.
30130

31-
*I suggest language-pug-jade because it works better for me. But there are more approaches for building pugjs grammar: [language-pug](https://atom.io/packages/language-pug) and [atom-pug](https://atom.io/packages/atom-pug), and you can try them too.*
32-
33-
3. Open settings of language-babel in atom
34-
4. Find the field under "JavaScript Tagged Template Literal Grammar Extensions"
35-
5. Enter: `pug:source.pug`
131+
## Install
36132

37-
More details: [gandm/language-babel#javascript-tagged-template-literal-grammar-extensions](https://github.com/gandm/language-babel#javascript-tagged-template-literal-grammar-extensions)
133+
1. Install via yarn or npm
38134

39-
6. Restart the atom
135+
```
136+
yarn add --dev babel-plugin-transform-react-pug
137+
```
40138
41-
## Examples
139+
```
140+
npm install --save-dev babel-plugin-transform-react-pug
141+
```
42142
43-
### Example 1 - Basic Example
143+
2. Add to babel configuration before transpiling jsx (usually in `.babelrc`)
44144
45-
You can now create a react component with your pug inside it.
145+
```
146+
{
147+
"plugins": [
148+
"transform-react-pug",
149+
"transform-react-jsx"
150+
]
151+
}
152+
```
46153
47-
```js
48-
import React from 'react';
154+
3. Now all your templates written with pug are understood by react and browsers.
49155
50-
class MyComponent extends React.Component {
156+
### create-react-app
51157
52-
render() {
53-
return pug`
54-
div
55-
h1 My Component
56-
p This is my component using pug.
57-
`;
58-
}
59-
}
60-
```
158+
Integrating with [create-react-app][link to cra] is tricky because it does not allow you to modify babel configuration. There are two documented possibilities:
159+
160+
* [eject][link to cra eject]
61161
62-
### Example 2 - Re-using a Pug Component
162+
That is easy, you will get `.babelrc` file in your root directory, just add `transform-react-pug` before `transform-react-jsx` there.
63163
64-
You can use a pug component in another component.
164+
* [react-app-rewired][link to rewired cra]
65165
66-
```js
67-
import React from 'react';
68-
import MyComponent from './my-component'
166+
Go through official instruction to rewire your application. Then modify your `config-overrides.js`:
69167
70-
class MyNewComponent extends React.Component {
168+
```diff
169+
+ const {injectBabelPlugin} = require('react-app-rewired');
170+
module.exports = function override(config, env) {
171+
- //do stuff with the webpack config...
172+
+ config = injectBabelPlugin('transform-react-pug', config);
173+
return config;
174+
}
175+
```
71176

72-
render() {
177+
[link to cra]: https://github.com/facebook/create-react-app/
178+
[link to cra eject]: https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#npm-run-eject
179+
[link to rewired cra]: https://github.com/timarney/react-app-rewired#1-injectbabelplugin
73180

74-
const prop1 = 'This is something to pass to another component';
181+
### React Native
75182

76-
return pug`
77-
div
78-
h1 MyNewComponent
79-
p This component imports my other component.
80-
p It could import several of these within the pug.
81-
MyComponent
183+
Just add this plugin to the list in `.babelrc` file.
82184

83-
p If I had created a component with props I could pass them from this component.
84-
AComponentExpectingProps(
85-
prop1 = prop1
86-
)
87-
`
185+
```diff
186+
{
187+
- "presets": ["react-native"]
188+
+ "presets": ["react-native"],
189+
+ "plugins": ["transform-react-pug"]
88190
}
89-
}
90191
```
91192

92-
### Example 3 - Creating a Pug Constant
193+
_We don't need `transform-react-jsx` here because it's coming with `react-native` preset._
93194

94-
You can create a pug constant that you can simply re-use in your code.
195+
## How it works
95196

96-
```js
97-
import React from 'react';
197+
_Coming soon..._
98198

99-
class MyComponent extends React.Component {
199+
## Limitations
100200

101-
_onDoOneThing = () => {
102-
console.dir('Do one thing');
103-
};
201+
* We can't use dots in component names because pugjs treats everything after dot as a className. For example, `React.Fragment` becomes `<React className="Fragment" />`, not `<React.Fragment />`
104202

105-
_onDoAnotherThing = () => {
106-
console.dir('Do Another thing');
107-
};
203+
## FAQ
108204

109-
render() {
205+
### Can I import template from other files?
110206

111-
const myButtons = pug`
112-
div
113-
button(onClick=this._onDoOneThing) Do One Thing
114-
= ' '
115-
button(onClick=this._onDoAnotherThing) Do Another Thing
116-
`;
207+
No.
117208

118-
return pug`
119-
div
120-
h1 MyComponent
121-
p this component uses buttons from my constant.
122-
div
123-
= myButtons
124-
`
125-
}
126-
}
127-
```
209+
_Coming soon..._
128210

129-
### Example 4 - Using interpolation in your Pug Component
211+
### How to get syntax highlighting in IDE (or text editors)?
130212

131-
If you'd prefer to use interpolation, you can! This is possible by using `${ }` within your template.
213+
Here is an instruction for Atom text editor.
132214

133-
This lets you benefit from syntax highlighting and linting!
215+
1. Install [language-babel](https://atom.io/packages/language-babel) and [language-pug-jade](https://atom.io/packages/language-pug-jade)
134216

135-
```js
136-
import React from 'react';
217+
_I suggest language-pug-jade because it works better for me. But there are more approaches for building pugjs grammar: [language-pug](https://atom.io/packages/language-pug) and [atom-pug](https://atom.io/packages/atom-pug), and you can try them too._
137218

138-
const List = (props) => {
139-
return pug`
140-
ul.list(className=${ props.modifier })
141-
${ props.items.map((item, index) => pug`li.list__item(key=${ index }) ${ item }` ) }
142-
`
143-
}
144-
```
219+
2. Open settings of language-babel in atom
220+
3. Find the field under "JavaScript Tagged Template Literal Grammar Extensions"
221+
4. Enter: `pug:source.pug`
222+
223+
More details: [gandm/language-babel#javascript-tagged-template-literal-grammar-extensions](https://github.com/gandm/language-babel#javascript-tagged-template-literal-grammar-extensions)
224+
225+
5. Restart the atom
226+
227+
## License
145228

229+
MIT

0 commit comments

Comments
 (0)