@ntbjs/react-components

This is a library containing NTBs common front-end design utilities and React components.

✨ Usage

To start using the library is as simple as installing it.

You can then install the library with:

// with NPM  
npm install @ntbjs/react-components  
  
// with Yarn  
yarn add @ntbjs/react-components

📚 Documentation

@ntbjs/react-components uses Storybook as documentation and playground for all the utilities and components. Storybook will provide the necessary information about how to import and use the components.

▶ Visit our documentation in Storybook

🦺 Development

The library is created with:

Rollup to build the library
Scss for style configs and common style utilities
Styled-components to style components
Storybook as a playground and documentation off components

Tips before contributing

A component in this library should not assume anything about the context (e.g. layout) it's used in. By assuming the context it may limit the usability and diversity of the component in the consumer application. Therefore, we should strive to make all components layout- and position-agnostic whenever it's possible. Adding margin to a component is best left to the consumer.

All components should use React.forwardRef to let the consumer refer to the component root. They should also accept rest-{...props} in case the consumer needs to assign attributes or event-props to the component root

📚 Storybook

To run a live-reload Storybook server on your local machine:

npm run storybook

To export your Storybook as static files:

npm run storybook:export

You can then serve Storybook from the files under storybook-static using S3, GitHub pages, Express or anything that can serve static files.

🖨️ Generating new components

The project ships with a handy NodeJS utility file under ./util called create-component.js. Instead of copy pasting components to create a new component, you can instead run this command to generate all the files you need to start building out a new component. To use it run:

npm run generate widgets/AmazingComponent
                    ↑           ↑
                    |           └─── Component Name
                    └─── Component Category

This will generate:

─ /src  
  └── /components
      └── /widgets
          └── /AmazingComponent
              ├── AmazingComponent.js
              ├── AmazingComponent.stories.js
              ├── AmazingComponent.styled.js
              └── index.js

The default templates for each file can be modified under util/templates.

Note: Don't forget to re-export your new component in the index.js-file located in src/components/[component-category]

🔨 Building

You can build the library with:

npm run build

🧪 Installing the package locally (for testing only)

Let's say you have another project (test-app) on your machine that you want to try installing the component library into without having to first publish the component library. In the test-app directory, you can run:

npm i --save ../path/to/react-components

which will install the local component library as a dependency in test-app. It'll then appear as a dependency in package.json like:

"dependencies": {
  ...
  "@ntbjs/react-components": "file:../path/to/react-components",
  ...
}

The library with its utilities and components can then be imported and used in that project.

📦 Publishing

Docs on publishing is coming soon...

📂 Application structure

├── .storybook                              - The config folder for Storybook  
├── /build                                  - Build folder. Contains the output of the build. - auto generated
├── /src  
│   ├── /components                         - A folder containing all React components  
|   |   └── /[category]                     - The component category folder  
|   |       └── /[name]                     - The component folder  
|   |           ├── [name].js               - The React component code  
|   |           ├── [name].stories.js       - The Storybook story-definition of the component  
|   |           ├── [name].styled.js        - The component style powered by styled-components  
|   |           └── index.js                - A re-export of the component to allow easy ES module imports  
|   |  
│   ├── /icons                              - All icons this library provides
|   |   └── [icon-name].svg  
|   |  
|   ├── /storybook                          - Storybook documentation thats not liket to a component (like colors / icons)
|   |   ├── /assets                         - Assets used in the Storybook documentation  
|   |   └── /mdx                            - Storybook documentation  
|   |  
|   ├── /styles
|   |   ├── /utils                          - All SCSS utilities  
|   |   ├── all.scss                        - A file that imports all utilities and the global config  
|   |   └── config.scss                     - The global SCSS config  
|   |  
│   └── /utils  
│  
├── / package.json                          - Contains all npm scripts  
└── / *.*                                   - Various dotfiles and config files