node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »




Reusable UI component and styles library for Planet built with React.



To use in your project, simply install with npm (or yarn):

With npm:

$ npm install --save @planet/ui react react-dom

With yarn:

$ yarn add @planet/ui react react-dom


@planet/ui depends on the following packages:

*Although emotion is a dependency, you won't necessarily need to implement any of your customizations using emotion, or use it for styling the rest of your app. Read more about using emotion in the customization section of the wiki.


To get started developing, read our Contribution Guidelines and Wiki article on Contributing.


Clone the repository locally:

$ git clone

Then navigate to the project directory:

cd ui

And install dependencies with npm:

$ npm install

Developing Components Independently

@planet/ui comes with a development server included, so you can work on components outside of any specific project.

To develop components locally, all you need to do is:

npm run start

Create a new Component

To create a new component from a starting template, including the styleguide markdown file, styles, and unit tests, simply run the following command (to create a new component called Sidebar (Please note our convention of using TitleCased names for components):

$ npm run forge Sidebar

Open the URL indicated in the terminal output to view the hot reloading enabled dev server!

Running Tests

There are 3 methods for running tests:

  1. npm run test, which will verify the integrity of the installed dependencies, and run all unit tests once.

  2. npm run test:analyze, which will run all the unit tests once with instrumentation, and generates code quality and test coverage reports, available via npm run report

  3. npm run test:watch, which will run your unit tests continuously by watching source and test files for changes.

If you encounter an error running npm run test:watch, and you are running Mac OS X Sierra, you may need to brew install watchman and try again. More info

Developing Components with Another Application

To develop UI components locally, while seeing the changes auto-reload inside another app you're working on (eg. explorer project):

  1. Link @planet/ui and start the development server to watch changes:

    # @planet/ui terminal window 
    $ npm link
  2. Link @planet/ui to your app

    # Your App terminal window 
    path/to/your/app $ npm link @planet/ui
  3. Start your app's development environment as usual

    # Your App terminal window 
    path/to/you/app $ npm run dev # or whatever your project does 

Now, if you make changes to a component in @planet/ui locally, the change will automatically reload in your app as if you had installed it with npm.

When you're finished making updates commit your changes using npm run commit ( or following conventional commits) and push to your remote branch. @planet/ui uses commitizen to help ensure quality

Publishing/Releasing Updates

  1. Merge your MR to master branch (after it is approved).
  2. In your local git repo, pull and rebase master to get latest updates.
  3. Clean your node_modules directory: rm -rf node_modules
  4. Bump the NPM version with npm version
  5. Push new tags to git: git push --tags origin master
  6. Publish the package to NPM: npm publish
  7. Verify the publication on NPM

To patch a version, use npm version patch in step 4 above.


Check the project Wiki to learn more about @planet/ui.

Visit our Issues queue for troubleshooting and support.