Developers

Install

You can install real-react via npm or yarn. Today we do not have a functioning build for distribution, so you should install the latest release from github by tag or branch.

See all releases on Github

npm install git+https://github.com/kwri/real-react.git#develop

yarn add git+https://github.com/kwri/real-react.git#develop

Configuring the styles

At the root of your application, you should import the bundled CSS file that comes with the installation.

import React from 'react';
import { Button } from 'real-react';
import 'real-react/real.css';
const App = () => (
  <div>
    <Button theme="secondary">Click me</Button>
  </div>
);
export default App;

Using components

Simply import components by name from the real-react package, as demonstrated above.

Contributing

The following guidelines should be adhered to when contributing to this project.

Follow the Design System

The design system is the source of truth for all components built. All styles and components created should be as close to pixel perfect as possible.

You can find the design system here.

Code Formatting

Ensure that whatever code editor you're using has the Prettier and CSSComb extensions/plugins installed and enabled

Documentation

Any modifications (add, remove or edit) made to the codebase should result in documentation updates.

We use Docz as the documentation tool for the library. Each component (or set of components if related) should have a corresponding readme.mdx file that will serve as the documentation. The file should contain, at a minimum, a Props table, but should typically include some example usage as well.

You can reference any of the existing MDX files for an example.

Define Props and Default Props

You should define props and default props when appropriate since they will serve as part of the documentation generated by Docz

Single Element Pattern

When possible, each component should only return a single HTML element. For example, the TextInput component should return only an <input/>.

However, rendering multiple elements is sometimes necessary for more complex components such as Pagination which is made up of several other components.

Pass-Through Props

Whenever possible, you should be passing through all additional props to the component to make them as reusable as possible. Ensure that you destructure any explicitly defined props, otherwise they end up on the DOM element itself and can throw warnings or errors.

render() {
    const { className, ...props } = this.props
    return <div className={cx('my-component', className)} {...props}/>
}

If the component renders more than a single DOM element, the pass through props should be applied to the most applicable element. This can be difficult to determine, but typically aligns more closely with the intended use of the component itself. Take an Input component that may be wrapped in a div. The input element makes far more sense to pass through props into because it's the focus / intended use.

render() {
    const { className, ...props } = this.props
    return (
        <div className={cx('my-component', className)}>
            <input {...props}/>
        </div>
    )
}

Static Assets

Any static assets (illustrations, logos, icons, etc.) used should be upload to the kw-console-assets S3 bucket and sorted respectively.

The base URL for that bucket is available in the src/constants and should be imported into your component to reference a particular asset.

Styling / CSS

In the future, this library will consume an external stylesheet in order to style components much how react-bootstrap might consume the styles from the actual bootstrap.css asset rather than build them directly into the library.

In the meantime, we're building the CSS inside this repository in the scss directory.

The following should be followed when working in that directory

• All colors, sizes, etc. should be applied using the variables in the scss/variables directory
• All component styles should be placed in the appropriate scss/components file or created in a new file in the same directory
• All SCSS files should be created as partials (prefixed with _)
• Class names should follow the BEM naming convention

If creating a new file in any of the subdirectories in scss, you will need to import it into the respective root file. For example, if you created scss/components/_mycomponent.scss, you will need to add import "components/mycomponent.scss" to the scss/_components.scss file

Branching, PRs and Releases

• The GitFlow branching model should be followed for all new features.
• Any contributions should have a pull request created off of the develop branch for approval before merging
• Semantic versions should be used to tag releases for production

Modifying Dependencies

If you add or remove a dependency, be sure to modify the list of the dependencies in the documention appropriately.

When all possible, dependencies should be kept to a minimum.