satyamz/ui-components

A collection of UI components that are shared across Weaveworks projects

See it in action:

http://weaveworks-ui-components.s3-website-us-west-2.amazonaws.com/

Prerequisites

• React & ReactDOM ^16.0.0
• lodash ^4.0.0
• styled-components ^2.0.0
• moment ^2.0.0
• font-awesome ^5.0.0

Installation

yarn add weaveworks-ui-components

import React from 'react';
import ReactDOM from 'react-dom';
import { ThemeProvider } from 'styled-components';

import { WeaveLogo } from 'weaveworks-ui-components';
import theme from 'weaveworks-ui-components/lib/theme';

ReactDOM.render(
  <ThemeProvider theme={theme}>
    <WeaveLogo />
  </ThemeProvider>,
  document.getElementById('logo')
);

Importing Styles

To import the stylesheets, you must have a webpack Sass loader configured:

module.exports = {
  ...
  module: {
    loaders: [
      {
        test: /\.(scss|css)$/,
        loader: 'style-loader!css-loader!sass-loader'
      }
    ]
  },
  sassLoader: {
    includePaths: [
      path.resolve(__dirname, './node_modules/weaveworks-ui-components')
    ]
  }
  ...
}

To import styles:

@import "~weaveworks-ui-components/styles.scss";

Development

Adding a component

1. Place your component in a src/components/<component name>/ directory.
2. Add a file called index.js to your component directory. Add export statements, like so:

export Menu from './Menu';
export MenuItem from './MenuItem';

export default from './Menu';

3. Add some tests to the same directory with a .test.js suffix.
4. Document your module by adding comments. See the <Button /> component for an example. The react-docgen library is used to parse comments, which are then rendered as markdown.
5. (Optional) Add an example implementation of your component in its directory. Call the file example.js. If no example.js file is added, the component itself (with default props) will be rendered in the component library UI.
6. Export the component from the library by adding an export statement to src/components/index.js. There is a unit test that will check that all components are exported; run tests using npm test.

To develop a component locally, start the webpack-dev-server using npm start. Any components in the src/components directory will auto-magically be visible in the left-hand navigation. Editing a component will hot-reload it in the page. NOTE: when adding a component file for the first time, you will need to restart the webpack-dev-server to see the component appear in the navigation.

Parallel development with LocalModuleProxy

It is possible to proxy module imports to a local copy of the weaveworks-ui-components repository to allow for parallel development. For example, if you want to add a new component to your project, but you want to re-use the component on other projects, you can do you can add a component in the ui-components/src/components directory, then add the LocalModuleProxy resolver plugin to your webpack config:

const webpack = require('webpack');
const LocalModuleProxy = require('weaveworks-ui-components/resolvers').LocalModuleProxy;
const COMPONENT_LIB_PATH = '/Users/myusername/path/to/ui-components';

module.exports = {
  ...
  plugins: [
    new webpack.ResolverPlugin(new LocalModuleProxy({
      moduleName: 'weaveworks-ui-components',
      path: `${COMPONENT_LIB_PATH}/src/components/index.js`
    }))
  ]
}

You can also proxy multiple modules by adding a lookup to the modules key in the LocalModuleProxy constructor:

plugins: [
  new webpack.ResolverPlugin(new LocalModuleProxy({
    enabled: true,
    modules: {
      'weave-scope/reducer': `${SCOPE_COMPONENT_PATH}/client/app/scripts/reducers/root.js`,
      'weave-scope/component' : `${SCOPE_COMPONENT_PATH}/client/app/scripts/components/app.js`
    }
  }))
]

Webpack will resolve imports that match moduleName from the path supplied to the path key. This should work for all webpack-related functionality, including hot reload.

One weird trick to remove the COMPONENT_LIB_PATH variable from version control:

In your .bash_profile or equivalent:

export COMPONENT_LIB_PATH="/absolute/path/to/ui-components"

In your webpack.config.js:

module.exports = {
  ...
  plugins: [
    new webpack.ResolverPlugin(new LocalModuleProxy({
      moduleName: 'weaveworks-ui-components',
      path: `${process.env.COMPONENT_LIB_PATH}/src/components/index.js`
    }))
  ]
}

Exclude proxied modules from preLoaders

Since the request for weaveworks-ui-components is no longer resolving to node_modules, you may need to add an additional clause to the exclude option in your webpack preLoaders:

// Change this:
preLoaders: [
  {
    test: /\.js$/,
    exclude: /node_modules|vendor/,
    loader: 'eslint-loader'
  }
]

// To this:
preLoaders: [
  {
    test: /\.js$/,
    exclude: new RegExp(`node_modules|vendor|${process.env.COMPONENT_LIB_PATH}`),
    loader: 'eslint-loader'
  }
],

Releasing this repo

Configure your AWS CLI tools: http://docs.aws.amazon.com/cli/latest/userguide/installing.html.

Run yarn release to cut a new release, this will also generate and commit the CHANGELOG.md automatically.

If everything is ok, you can publish the release to github and npm with yarn publish, entering the new version you just created. This will build, publish and then push static files to S3 for the docs site.

Adding Style Guide articles

To add a page to the style guide:

1. Add a markdown file to the /styleguide directory of this repo
2. ???
3. Profit

Getting Help

If you have any questions about, feedback for or problems with ui-components:

• Invite yourself to the #weave-community slack channel.
• Ask a question on the #weave-community slack channel.
• Send an email to weave-users@weave.works
• File an issue.

Your feedback is always welcome!