nwb-spike v0.0.1
nwb-spike
Describe nwb-spike here.
npm run
Scripts
package.json
is configured with "scripts"
we can use with npm run
while developing the project.
Command | Description |
---|---|
npm start | start a development server for the demo app |
npm test | run tests |
npm run test:coverage | run tests and produce a code coverage report in coverage/ |
npm run test:watch | start a test server and re-run tests on every change |
npm run build | prepare for publishing to npm |
npm run clean | delete built resources |
The initial project is set up so you can successfully run each of these commands and get some meaningful output, albeit for a component which does nothing more than render a welcome message.
Testing
nwb provides a default testing setup which uses Karma to run tests written with Mocha and Expect in the headless PhantomJS browser.
The Testing documentation provides an in-depth overview of what nwb's default testing setup provides (and how to configure things to your liking if you want to), but we'll stick to editing the initial test provided in the React component project skeleton, in
tests/index-test.js
.
npm run test:watch
automatically re-runs tests on every change to provide a quick feedback loop while developing, whether you're writing tests up-front, in parallel with implementation or after the fact.
If you're into Test Driven Development, it will give you the flow you want as you write breaking tests followed by implementations which satisfy them.
The following example tests were implemented after the LoadingButton
component was written, adding one it()
block at a time and tweaking each test based on feedback from re-runs - for example, I wasn't sure how a disabled={true}
prop would be represented in the resulting HTML, so I used .toContain('')
to see what would happen.
Note 1: Testing against static HTML output is a brittle way to assert what your components are returning from their
render()
methods, but it's handy for our demonstration purposes.Note 2: We're importing the expect library below, but it's not included in
package.json
- nwb handles the expect dependency for you so you can get started with testing without having to make a decision. Other assertion and spy libraries are available :)
import expect from 'expect'
import React from 'react'
import {renderToStaticMarkup as render} from 'react-dom/server'
import LoadingButton from 'src/'
describe('LoadingButton', () => {
it('renders a button with type="button"', () => {
expect(render(<LoadingButton>Test</LoadingButton>))
.toContain('<button type="button">Test</button>')
})
it('disables the button when loading=true', () => {
expect(render(<LoadingButton loading>Test</LoadingButton>))
.toContain('<button disabled="" type="button">Test</button>')
})
it('disables the button when loading=true even if disabled=false', () => {
expect(render(<LoadingButton disabled={false} loading>Test</LoadingButton>))
.toContain('<button disabled="" type="button">Test</button>')
})
it('passes other props through', () => {
expect(render(<LoadingButton className="test">Test</LoadingButton>))
.toContain('<button type="button" class="test">Test</button>')
})
})
Code Coverage Reporting
Once your tests are working, you can generate a code coverage report by running npm run test:coverage
:
Code coverage percentages on their own are fairly meaningless, but running coverage also produces an HTML report in coverage/html/
showing coverage statistics for each file and annotating your code to show which pieces were and weren't touched during a test run.
This HTML report is handy for finding out what your tests aren't covering, and deciding which uncovered areas you'd feel more comfortable having some tests for.
Continuous Integration (CI) Testing
If you use GitHub for your project's source code hosting, it's pre-configured for running tests on Travis CI and posting code coverage results to coveralls and codecov.io after successful test runs.
If you log in to Travis CI and enable it for your GitHub project, your tests will be run on every subsequent commit and automatically run against Pull Requests.
Building and Publishing
nwb provides a default setup which keeps your source code repository free from distracting built resources (which can also be confusing for potential contributors) and makes your code usable as part of a standard Node.js development setup, by module bundlers and directly in the browser via <script>
tag.
Preparing for Publishing
npm run build
will prepare the component for publishing, creating:
- A CommonJS build in
lib/
- An ES modules build in
es/
(enabled by default / without configuration) - UMD development and production builds in
umd/
(if configuration is provided)
The CommonJS build preserves CommonJS interop using the add-module-exports
plugin, to avoid people using your npm packages via CommonJS require()
having to tag a .default
onto every require()
call.
Any propTypes
declared by class components or stateless function components will be wrapped with an if (process.env.NODE_ENV !== 'production')
environment check by default, so they'll be automatically stripped from the production build of apps which use them.
By default nwb will also create a production build of the demo React app in demo/dist/
, ready for deployment to wherever you want to host the demo (e.g. Surge for simple deployment, GitHub Pages for more involved deployment tied in with source control). The demo is configured so it can be served from any directory, so you shouldn't need to configure anything no matter where you're hosting it.
.gitignore
is configured to ignore these build directories to avoid/prevent checking built resources into source control, since npm acts as the canonical source for published, versioned builds and unpkg makes it easy to provide access to the UMD build.
For example, if you were to publish this example project to npm as react-loading-button
, the latest version of its UMD build would be available from https://unpkg.com/react-loading-button/umd/react-loading-button.js
without having to configure anything.
Publishing to npm
Once you've built your project, it's ready for publishing to npm using whatever your preferred process for doing that is, with the simplest being manually running publish
:
npm publish
package.json
is pre configured with a "files"
whitelist which will only include lib/
, es/
and umd/
directories in the npm package, in addition to the usual npm metadata like package.json
and README.md
.