template-component

Naive template for JavaScript package scaffolding

📦 Setup

Clone this repository:

git clone https://github.com/lookiero/template-component MyComponent

Or just use the Github template

📚 Storyteller

This template brings with it a Storytelling system for your components and modules. If your package contains more than one component you can contain each of them in different chapters, so that make it is easier to test. Let's see a naive example with our Button component:

App.storyteller.jsx

import { useStoryteller } from '@lookiero/storyteller';
import React from 'react';

import { Button } from './src';

const ChapterButton = () => {
  const { boolean, event, select, text } = useStoryteller();

  return (
    <Button
      align={select('align', 'center', { options: ['left', 'center', 'right'] })}
      disabled={boolean('disabled')}
      icon={text('icon', 'lookiero')}
      small={boolean('small')}
      variant={select('variant', 'primary', { options: ['primary', 'secondary', 'circular', 'circular-secondary'] })}
      onPress={() => event('onPress', { customized: true })}
    >
      {text('children', 'Hello world')}
    </Button>
  );
};

const Chapters = {
  '1️⃣ Button': ChapterButton,
};

export default Chapters;

✅ Testing

This template offers an isomorphic testing system, you can define a single test whose it will run by default in 3 environments (web, iOS and Android).

In case you want to modify these testing environments, you should simply go to the file [jest.config.js] (https://github.com/lookiero/template-component/blob/master/jest.config.js) and make your changes.

How to test

All tests must be contained in a tests folder. The recommendation is that each component, module, etc. have their own tests directory. Within this directory you can contain 2 types of files:

• file.test.[jt]s?(x) for Unit & Snapshot tests.
• file.visual.[jt]s for Visual Regression tests.

How to make a Snapshot

It is very important that you check the JSX structure of your React component. Remember that the system is configured to run in 3 environments automaticaly, so the transpiled JSX can give totally different tree nodes. Let's look at a simple example:

Button.test.jsx

import React from 'react';

import { Button } from '../Button';
import { render } from '@testing-library/react-native';

const align = 'right';

const DEFAULTS = {
  children: 'children',
};

describe('component:<Button>', () => {
  test('renders', () => {
    const { toJSON } = render(<Button {...DEFAULTS} />);
    expect(toJSON()).toMatchSnapshot();
  });

  test('prop:align', () => {
    const { toJSON } = render(<Button {...DEFAULTS} align={align} />);
    expect(toJSON()).toMatchSnapshot();
  });
});

You can take a look at the 3 snapshots rendered on the __snapshots__ directory that is generated at the same level of the test.

• Button.test.jsx.snap.web
• Button.test.jsx.snap.ios
• Button.test.jsx.snap.android

How to make a Image Snapshot

If your component has a visual representation, it is highly recommended to generate visual regression tests. In this template you will find a helper method visualSnapshots() that will help you test each of the properties of your component and generate a snapshot image for each of these properties. Let's see an example:

Button.visual.js

import { visualSnapshots } from '@tests';

visualSnapshots({
  chapter: 1,
  component: 'Button',
  props: {
    default: undefined,
    'align:left': 'left',
    'align:center': 'center',
    'align:right': 'right',
    children: 'test',
    disabled: true,
    icon: 'close',
    small: true,
    'variant:primary': 'primary',
    'variant:secondary': 'secondary',
    'variant:circular': 'circular',
    'variant:circular-secondary': 'circular-secondary',
  },
});

The use of this method is pretty simple, visualSnapshots receives an object with 3 properties:

• chapter being the chapter number of the Storyteller
• component the name of the component that we are going to test
• props the object that contains the properties to be tested.

By default, all Image Snapshots are rendered for a small screen (AKA, for a mobile device). In the case that you need to generate a certain Image Snapshot for another device size, you will simply have to add the property screen. Let's see how:

Button.visual.js

import { visualSnapshots } from '@tests';

visualSnapshots({
  ...
  screen: 'M',
});

How to run test?

Running the different tests is quite simple, inside the package.json you have several scripts ready to run. Let's see them:

• yarn test runs the default tets
• yarn test:visual runs the visual regression tests
• yarn test:coverage generates a report of the coverage of your package
• yarn test:watch runs yarn test in watch mode

👷🏻 How to build your package

Compiling your package is quite easy thanks to the preconfigured scripts in package.json. These will be in charge of linting your code, testing it and in case everything goes well, generate a new build and upload it to the NPM repository with a new minor patch.

For this magic to take place you must bear in mind that your package must be configured in the jenkins-init project. Let's see an example:

jobs.yaml

...
- name: your-component-front
  type: yarn_component
  version: 4.4.4
...

After having configured everything, simply with each merge to your master branch all the processes will be triggered to generate your new version of the package. In case you want to test it on your machine, you can take a look at the pipeline script in your package.json file.

Build Storyteller as Single Page Application

As you know, the Storyteller allows you to have a playground to be able to play with your components and modules. If you need to generate a Single Page Application version which can be online, you will simply have to run the script build: storyteller from your package.json. This script will generate a web-build directory with everything necessary to be able to publish it on a server.

👹 What the heck is .lookiero.rc

Think of this file as a descriptor for your project. In it you can set everything you need to facilitate the development of your project. For now we will focus on 2 features: alias and devServer.

The alias section will help you generate naming shortcuts to the different sections of your code. Note that by default you have the alias of Aurora Design System configured:

.lookierorc.js

  alias: {
    '@lookiero/aurora': '@lookiero/aurora-next',
    '@tests': './src/__tests__',
  },

The devServer section is a shortcut to the WebPack configuration. You can perform the same configuration as if it were webpack, although it will mainly be destined to the proxy subsection:

.lookierorc.js

devServer: {
  proxy: {
    '/api': {
      secure: false,
      changeOrigin: false,
      target: 'https://backend-for-user.dev.envs.lookiero.tech/',
    },
  },
},