README.md

Forma 36 React Components

A React component library for Contentful, powered by Storybook.

Table of contents

• Library Usage
  • Install package from NPM
  • Import desired component into your project
  • Import styles
• Development
  • Switch to the correct version of Node (using NVM)
  • Install dependencies
  • Run Storybook
  • Example component directory structure
  • Styling
  • Adding a new component
  • Adding new Storybook documentation
• Testing
  • Run tests
• Building
  • Create a build of the library
• Commits
• PropTypes

Library Usage

Install package from NPM

yarn add @contentful/forma-36-react-components

Or for NPM

npm i @contentful/forma-36-react-components

Import desired component into your project

import { Input } from '@contentful/forma-36-react-components';

Import styles

import '@contentful/forma-36-react-components/dist/styles.css';

Development

Switch to the correct version of Node (using NVM)

nvm use

Install dependencies

yarn

or

npm i

Run Storybook

Storybook is a UI development environment we are using to power our component library. Using Storybook allows us to work on components in isolation.

yarn start

Using Storybook requires you to wrap your component in a story. Look in the src/components directory for an example .stories.js file. Storybook has been configured to automatically include any files with the .stories.js file extension.

Storybook is setup using its own Webpack configuration file located at tools/.storybook/webpack.config.js.

Example component directory structure

A component's directory should resemble the following:

YourComponent
├── index.js                 // A file for exporting your component
├── YourComponent.js         // Your React component
├── YourComponent.css        // Component styles
├── YourComponent.stories.js // Storybook for the component
└── YourComponent.test.js.   // Component tests

Styling

We are using postcss-preset-env for styling our components. Using postcss-preset-env allows us to use the latest CSS syntax without having to wait for browser support. tools/postcss.config.js is used for adding plugins and configuration.

Adding a new component

You can use Plop to scaffold new components. Run yarn add-component and follow the steps in the CLI to create a component. Using your input here, Plop will generate the relevant files and add the relevant imports/exports to the main src/index.js file required to make the component available when publishing the library.

Here is the example output of running the yarn add-component command:

? What is the name of your component? button
[SUCCESS] add /src/components/Button/Button.js
[SUCCESS] add /src/components/Button/Button.css
[SUCCESS] add /src/components/Button/Button.test.js
[SUCCESS] add /src/components/Button/Button.stories.js
[SUCCESS] modify /src/index.js
[SUCCESS] modify /src/index.js

Adding new Storybook documentation

You can also use Plop to scaffold documentation sections in Storybook. Run yarn add-documentation and follow the steps in the CLI to create new documentation. Using your input here, Plop will generate the relevant files required to make the documentation show in Storybook.

Here is the example output of running the yarn add-documentation command:

? What is the title of your documentation? general
[SUCCESS] add /.storybook/docs/General/General.md
[SUCCESS] add /.storybook/docs/General/General.stories.js

Testing

We are using Jest and Enzyme to test our components.

Tests are kept next to their components and use the .test.js file extension.

Run tests

yarn test

It is recommended to run tests in development with the optional --watch flag.

yarn test --watch

Building

We are using a combination of Webpack and Babel to create builds of our component library. We use Webpack with the tools/webpack.production.config.js config to build a stylesheet including all CSS used for our components using the ExtractTextPlugin. Babel is used for transpiling our React components into CommonJS modules. Babel and Webpack both output the build to the dist directory.

Create a build of the library

yarn build

Commits

This project uses the Angular JS Commit Message Conventions, via semantic-release. See the semantic-release Default Commit Message Format section for more details.

You can commit the changes by running

yarn commit

PropTypes

We recommend the following naming convention for PropTypes:

• Array - use plural nouns. e.g. items
• Number - use a prefix or suffix to imply that the prop accepts a number. e.g. numItems, itemCount, itemIndex
• Boolean - use the prefix 'is'/'can'/'has'. e.g. isVisible, canExpand, hasImage
• Object - use a noun. e.g. item
• Node - use the prefix 'node'. e.g. containerNode
• Element - use the prefix 'element'. e.g. triggerElement
• Event handler functions - use the prefix 'on'. e.g. onOpen, onClick