building open-source react components
TRANSCRIPT
Zack Argyle
Building Open SourceReact Components
1
2
3
4
Just a guy that loves software and his kid, but mostly software.Introduction
PlaystationJavascript Engineer
HarmanAudio Hardware Engineer
VerisageSoftware Consulting
PinterestFull-Stack Engineer
San MateoDad
Twitter:@zackargyle
Github:github.com/zackargyle
Medium:medium.com/@zackargyle/
6
react-pinterest
Confidential 7
Building Your Component
8
What’s on the Agenda?
9
1. Building the component2. Open sourcing to Github3. Publishing to NPM
Building the Component
10
• PropTypes + DefaultProps
• Tests• Linting• README.md• Example usage
• Lightweight• Encapsulated• Stateless (if possible)• Performant• Minimal dependencies
PropTypes + DefaultProps
11
The bane of every open-source developer’s existence is argument validation.
• Ain’t nobody got time to add hundreds of lines of validation to make sure people are putting the right crap in the right spots
• Be specific Bad
• PropTypes.array Good
• PropTypes.arrayOf(PropTypes.number)• Add .isRequired for all required properties• Add a defaultProp value for all non-required properties• Comment about what the prop does in either the class documentation (@prop) or at the
PropType declaration.
PropTypes are Elegant
12
Testing
13
When contributors make changes, good tests will give you the confidence to merge.
• Add fixtures to make adding tests easier.• Test UI. The beautiful thing about React is that you can shallow render a component and
make assertions against what you know it should look like.• Test methods. Test key internal component methods against edge cases.• Test everything you can. Not sure if you should test it === yes.• Require tests from all incoming PRs that change more than configurations / typos• Which testing framework should you use?
Testing is Key
14
15
Linting
16
Never trust yourself to catch what automation can catch.
• It’s a one-time configuration that gives back to the project in abundance.• Saves you from being the butthole owner that nit picks every PR. Can you say scapegoat?• When contributing to a codebase it’s nice to have a standard to code towards.• There is literally no downside to linting. Ok maybe there are one or two.
Linting Saves Time
17
README.md
18
Don’t slack off on documentation.The 3 Things Every README Needs
19
PicturesAlways show a visual
representation of what your component does
Props Dev Tips
2 3
Add a table or some simple way of seeing
what props are available for use
Provide tips on how to get started in
contributing to the component
1
NPM
20
There’s a lot of little things to learn, so break it down.
• devDependencies - Any dependencies that are requirements for contributing to the component.
• peerDependencies - This means that your component is like a plugin for a given dependency. It will not install the dependency itself, but expects it to be there. Ours has `react` as a peer dep.
• dependencies - Any dependencies that are requirements for production.• files - List of directories/files to be included when npm installed. You can conversely use a .npmignore file to exclude directories/files.• main - Path to the file that should be referenced when `required` (the dist file).• jsnext:main - Like main, but points to an ES2015 file (the src file).• keywords - These are `tags` for your component. Make sure to at least include `react` and `react-component`.
package.json
21
You can create your own, or tie into keywords.
Scripts
22
• start - Typically used for starting your development server ( ie., cd example && node server.js ).
• test - Runs the unit tests for your component ( ie., node_modules/.bin/karma start karma.config.js ).
• build - Compiles/minifies your src directory ( ie., npm run clean && webpack --config webpack.config.js ).
• lint - Runs the linters to verify code quality ( ie., ./node_modules/eslint/bin/eslint.js src ).• prepublish - Runs before publishing to NPM. Typically runs build ( ie., npm run build ).
"scripts": { "build": "npm run clean && webpack --config webpack.config.js", "clean": "rimraf dist lib", "lint": "./node_modules/eslint/bin/eslint.js src", "prepublish": "npm run build", "start": "cd example && node server.js", "test": "node_modules/.bin/karma start karma.config.js”}
Just use MIT, it’s popular and truly open.
Licenses
23
All public projects on NPM are free to create and maintain.
Getting Started with NPM
24
• Create your account -NPM Sign up• Command Line
npm login: use the credentials for the user you just created npm publish
• README - Make sure your component page looks good on npmjs.com Go check it out at https://www.npmjs.com/package/<component_name>
• Try it - Make sure your project installs correctly (npm install <component_name>)
Semantic Versioning
25
“Semantic versioning is a standard that a lot of projects use to communicate what kinds of changes are in this release. It's important to communicate what kinds of changes are in a release because sometimes those changes will break the code that depends on the package.” - NPM
Use the correct versioning to ensure compatibility for your users.
Versioning
26
• 1.0.0 - Publish to NPM. npm publish
• 1.0.1 - Patch release. Bug fixes or minor changes. npm version patch -m “[B124] Fixes some bug”
• 1.1.0 - Minor release. New feature with backwards compatibility. npm version minor -m “Adds X feature”
• 2.0.0 - Major release. New features that break old versions. npm version major -m “Architecture change for X”
Let’s check out the demo!
27
react-image-layout
28
Lightweight
Encapsulated
Stateless (if possible)
Performant
Minimal
PropTypes + DefaultProps
Tests (UI + unit)
Linters
README (pictures, props, tips)
Example Usage
Package.json