You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+9-72Lines changed: 9 additions & 72 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,26 +1,27 @@
1
1
# react-modern-library-boilerplate
2
2
3
-
> Boilerplate for publishing modern React modules with Rollup and example usage via create-react-app.
3
+
> Boilerplate and [CLI](https://github.com/transitive-bullshit/react-modern-library-cli)for publishing modern React modules with Rollup and example usage via create-react-app.
We strongly recommend that you use the accompanying [CLI](https://github.com/transitive-bullshit/react-modern-library-cli) to create new modules based off of this boilerplate.
12
12
13
13
**The purpose of this boilerplate is to make publishing your own React components as simple as possible.**
14
14
15
15
## Features
16
16
17
17
There are some existing React library boilerplates, but none of them fulfilled the following goals which we set out to accomplish:
18
18
19
+
- Comes with an easy-to-use [CLI](https://github.com/transitive-bullshit/react-modern-library-cli) for creating new modules
19
20
- Support all modern JS language features for component development out of the box
20
21
- Build process to convert source to `umd` and `es` module formats for publishing to npm
21
22
- Comes with an `example` app using a standard [create-react-app](https://github.com/facebookincubator/create-react-app), serving 2 purposes
22
23
- Local, hot-reload server for developing your module
23
-
- Easily publishable to *github pages* so users can quickly play with your module (or [surge.sh](http://surge.sh/) or [now.sh](https://zeit.co/now))
24
+
- Easily publishable to github pages so users can quickly play with your module
24
25
- Use [Rollup](https://rollupjs.org/) for build process and [Babel](https://babeljs.io/) for transpilation
25
26
- See the [blog post](https://hackernoon.com/publishing-baller-react-modules-2b039d84bce7) for an explanation of Rollup vs Webpack
26
27
- Allow the use of `npm` modules within your library, either as dependencies or peer-dependencies
@@ -30,79 +31,15 @@ There are some existing React library boilerplates, but none of them fulfilled t
30
31
- Sourcemap creation enabled by default
31
32
- Thorough documentation written by someone who cares :heart_eyes:
32
33
33
-
## Walkthrough
34
+
## Usage
34
35
35
-
Check out the accompanying [blog post](https://hackernoon.com/publishing-baller-react-modules-2b039d84bce7) which gives more in-depth explanations on how to create an example component using this boilerplate.
36
+
We strongly recommend that you use the accompanying [CLI](https://github.com/transitive-bullshit/react-modern-library-cli)to create new modules.
36
37
37
-
On this page, we'll give a quick rundown of the essential steps.
38
-
39
-
#### Getting Started
40
-
41
-
The first step is to clone this repo and rename / replace all boilerplate names to match your custom module. In this example, we'll be creating a module named `react-poop-emoji`.
# replace boilerplate placeholders with your module-specific values
53
-
# NOTE: feel free to use your favorite find & replace method instead of sed
54
-
mv README.template.md README.md
55
-
sed -i 's/react-modern-library-boilerplate/react-poop-emoji/g'*.{json,md} src/*.js example/*.json example/src/*.js example/public/*.{html,json}
56
-
sed -i 's/transitive-bullshit/your-github-username/g' package.json example/package.json
57
-
```
58
-
59
-
#### Local Development
60
-
61
-
Now you're ready to run a local version of rollup that will watch your `src/` component and automatically recompile it into `dist/` whenever you make changes.
62
-
63
-
```bash
64
-
# run example to start developing your new component against
65
-
npm link # the link commands are important for local development
66
-
npm install # disregard any warnings about missing peer dependencies
67
-
npm start # runs rollup with watch flag
68
-
```
69
-
70
-
We'll also be running our `example/` create-react-app that's linked to the local version of your `react-poop-emoji` module.
71
-
72
-
```bash
73
-
# (in another tab)
74
-
cd example
75
-
npm link react-poop-emoji
76
-
npm install
77
-
npm start # runs create-react-app dev server
78
-
```
79
-
80
-
Now, anytime you make a change to your component in `src/` or to the example app's `example/src`, `create-react-app` will live-reload your local dev server so you can iterate on your component in real-time.
81
-
82
-
#### NPM Stuffs
83
-
84
-
The only difference when publishing your component to **npm** is to make sure you add any npm modules you want as peer dependencies are properly marked as `peerDependencies` in `package.json`. The rollup config will automatically recognize them as peer dependencies and not try to bundle them in your module.
85
-
86
-
Then publish as per usual.
87
-
88
-
```bash
89
-
# note this will build `commonjs` and `es`versions of your module to dist/
90
-
npm publish
91
-
```
92
-
93
-
#### Github Pages
94
-
95
-
Deploying the example to github pages is simple. We create a production build of our example `create-react-app` that showcases your library and then run `gh-pages` to deploy the resulting bundle. This can be done as follows:
96
-
97
-
```bash
98
-
npm run deploy
99
-
```
100
-
101
-
Note that it's important for your `example/package.json` to have the correct `homepage` property set, as `create-react-app` uses this value as a prefix for resolving static asset URLs.
38
+
If you'd prefer to setup a new module manually, check out the introductory [blog post](https://hackernoon.com/publishing-baller-react-modules-2b039d84bce7) and the old [manual guide](https://raw.githubusercontent.com/transitive-bullshit/react-modern-library-boilerplate/master/manual.md).
102
39
103
40
## Examples
104
41
105
-
Here is an example react module created from this guide: [react-background-slideshow](https://github.com/transitive-bullshit/react-background-slideshow), a sexy tiled background slideshow for React. It comes with an example create-react-app hosted on github pages and should give you a good idea of the type of module you’ll be able to create starting from this boilerplate.
42
+
Here is an example react module created from this boilerplate: [react-background-slideshow](https://github.com/transitive-bullshit/react-background-slideshow), a sexy tiled background slideshow for React. It comes with an example create-react-app hosted on github pages.
This guide is for people who don't want to use the accompanying [CLI](https://github.com/transitive-bullshit/react-modern-library-cli).
4
+
5
+
Check out the accompanying [blog post](https://hackernoon.com/publishing-baller-react-modules-2b039d84bce7) which gives more in-depth explanations on how to create an example component using this boilerplate.
6
+
7
+
On this page, we'll give a quick rundown of the essential steps.
8
+
9
+
#### Getting Started
10
+
11
+
The first step is to clone this repo and rename / replace all boilerplate names to match your custom module. In this example, we'll be creating a module named `react-poop-emoji`.
# replace boilerplate placeholders with your module-specific values
23
+
# NOTE: feel free to use your favorite find & replace method instead of sed
24
+
mv README.template.md README.md
25
+
sed -i 's/react-modern-library-boilerplate/react-poop-emoji/g'*.{json,md} src/*.js example/*.json example/src/*.js example/public/*.{html,json}
26
+
sed -i 's/transitive-bullshit/your-github-username/g' package.json example/package.json
27
+
```
28
+
29
+
#### Local Development
30
+
31
+
Now you're ready to run a local version of rollup that will watch your `src/` component and automatically recompile it into `dist/` whenever you make changes.
32
+
33
+
```bash
34
+
# run example to start developing your new component against
35
+
npm link # the link commands are important for local development
36
+
npm install # disregard any warnings about missing peer dependencies
37
+
npm start # runs rollup with watch flag
38
+
```
39
+
40
+
We'll also be running our `example/` create-react-app that's linked to the local version of your `react-poop-emoji` module.
41
+
42
+
```bash
43
+
# (in another tab)
44
+
cd example
45
+
npm link react-poop-emoji
46
+
npm install
47
+
npm start # runs create-react-app dev server
48
+
```
49
+
50
+
Now, anytime you make a change to your component in `src/` or to the example app's `example/src`, `create-react-app` will live-reload your local dev server so you can iterate on your component in real-time.
The only difference when publishing your component to **npm** is to make sure you add any npm modules you want as peer dependencies are properly marked as `peerDependencies` in `package.json`. The rollup config will automatically recognize them as peer dependencies and not try to bundle them in your module.
57
+
58
+
Then publish as per usual.
59
+
60
+
```bash
61
+
# note this will build `commonjs` and `es`versions of your module to dist/
62
+
npm publish
63
+
```
64
+
65
+
#### Github Pages
66
+
67
+
Deploying the example to github pages is simple. We create a production build of our example `create-react-app` that showcases your library and then run `gh-pages` to deploy the resulting bundle. This can be done as follows:
68
+
69
+
```bash
70
+
npm run deploy
71
+
```
72
+
73
+
Note that it's important for your `example/package.json` to have the correct `homepage` property set, as `create-react-app` uses this value as a prefix for resolving static asset URLs.
74
+
75
+
## Examples
76
+
77
+
Here is an example react module created from this guide: [react-background-slideshow](https://github.com/transitive-bullshit/react-background-slideshow), a sexy tiled background slideshow for React. It comes with an example create-react-app hosted on github pages and should give you a good idea of the type of module you’ll be able to create starting from this boilerplate.
78
+
79
+
### Multiple Named Exports
80
+
81
+
Here is a [branch](https://github.com/transitive-bullshit/react-modern-library-boilerplate/tree/feature/multiple-exports) which demonstrates how to create a module with multiple named exports. The module in this branch exports two components, `Foo` and `Bar`, and shows how to use them from the example app.
82
+
83
+
### Material-UI
84
+
85
+
Here is a [branch](https://github.com/transitive-bullshit/react-modern-library-boilerplate/tree/feature/material-ui) which demonstrates how to create a module that makes use of a relatively complicated peer dependency, [material-ui](https://github.com/mui-org/material-ui). It shows the power of [rollup-plugin-peer-deps-external](https://www.npmjs.com/package/rollup-plugin-peer-deps-external) which makes it a breeze to create reusable modules that include complicated material-ui subcomponents without having them bundled as a part of your module.
0 commit comments