Relayr UI Elements

• Relayr UI Elements
  • Live Playground
  • Scripts
  • Contributing
    • Creating new package
      • Use create:package script if possible
      • Creating new package manually
    • Creating new components
      • Use create:component script if possible
      • Creating new components manually
  • Making release

Live Playground

To run demo locally: (click to expand)

• Clone this repository
• Install dependencies via yarn
• yarn run storybook
• Visit http://localhost:9001/

Scripts

Below is a list of scripts you can use while working with this repository. Preferably use Yarn to run them.

• start

  Runs storybook on local machine. It also builds all packages to be sure that all cross dependencies between packages works.

  Usage example:

  yarn start

  Aliases: sb, storybook

  To run Storybook with withInfo addon the environment variable STORYBOOK_WITHINFO should be set to 1:

  STORYBOOK_WITHINFO="1"
  

• start:no-build

  Runs storybook on local machine without building packages.

  Usage example:

  yarn start

  Aliases: sb:no-build, storybook:no-build

  To run Storybook with withInfo addon the environment variable STORYBOOK_WITHINFO should be set to 1:

  STORYBOOK_WITHINFO="1"
  

• build

  Build all packages

  Usage example:

  yarn build

• test

  Run all tests

  Usage example:

  yarn test

• test:coverage

  Run all tests and open coverage summary in browser window.

  Usage example:

  yarn test:coverage

• test:watch

  Run all tests in watch mode.

  The same as yarn test --watch

  Usage example:

  yarn test:watch

• lint

  Run typescript linter.

  Usage example:

  yarn lint

• commit

  Make git commit by using commitizen.

  See contributing section for more information.

  Usage example:

  yarn commit

• create:package

  Create new package if it not exists. It also creates basic file and folder structure inside new package.

  Usage example:

  yarn create:package

• create:component

  Create new component in given package (it will prompt for package name). It creates all required files for component:

  • test file
  • index file
  • component file
  • storybook file

  
  Usage example:

  yarn create:component

Contributing

Please do not use NPM for installing packages. Instead use Yarn as project is designed for Yarn workspaces.

UI-Elements uses the Conventional Commits specification. This means that every Pull Request must contain approvals with a description compliant with the "Conventional Commits" specification. Because we also use Lerna to manage multiple packages, the scope of the commit should be clearly defined as the name of one of the packages, e.g. ui-elements-i18n.

The easiest way to add new commits by convention is to use the Commitizen tool. Installation is as simple as running the following command:

npm install -g commitizen

Now, simply use git cz instead of git commit when committing.

Alternatively, if you are using NPM 5.2+ you can use npx instead of installing globally: npx git-cz or as a script:

yarn commit

Creating new package

Use create:package script if possible

yarn create:package

It will prompt for package name and create basic package structure with required files.

Creating new package manually

This project uses Yarn Workspaces for distributing multiple packages within one, monolithic repository.

Each package should have following files:

[package_name]
    |- index.ts
    |- package.json
    |- README.md

where:
index.ts - is main package file. It should contain all import and exports required by package.

package.json - should contain only dependencies required by package itself. Package can have cross dependencies. You can read more about it here. Remember to use Peer dependencies (instead of dependencies) for external dependencies inside package, for example React.

README.md - short readme for package visible in npm registry. Should have installation instruction for package itself.

Creating new components

Use create:component script if possible

yarn create:component

You can use the built-in script for convenience. It will prompt for package and create new component with given name. It will make sure that all basic files for the component will be created as well and component itself will be added to index.ts file located in package root folder.

Creating new components manually

Each package containing components should have following directory structure:

[package_name]
    |- components
        |- [component_name]
              |- __tests__
              |- [component_name].stories.tsx
              |- [component_name].tsx
              |- index.ts
    |- index.ts
    |- package.json
    |- README.md

While creating new components manually remember to maintain above structure. Also remember to update the index.ts file in package root. Its main purpose is to export all components from package.

Also its important to create stories for storybook. To do it, please create a *.stories.tsx file inside the component directory.

The main file for component has to be {component_name}.tsx. It should contain the top level component named exactly as component's folder. You can split component into smaller ones and place it in component folder. There is no rule limiting You to one file.

Fonts

In the projects icons are imported from @fortawesome/free-solid-svg-icons package as an object and then provided to the icon prop as an object.

Explicitly importing icons like this allows us to subset Font Awesome's thousands of icons to include only those you use in your final bundled file.

Making release

Follow below steps to make new release:

• Pull latest master from repository
• run

yarn lerna publish --registry {private_registry_url} --message "chore: new release"

where {private_registry_url} is the url of npm registry other than official one. You can skip this flag if you are using official registry.

Thats all, new release of all packages tha have been changed since last release will be created and pushed to registry. Also new tags will be pushed to Github repository with corresponding changelog.