podium-ui v10.1.2

Podium UI

A library of Podium UI components built in React to be used in our applications.

See all the components here https://podium.github.io/podium-ui

Usage

Getting started

Install Podium UI into your project by running the following:

npm install -S git+ssh://git@github.com/podium/podium-ui.git Once it's installed, add #latest to the end of the url in your package.json. Once your app is stable, you'll probably want to change latest to whatever the most current release is. Most likely only the big releases will be official github releases, so just go with whatever the most recent tag is. Also, as of v7.0.0, in order for Podium UI to function properly, you must have styled-components as a dependency within your app.

Include components like normal

import { Button } from 'podium-ui';

Styles

Included are a few stylesheets with variables to help us keep a consistent design. You can include them in your scss like so:

@import "~podium-ui/src/styles/colors";

.podium-green-text {
  color: $podium-brand;
}

It is recommended to include the base stylesheet in the global or base stylesheet of your app. base.scss includes sanitize.css, the AvenirNext font family, and a few other basic styles.

If you'd rather not include the entirety of the AvenirNext font family, you can instead just inclue global.scss. Be aware that at this point you will also have to manually include sanitize.scss.

It should be noted that the use of scss and css modules is deprecated in Podium UI. The base.scss and global.scss stylesheets can still be used as noted above.

There are equivalent JavaScript files that will set global styles using styled components. Where you import from will depend on what module system your project uses. If using native modules, you can import the base and global from podium-ui/build/styles to globally set styles.

// Includes sanitize.css and AvenirNext font family
import 'podium-ui/build/styles/base';

// Doesn't include sanitize and AvenirNext font family
import 'podium-ui/build/styles/global';

If using another module system, such as CommonJS, UMD, AMD, etc., then you can import or require from the podium-ui/legacy-build/styles;

// Includes sanitize.css and AvenirNext font family
import 'podium-ui/legacy-build/styles/base'; // or
require('podium-ui/legacy-build/styles/base');

// Doesn't include sanitize and AvenirNext font family
import 'podium-ui/legacy-build/styles/global'; // or
require('podium-ui/legacy-build/styles/global');

Development

Getting started

After downloading the project run: yarn or npm install Podium UI uses storybook, which allows you to see and test all the components via a web interface. Run the storybook with npm run storybook.

Hot reload

In podium-ui run npm link Run npm link podium-ui in the repo you are viewing the changes IE: dashboard-frontend After each change you make run npm run build in podium-ui After your frontend recompiles you can view your changes locally To unlink from podium-ui simply run npm unlink podium-ui

Local Changes

If the symlinking above doesn't work for you (which it sometimes doesn't because of the way webpack ignores symlinks), you can try this. In order to see changes made locally to podium-ui in other projects, commit the changes on a new branch. Run the bin/publish-branch script. This will create a tag on github in the form b-{BRANCH_NAME}. In order to include those changes in another project (for example, Dashboard Frontend), change the line in package.json where podium-ui is included to say "podium-ui": "git+ssh://git@github.com/podium/podium-ui.git#b-{BRANCH_NAME}",. After re-installing podium-ui with npm (npm install podium-ui) you will be able to see the changes in whichever frontend app you're working on. After making more changes, commit, re-run bin/publish-branch, and once it is finished publishing, re-install podium-ui in the other project.

Publishing

Before you create your PR, bump the version number appropriately in package.json, commit, and push. Once your PR has been approved, merge it, then checkout and pull master. Then run bin/publish on the master branch. This will create the appropriate tag based on what you changed it to in package.json, and upload it to the npm registry. You can now use the version you created in your other projects.

JavaScript Modules

The build process currently makes two builds, one into a build directory and another into a legacy-build directory. Both are transpiled with Babel from ES6+ into valid JavaScript. However, the build directory contains a build that uses native JavaScript modules with import and export. This gives the benefit of tree shaking with Webpack 2. The legacy-build converts native modules into CommonJS modules. The package.json has the main field pointing to legacy-build and the module field pointing to build. If your project is using native modules, it should point to the module field as the entry point and give you tree shaking benefits. Otherwise, it should default to the main field and work as usual.

To use version 5+, you will need a file loader in your build process to handle assets in Podium UI.