rods-ui v1.0.0-alpha.3

Rods UI

A library based on material-ui to be used as a standard library inside Beetech.

Installation

npm i -S @beetech/rods-ui
# or
yarn add @beetech/rods-ui

Remembering that to install internal packages from Remessa, you must be connected to the VPN. See more here

About

This project is a library built for React projects. There are peerDependencies as react, react-dom, and styled-components. PeerDependencies have some particularities to run locally or for development.

Important

Only customized components are listed on the internal storybook. Therefore, you have to follow the current material-ui documentation if you need details of components that are not fully customized yet.

Development

Installation

Node.js version >= v14.17.0

nvm use  # if you have nvm installed to select the v14.17.0 of Node
npm install

This command installs the peer dependencies also. Using the install-peers module.

Running

Development

To compile the project using rollup.js to dist/bundle.js and to watch the changes:

npm run start:dev # it runs compiling to dist/bundle.js

To run the storybook (most important to local development)

npm run start:storybook  # it runs at http://localhost:6006/

To run the tests and watching the changes:

npm run test:watch

Ideally, it would be best to work on the storybook to develop new components or fix a bug.

If needed, you can link the library with your local project. Some weird behaviors can happen.

Contributing

ForwardRef

React.forwardRef creates a React component that forwards the ref attribute it receives to another component below in the tree. Therefore, we need to provide components with Forwarding Refs to allow Ref to consume components from this library.

Component development:

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>((props, ref) => {
  return <StyledButton {...props} ref={ref} />
})

Component usage:

// possible implementations
const ref = React.createRef<HTMLButtonElement>()
// or
const ref = React.useRef<HTMLButtonElement>(null)

<Button ref={ref}>Button with ref</Button>

To further information, you can check the material-ui documentation about forwarding ref in their components. Check this out caveats with refs and usage of component prop

Exportation

RODS-UI has two build systems configured: CommonJS (preserving modules) and UMD (unified bundle).

Exporting To export a new component it is necessary that the exports follow this pattern (found in the src/index.ts) file):

export { default as Accordion } from './components/Accordion'
export * from './components/Accordion'

The first line exports the Accordion component to be imported as follows: import { Accordion } from "@beetech/rods-ui". In this way, the component is inserted into the UMD final bundle.

The second line exports all the exported content into the ./components/Accordion file, and with that, all the typings are exported too.

CI and CD

RODS-UI is published on Storybook(S3) and NPM (as a package).

All the branches execute the Jenkins job to verify if they can be published. It runs lint, tests, and coverage.

The deploy is ran on the following branches: development (automatically) and tags(manually, see below how) with the semantic version pattern. The tests and lint aren't executed on these branches once the CI has run in the other branches created before merging to main and generating the tag.

See the following points to know how to publish in NPM and execute the deployment of the storybook by tag.

NPM

After generating a new tag from the main branch, you need to run the npm-publish job on Jenkins.

Access npm-publish job on Jenkins and click on the RUN button, fill the fields as below:

REPO_TO_PUBLISH=rods-ui
NODE_VERSION=14.17.0

You can access this runbook for more details.

Storybook

Development/Homologation

Just commit and push to the development branch, then the Jenkins will automatically publish in this url

Production

Generate a tag in git and manually trigger the publication on Jenkins -> find your created tag -> click on play button and wait it finished to access this url

Enjoy! :)

Important

When committing, it's executed a task to lint the project. If the lint doesn't pass, you can't commit your stuff. And when you try to push your code, it runs the lint and tests before pushing. So if there is any issue with your code, you won't be able to push the code.

Troubleshooting

See this article Setting up peer dependencies and local project

The problem with the link is that you will have 2 react libraries running on the same project. This causes an issue with react hooks. So then, you need to create an npm link to React from one to the project.

So, go to the library, get into node_modules/react, then execute npm link. Then, go back to your app repository and execute the npm link react. It should fix.

However, installing a new npm module on the rods-ui will probably have to execute npm install again because the peer dependencies are lost.

PS.: You may have the same problem with styled-components, and it will need to be linked to the app project as well.

See more

ZeroHeight

You can find the password on 1password. If you don't have access to 1password, you can ask for your tech lead, your team designer, or on #workgroup-design-system slack channel.

Storybook

Tests