|
1 | | -# React CDK |
| 1 | +# React-CDK v.3 |
2 | 2 |
|
3 | | -### Component Development Kit for React |
| 3 | +This branch is under development. Any help with code review, bug reporting/fixes, ideas, wishes, objections, PR creation, docs writing is very appreciated! If you are interested, please contact us in the [Storybook Slack](https://now-examples-slackin-nqnzoygycp.now.sh/). |
4 | 4 |
|
5 | | -##### We are looking for an active maintainer for this repository. React CDK has been put on hold and may become deprecated in the future so our core team can focus on Storybook. If you are interested, please contact Norbert in the Storybook Slack. |
6 | | - |
7 | | -React CDK is not just another React boilerplate. With React CDK, you can focus on developing your React component or utility while React CDK takes care of all the other stuff. |
8 | | - |
9 | | -> Read why [Kadira created React CDK](https://voice.kadira.io/say-hello-to-react-cdk-97cff692e798#.2aaodkb6c). |
10 | | -
|
11 | | -React CDK comes with following features: |
12 | | - |
13 | | -* Create a project with a single command. |
14 | | -* Write your component in [ES2016+ syntax](https://www.npmjs.com/package/babel-preset-react-app). |
15 | | -* Develop in a live environment with [React Storybook](https://github.com/kadirahq/react-storybook/). |
16 | | -* Write tests with Mocha and [Enzyme](https://github.com/airbnb/enzyme). |
17 | | -* Use ESLint with the [Airbnb style guide](https://github.com/airbnb/javascript). |
18 | | -* Publish correctly transpiled code into NPM. |
19 | | -* Deploy your storybook to GitHub Pages. |
20 | | -* Get **updates** to core building tools. |
21 | | - |
22 | | -## TOC |
23 | | - |
24 | | -* [Getting Started](#getting-started) |
25 | | -* [Developing Your Component](#developing-your-component) |
26 | | -* [Testing](#testing) |
27 | | -* [Lint Rules](#lint-rules) |
28 | | -* [Publishing](#publishing) |
29 | | -* [Deploying Storybook](#deploying-storybook) |
30 | | -* [CSS and Styles](#css-and-styles) |
31 | | -* [Updating Your Component with React CDK](#updating-your-component-with-react-cdk) |
32 | | -* [Customizing the Component](#customizing-the-component) |
33 | | - |
34 | | -## Getting Started |
35 | | - |
36 | | -Install React CDK with the following command: |
37 | | - |
38 | | -``` |
39 | | -npm install -g yo generator-react-cdk |
40 | | -``` |
41 | | - |
42 | | -> React CDK comes as a [yeoman](http://yeoman.io/) generator, which allows you to scaffold your component quickly. |
43 | | -
|
44 | | - |
45 | | -Then, create your first component library with the following command: |
46 | | - |
47 | | -``` |
48 | | -yo react-cdk react-wizard |
49 | | -``` |
50 | | - |
51 | | - |
52 | | - |
53 | | -> React CDK will create a directory called react-wizard with all the files you need to get started. |
54 | | -
|
55 | | - |
56 | | -Visit that directory and install the NPM dependencies: |
57 | | - |
58 | | -``` |
59 | | -cd react-wizard |
60 | | -npm install |
61 | | -``` |
62 | | - |
63 | | -By default, this project contains a simple button created with React. It also includes tests and [React Storybook](https://github.com/kadirahq/react-storybook/) stories so you can get ideas for writing your own stories. |
64 | | - |
65 | | -## Developing Your Component |
66 | | - |
67 | | -Now we need to work with the component. Your component lives under the src directory. Open `src/index.js` in your favorite editor and start developing. |
68 | | - |
69 | | -Now, it’s time to start the Storybook so we can see what we are building: |
70 | | - |
71 | | -``` |
72 | | -npm run storybook |
73 | | -``` |
74 | | - |
75 | | -The above command starts the Storybook console on [http://localhost:9010](http://localhost:9010/). |
76 | | - |
77 | | - |
78 | | - |
79 | | -> You can see changes you make while you are editing your component. Visit [React Storybook](https://github.com/kadirahq/react-storybook/) repo to learn more. |
80 | | -
|
81 | | - |
82 | | -You can write your component in ES2015+ syntax. It supports `react` and `babel-stage2` presets. |
83 | | - |
84 | | -## Testing |
85 | | - |
86 | | -You can write your tests inside the `src/tests` directory. By default, the project comes with two test cases demonstrating how to write tests. React CDK configures your component with Mocha, [Enzyme](https://github.com/airbnb/enzyme), jsdom, and other essential JS testing tools. |
87 | | - |
88 | | -This is the ideal way to write React tests. |
89 | | - |
90 | | -You can run tests with the following commands: |
91 | | - |
92 | | -* `npm run testonly` (run tests once) |
93 | | -* `npm run test-watch` (run tests and watch for changes) |
94 | | -* `npm test` (run tests and apply lint rules) |
95 | | - |
96 | | -## Lint Rules |
97 | | - |
98 | | -Your project is configured with ESLint based on the [Airbnb JavaScript style guide](https://github.com/airbnb/javascript) with some minor changes. |
99 | | - |
100 | | -You can apply lint rules with the following commands: |
101 | | - |
102 | | -* `npm run lint` (apply lint rules) |
103 | | -* `npm run lintfix` (apply lint rules and fix some common issues) |
104 | | - |
105 | | -## Publishing |
106 | | - |
107 | | -Now it’s time to publish your component to NPM. Before you publish, make sure you’ve customized the following files as necessary: |
108 | | - |
109 | | -* package.json |
110 | | -* README.md |
111 | | -* CONTRIBUTE.md |
112 | | -* LICENSE |
113 | | - |
114 | | -If everything is okay, simply publish your component to NPM with the following command: |
115 | | - |
116 | | -``` |
117 | | -npm publish |
118 | | -``` |
119 | | - |
120 | | -This command will transpile your component for ES5 before publishing it to NPM. Your component will work on any JavaScript environment. |
121 | | - |
122 | | -## Deploying Storybook |
123 | | - |
124 | | -You will usually write your stories while you are developing your component. That allows you to use your storybook as a living document. You could show what your component looks like and different ways to use it. |
125 | | - |
126 | | -Then you can simply deploy it to GitHub Pages with the following command: |
127 | | - |
128 | | -``` |
129 | | -npm run publish-storybook |
130 | | -``` |
131 | | - |
132 | | -You can link your Storybook URL inside the README file. |
133 | | - |
134 | | -Here’s a [sample component](https://github.com/kadira-samples/react-button) listing a Storybook URL. |
135 | | - |
136 | | - |
137 | | -> You can also publish your storybook automatically when you publish your component to NPM. To do that, simply add the following NPM script to your package.json file: |
138 | | -
|
139 | | -```js |
140 | | -{ |
141 | | - "scripts": { |
142 | | - ... |
143 | | - "postpublish": "npm run publish-storybook" |
144 | | - ... |
145 | | - } |
146 | | -} |
147 | | -``` |
148 | | - |
149 | | -## CSS and Styles |
150 | | - |
151 | | -It’s common to include CSS and Styles with your component. There are many ways to do this. Some prefer to write CSS in JS, while some provide a CSS file that lives inside the repo. |
152 | | - |
153 | | -### CSS in JS |
154 | | - |
155 | | -With this approach, you don’t need to configure anything. You can just use it. However, you should make sure you accept some external styles, which allows the end user to change the look and feel of your component as needed. |
156 | | - |
157 | | -### Plain old CSS files |
158 | | - |
159 | | -If you are following this approach, make sure to place your CSS files inside the root of your component and not inside the src directory. Then, your end users can import it like this: |
160 | | - |
161 | | -```js |
162 | | -import 'my-comp/style.css' |
163 | | -``` |
164 | | - |
165 | | -You may also need to load this style sheet inside your stories. Simply import the above style sheet into src/stories/index.js with the following command: |
166 | | - |
167 | | -``` |
168 | | -import '../../style.css' |
169 | | -``` |
170 | | - |
171 | | -## Updating Your Component with React CDK |
172 | | - |
173 | | -This is a plain NPM module without any magic. However, it’s written in a way that allows us to push updates to your repo. |
174 | | - |
175 | | -You never need to worry about updating dependencies and build tools. React CDK will take care of that. |
176 | | - |
177 | | -First, update React CDK with the following command: |
178 | | - |
179 | | -``` |
180 | | -npm install -g generator-react-cdk |
181 | | -``` |
182 | | - |
183 | | -Then, visit your project and apply the following command: |
184 | | - |
185 | | -``` |
186 | | -yo react-cdk:update |
187 | | -``` |
188 | | - |
189 | | -This will update the core build tools and the package.json file for dependencies. |
190 | | - |
191 | | - |
192 | | -> It won’t update dependencies you’ve added; it will only update the dependencies and NPM script React CDK has added. |
193 | | -
|
194 | | -## Customizing the Component |
195 | | - |
196 | | -Since your component is a plain NPM module, you can customize it any way you want. Here are some ways to do so: |
197 | | - |
198 | | -### Add dependencies |
199 | | - |
200 | | -You can add dependencies to the `package.json` file as needed. |
201 | | - |
202 | | -### Change the JavaScript environment |
203 | | - |
204 | | -Sometimes you may want to use cutting-edge JavaScript features. You can simply add the necessary Babel preset and change the `.babelrc` file. |
205 | | - |
206 | | -### Change other dotfiles |
207 | | - |
208 | | -You can change any of the dotfiles, including `.gitignore` and `.npmignore`. |
209 | | - |
210 | | -### Customize Storybook |
211 | | - |
212 | | -Sometimes you may need to customize your React Storybook. If you do, you’ll usually customize the `.storybook/webpack.config.js` file. Go ahead and do it. |
213 | | - |
214 | | -### Add some pre-publish code |
215 | | - |
216 | | -React CDK already uses the NPM `pre-publish` hook, so you won’t be able to use it directly. Instead, you can use `.scripts/user/prepublish.sh` to add your own code. |
217 | | - |
218 | | -### Configure test utilities |
219 | | - |
220 | | -We have included JSDOM(to support enzyme's [full DOM rendering](https://github.com/airbnb/enzyme/blob/master/docs/api/mount.md)) and Babel configurations before running Mocha tests. If you want to add more stuff, simply use the `.scripts/user/pretest.js` file. |
221 | | - |
222 | | -### Configure something else |
223 | | - |
224 | | -You can configure this project in many ways. Give it a try, and I bet you can do it without our help. If you need help from the core React CDK tools, just create [an issue](https://github.com/kadirahq/react-cdk/issues). |
| 5 | +See [Roadmap](ROADMAP.md) |
0 commit comments