Particles
Design Principles
Simple is better than complex.
Explicit is better than implicit.
Readability counts.
Flat is better than nested.
Sparse is better than dense.
Special cases aren't special enough to break the rules.
Follow SemVer religiously.
Maintain sandboxes for components.
Ship it.
How do I get started?
- Run
yarn
at the root. - Navigate to the directory of the component you're interested in.
- Run
yarn
in that directory.
particles
?
How do I view all the available - Run
yarn
at the root - Run
yarn storybook
- Go to
http://localhost:6006
Create a new Particle
Particle names must be unique and contain only letters and '-' dashes
- In the root dir run
yarn create-particle <your-particle-name>
Development
To develop a component FOO
, all you need are these commands:
yarn sandbox
Spins up FOO
and serves it up on http://localhost:8080
(or http://ude.8080
) for you to play around with in a standalone environment. The sandbox files are usually minimal implementation examples for the component, so keep them up to date!
yarn dev
Builds the dev bundle and watches the folder, rebuilding on a change.
In the tool which is importing FOO
, use yarn link FOO
to take advantage of these hot builds.
yarn test
Starts the appropriate test runner for FOO
's test suite and runs the corresponding test file(s) from within the /test
directory.
Also generates a code coverage report for FOO
component and prints it to the console.
Testing
All Storybook documented particles
get a thin layer of snapshot testing provided by Storyshots
and jest.
To update the snapshot to support your new Particle
or sandbox change
run:
yarn test -- -u
** Be Warned **
- This is not a drop in replacement for unit tests.
- This is not a drop in replacement for unit tests!
Publishing
Make sure the sandbox works.
Please update the README for each component with each change.
npm version PATCH|MINOR|MAJOR
in the component itself:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner
- PATCH version when you make backwards-compatible bug fixes.
SEMVER IS CRUCIAL. For questions, start at semver.org.
If you have publishing rights, run npm publish
.
If not, find and go ask the maintainers of the component for code review to ensure quality and continuity. Or, make a new component and try to consolidate at a later time.