@reactuniversal/ui-library-template

A template for developing universal (web, ios, android, desktop) React Native UI components.

• Develop cross-platform components for iOS, Android, Web, Windows, Macos, and Electron with React Native
• Cross-platform storybook environment with useful addons
• Publish storybook environment to Github pages with a single command
• Publish and version each component independently using a single command with Lerna
• Typescript Support
• Accessibility checks with ay11 addon
• Unit testing with Jest and React test renderer
• Visual Regression Tests with Loki
• Continuous Integration with Circle CI
• Maintainability scores with CodeClimate
• Eslint and Prettier Config
• Git hooks with Husky

Documentation

Storybook Example

Get Started

1. Click "Use this Template" and create a new repo
2. Run npm i to install the dependencies
3. Start the storybook web environment: npm run web
4. Start a native storybook environment: npm run ios or npm run android
5. Start creating components

Optional

6. Update fields in Package.json to match your project (name, author, version, etc)
7. Update storybook/stories/Home.stories.tsx text to match the name of your project
8. Update Readme for your project

Tech

Docs

Developing components

Each component should have it's own folder under the packages folder, with it's own package.json. This allows you to publish and make available each component seperately. Though you can structure the packages and components however you want, but you'll need to update the lerna configuration depending on your structure.

An example component is provided in packages/example. The storybook config looks for stories that have this extension: .stories.tsx. The tests look for stories with .test.tsx extension. Where you put these files doesn't really matter, but I find putting them right next to the component makes it easier.

// packages/example/lib

Example.stories.tsx
Example.test.tsx
Example.tsx

When I want to create a new component I usually use the lerna create <name> commmand, but this is not necessary, you can just create a new folder, package.json, and the required component files.

Publishing Your Components

Lerna makes this incredibly easy, just run lerna publish and all packages with updates will be published. Lerna provides a lot of options here however, checkout the docs on publishing to learn more.

Publishing Your Storybook with Github Pages

You can publish the storybook web environment using the following command:

npm run run deploy-docs

This will bundle the storybook web project, create a separate branch gh, push the bundle to that branch, and make it available on github pages at a url like this:

https://react-universal.github.io/[package]

For example, the template ui library storybook is published here: https://react-universal.github.io/ui-library-template/

Independently Versioned Packages

The config for lerna is found in the lerna.json file at the project root. Currently, version is set to independent, which means that each package/component you add will be versioned independently of each other. If you want all packages to share the same version then change version to the semantic version you want, for example, version: 1.1.3. Check out the Lerna documentation to learn more about configuring Lerna.

Visual Regression Tests

For visual regression tests, we need to generate a starting reference image for how the component should look. We can do this initially by running the test:loki-update command, which will automatically create images for each story on chrome for three different sizes: 1366, iPhone7, and A4 paper. You can customize Loki settings in the package.json.

Once you have reference images, you can run the command test:loki to run visual regression tests. If differences are found, the current image will placed in .loki/current and the difference image in .loki/difference.

Stroybook style helper components

By default storybook adds the components directly in the top left without any styles. However, usually it looks better (though not always) to add some more spacing and title. Two helper components are provided for this: Container and Header.

Another problem with default storybook styling is that the storybook environment (where the components actually are) is not wrapped in a ScrollView, which in React Native means the screen will not scroll if the content extends past the bottom. The Container component, therefore, also wraps the environment and allows you to scroll down on iOS and Android if your components grow larger than the screen.

Badges

Some more badges that might be useful to disply in the library's Readme.

Structure

storybook

Folder contains configuration for React Native storybook and storybook in general.

.storybook

Folder contains configuration for React Web storybook

packages

Folder contains all of the individual package folders (Button, Utils, etc.

packages/[Component]

Each seperated package has it's own package.json, and the lib folder.

packages/[Component]/lib

Lib folder for each package contains the src files for that package as well as the .stories. and .test. files.

Commands

npm run android

Runs storybook on Android

npm run ios

Runs storybook on iOS

npm run web

Runs storybook on the web, also opens a tab at localhost:9000.

npm run deploy-docs

Builds and deploys storybook docs

npm run build-storybook

Builds the storybook web project into a bundle in the public folder.

npm run push-docs

Deploys the contents of the public folder, which should be the storybook web project.

npm run see-npm-package

This command shows the exact files that will be published if you run the command npm publish. Useful for double checking if you are including something you do not want to include. If something does need to be ignored, you can ignore it in the .npmignore file.

npm run test

Runs Jest tests

npm run test:generate-output

Generates jest-test-results.json which is used by the jest addon in Storybook to show the latest test results for that component.

npm run test:loki

Runs loki tests

npm run test:loki-update

Generates the initial reference images that will be diffed later on.

npm run lint

Runs eslint

React Universal

All React Universal UI components use this template. For example:

Libraries

• Space

Components

• Button