A shared set of UI Components using React and CSS Modules.
Install the package and save the exact version:
npm install @bufferapp/components -SE
Now in your code you can import a specific component:
For the component library you're required to use a few plugins and a valid Webpack config.
First, you'll need React installed (0.14 or newer):
npm i react react-dom -SE
In addition to your Babel configuration (not documented), you'll need the style-loader Webpack plugin:
npm i style-loader -SDE
Your Webpack config should use the proper config, here is an example:
moduleexports =module:loaders:test: /\.css$/loaders:'style-loader';
Install Node Modules
Start React Storybook
Run Linter And Test
npm run test
Run Test and watch for changes
npm run test-watch
Update Test Snapshots
npm run test-update
Note: only commit these if you have manually inspected them with a story
src/ # root +-- MyComponent/ # component root `-- index.js # component display logic `-- story.js # storybook entry
Considered patch release
Can upgrade without changes to the codebase
- Add a component
- Add a new prop to a component
Considered minor release
An upgrade would require a code change to work
- Remove a component
- Remove a prop
Considered major release
- Major milestone achieved (i.e a complete set of components)
- Complete re-skinning of components
- Up for debate
What is a component
In the current implementation components are all functional and stateless.
This means that UI is a function of state since we're using pure functions to build our views.
UI = f(state)
How do I determine the scope of a component
This is a tough question, it really depends. But as a general rule, a component should be simple enough to be reusable across multiple applications and be not much longer than 150 lines of code. This is a good one to seek advice if you're not sure.
What's the development workflow look like?
Note: this is a way to do this, but not necessarily the way to build components. For this workflow let's create a component called
- Create a branch with the name of the new component
Note: also make sure you're up to date
git checkout master git pull -r git checkout -b task/add-newcomponent
- Install dependencies and start the storybook
npm i && npm start
open http://localhost:9001 in your browser
- Create a
src(see Component Anatomy)
src/ +-- NewComponent/
- Create a story for the
src/ +-- NewComponent/ `-- story.js
populate story.js with a default story
Now when you look at Storybook you should see a broken story (red screen)
- Implement your component
src/ +-- NewComponent/ `-- story.js `-- index.js
populate index.js with the new component
;;const NewComponent =<divstyle=>NewComponent</div>;;
- Run the test for the first time
It's important to note that this creates a snapshot of the component. All tests ran in the future will be tested against this snapshot to ensure they haven't changed.
- Commit it!
git add .git commit -m "Add NewComponent"git push -u origin task/add-newcomponent
At this point it's a good idea to generate a PR on github :)
How do I write tests for a component?
This automatically happens when you write stories. They are tested with jest snapshots under the hood.
Since components are functional and stateless we can use snapshot testing to get complete coverage.
You're verifying that each property change has the expected outcome in HTML.
The first time the test is run it generates a new snapshot. The second time it's checked against the snapshot.
How Do I Update A Snapshot
npm run test-update
How do determine what a component does?
There's a pattern you can follow
- Look at the Component.propTypes section
- This is essentially the API of the component
- Look at the render function
- Look at any helper functions
- Ask one of the contributors :)