@apolitical/styleguide v5.0.0

Apolitical Styleguide

A re-usable collection of React Components for Apolitical's various UIs. Frontend Applications.

A reference UI is hosted on Gitlab Pages at https://apolitical.gitlab.io/styleguide - see .gitlab-ci.yml.

Usage

Install as a dependency:

yarn add @apolitical/styleguide

This library is exported as ApoliticalStyleguide. You must provide the following libraries: React, ReactDOM, ReactModal, ReactRouterDOM, styled, Supercluster

Important

There are several peer dependencies you may wish to bring in, depending on what components you use. At the very least you will need React and styled. You must provide these as UMD modules. If you are using webpack the WebpackCdnPlugin will help you:

webpack.config.js

...
plugins: [
  new WebpackCdnPlugin({
    modules: {
      react: [
        { name: 'react', var: 'React', path: `umd/react.${prod ? 'production.min' : 'development'}.js` },
        { name: 'react-dom', var: 'ReactDOM', path: `umd/react-dom.${prod ? 'production.min' : 'development'}.js` },
        { name: 'react-router-dom', var: 'ReactRouterDOM', path: `umd/react-router-dom${prod ? '.min' : ''}.js` },
        { name: 'styled-components', var: 'styled', path: `dist/styled-components${prod ? '.min' : ''}.js` },
        // Optional
        { name: 'react-modal', var: 'ReactModal', path: `dist/react-modal${prod ? '.min' : ''}.js` },
        { name: 'supercluster', var: 'SuperCluster', path: `dist/styled-components${prod ? '.min' : ''}.js` },
        // Must come last
        { name: '@apolitical/styleguide', var: 'ApoliticalStyleguide', path: 'dist/index.js' },
      ],
    },
  }),
]

See externals in webpack.config.js for all dependencies.

Then, you can use our React components.

import { Atom, Molecule, Organism } from './index';

You can see a full list of components here.

You will also want to bring the theme, by creating a wrapper:

import { Theme } from './index';
const { ApoliticalBrand, ApoliticalGlobalStyles } = Theme;

export default ({ children }) => (
  <>
    <ApoliticalGlobalStyles />
    <ThemeProvider theme={ApoliticalBrand}>
      {children}
    </ThemeProvider>
  </>
)

Environments

There are several "environments" to be aware of. These are managed via yarn (or npm if you prefer):

yarn run dev

Use while working on the styleguide to start a development server and other tools for interactive work / testing. The styleguide should become avalable at http://localhost:6060/ . dev-lite is less resource-intensive, but dev is preferred. It uses the development webpack environment.

yarn run build

Produces the styleguide library which is imported into other projects. It uses the lib webpack environment.

yarn run build:analyze

Produces the styleguide library and starts any profiling tools to help locate any issues. This does not self terminate and therefore should not be used in CI. It uses the analyze webpack environment.

yarn run build:styleguide

Builds a static version of the styleguide. It uses the production webpack environment.

Developing with Styleguide

yarn run start

This will make a local version of the styleguide available at http://localhost:6060 To link the local version of styleguide to the project that you are using it in:

Linking to other repositories for local development

Sometimes you'll want to link your work in progress styleguide to another repo so you can test things in realtime without having to keep publishing to npm.

We've run into trouble getting the traditional yarn link to work, so yalc is an alternative method. Try it with yarn link first, and if you cannot see the other repo updating with your changes, you can try yalc.

#### Linking with yarn

• In the styleguide repository in the terminal, while the project is not running, run yarn link && yarn run dev
• This creates what's called a symlink. This makes the project available locally for a node_module package to point to.
• In the project you'd like to use your local Styleguide in, run yarn link "@apolitical/styleguide". This will tell that project's node_modules to point the @apolitical/styleguide package at your locally running package. Running yarn install after this will overwrite it with the released remote package. You can also run yarn unlink @apolitical/styleguide in your project and yarn unlink in the styleguide to unlink the two/break the symlink.

Linking with yalc

Yalc documentation

1. Run yarn global add yalc - this is a global install on your computer
2. In Styleguide, run yalc publish
3. In the repo you want to link to, run yalc link @apolitical/styleguide
4. Each time you make a change in Styleguide, you can run yalc push in Styleguide repo and these changes should reflect in the linked repo. If changes do not show up, try yalc publish --push
5. Add .yalc/ and yalc.lock to your .gitignore file if it is not already there. This is just for local development, we don't want to commit yalc files.

Note

When you're done, you can run a regular yarn install @apolitical/styleguide in the linked repo to overwrite the yalc version, or run yalc remove @apolitical/styleguide in the linked repo.

Double check that the package in your linked repo's package.json is pointing to @apolitical/styleguide. yalc link should not touch the package.json, but it's wise to double check.

Troubleshooting

• I can't see my changes Styleguide builds itself down to a minified file, found in dist/umd.js. Any other project that uses this as a package will read from this file. Sometimes, it doesn't update quickly, or it might need a nudge to do it. If you are not seeing your changes, double check that you have run the project with yarn run start:build, as this tells it to update the umd.js file when it detects changes. Try be patient, as sometimes it takes a minute or so for the linked project/project that is using this to receive the updated umd.js file. Failing that, you can try to delete the dist folder and then run yarn run build to build it again.

• I can't override styles when I import the components If you want your styleguide component to allow a user to override its styles, you need to add className as a prop. ie.: export default ({className}) => <Box className={className} />; Then, in the repo you're using this component you'd do something like: const NewBox = styled.Box and apply your styling in there. StyledComponents does some work under the hood to auto generate classNames, but will not accept overrides without className being passed in.

Contributing

If you want to help, that's brilliant! Have a look at our Contributing Guide. We also adhere to a Code of Conduct, so please check that out, it includes details on who to contact if you have any concerns.