Getting Started

Clone this project.

Then from the project directory, run:

yarn

Now, run the app in development mode by running .

yarn start

The app will run on http://localhost:9009 in the browser.

Upgrading Storybook and structural packages

Upgrading the Storybook package and any important structural package should only be done via the "Upgrade" branch. This is to avoid having different versions of Storybook on different branches and cause problems and conflicts.

Note: Before any upgrade via the Upgrade branch, you must be up to date with the master branch in order to avoid conflicts also. Also, when submitting your Merge Request, be sure not to delete the branch on merge.

Note: The Storybook is frequently updated, often for minor fixes and thus should not be applied everytime

Building Components

Approach

The purpose of a Storybook is to use React's approach of breaking down UIs into reusable components but with the capability of using them accross different apps.

Thus, components should not have any logic in them. They should be project agnostic in order to be portable to any app. They should only receive props, whether data or callback functions.

Our aim is to never duplicate components and styles but reuse them as much as possible.

Folder and file structure

Folders

All components should go in the components folder and have their own folder containing all of their code.

The pages folder serves to put together the components of a specific page in order to test that they are displayed correctly.

components
└── MyFirstComponent
└── MyNextComponent
└── ...
...
└── Pages     
    └── Checkout

Files

Each component's folder will contain it's main file, styling, story and tests.

The main file should be used to define it's props and typings (if shared between components it should be exported to an external file).

The styling will live in a .style.tsx file (see below for more).

Every component displayed in the front-end should have a story to document it. This means it should have a .stories.tsx file alongside it.

In the case of pages, a .stories.tsx file can group several component's stories into one file. This is usually the case for a specific topic, page, purpose or usage.

All components should also be tested and the tests will be written in a .test.ts file (coming soon).

components
└── MyFirstComponent
    └── MyFirstComponent.tsx
    └── MyFirstComponent.style.tsx
    └── MyFirstComponent.stories.tsx
    └── MyFirstComponent.test.ts
└── MyNextComponent
    └── MyNextComponent.tsx
    └── MyNextComponent.style.tsx
    └── MyNextComponent.stories.tsx
    └── MyNextComponent.test.ts
└── ...
...
└── Pages    
    └── Checkout
        └── PricingPage.tsx
        └── PaymentPage.tsx
        └── Checkout.stories.tsx

Storybook will then look for your .stories.tsx in order to display them automatically, as below:

Styling

Styled-Components

Our Storybook's components are entirely based on the Styled-Components library for styling.

Our objective is to never use .scss files as Styled-Components provide the same capabilities as SCSS along with the power of CSS-in-JS which allows to scope styling to the component level. This way only the styles necessary to the components actually mounted are loaded.

As mentioned above, a functionnal component's Styled Components must be defined inside a .style.tsx file

Global Styling

SC's GlobalStyles and theming features enable us to easily define global styling properties and variables which will be shared across all of our apps and components.

Global Styles

Any styling which must be applied to the whole app needs to live in the globalStyles.ts file at the root of the /src directory.

For ex: fonts-faces, font-size definitions, body or html styling.

Themes

Themes are also defined in the storybook and shared across projects and live in a myTheme.ts file.

Their purpose is to provide a source of truth for shared styling properties. This will save dev time and avoid mistakes/confusions which come with repeating code and typo errors.

They are basically objects containing styling variables as key: 'value' pairs and are injected via Styled-component's <ThemeProvider> wrapper component.

Themes will contain definitions of colors, spacings, font names and any shared styling property just like any scss variables files. They can also include shorthand strings for better ease.

export const lpTheme = {
  legacyPhoneGreen: '#34C25C',
  grey00: '#FFFFFF',
  grey50: '#FBFCFD',
  grey100: '#F6F9FC',
  grey200: '#DEE2E6',
  grey300: '#BDC4CB',
  ...
  boxShadowTooltip: '0 5px 5px 0 rgba(0,0,0,.1)',
  boxShadowTooltipArrowLeft: '-3px 5px  5px 0 rgba(0,0,0,.1)',
  ...
}

More documentation on how to use a theme's variables.

Shared Elements and Resets

All common elements which require base styles or style resets live in the Utils folder in the CommonElements.tsx file.

This might be useful to reset ul or li elements to remove unwanted native list styles. Or to have paragraph and heading elements without margins for example.

// imports
export const ParagraphXs = styled.p`
  font-size: ${(props) => props.theme.fontSizes.xsmall};
  margin: 0;
`

export const BaseList = styled.ul`
  list-style: none;
  padding: 0;
  margin: 0;
  width: 100%;
`
...

Testing

Mocks

In order to test your component's props and rendering, you will need to generate mock data.

Since the components must stay agnostic to any app, no API calls should be made to use data.

Instead, you should generate fake data in the mocks folder, in a file named after the component which will use it.

Bear in mind, the component should not adapt to the data so your file should conform to the typing you initially set on the component's props.

Local Testing

Once your components are ready in the storybook, you must check how they behave within the app you intend to use them in and if the data received is correct.

This implies the target app (ex: WizardX) to be connected to the local version of the storybook instead of using the actual package.

As of now, we will be using the yarn link feature to create a symlink between the storybook project and the target app project.

This part is slightly tricky and you should the following steps:

1. From the storybook run yarn build
2. Then run yarn link
3. From the target app (ex: WizardX) run yarn link @legalplace/storybook to replace the package with the symlink to the local storybook
4. Because of a Styled-components issue the storybook must use the same React, React-dom and Styled-Components package as the target app or it will crash. So each of these packages must be linked as well:
   • From the target app, navigate to the react, react-dom and styled-components folders inside the node_modules directory.
   • Within each of these folders run yarn link as well.
5. From the Storybook folder, run the script yarn link-all. This will allow the storybook to use the symlink to each of these packages.
6. All set!
7. Run yarn build in the storybook to see any new changes in the target app.

Once you are done testing your local components:

1. From the storybook, run yarn unlink-all to remove the symlink to the target app's react, react-dom and styled-components packages.
2. From the target app run yarn unlink @legalplace/storybook.

In both cases, you may need to run yarn install --force to restore all your packages to normal.

If you run into any issues, delete your node_modules directory, run yarn to reinstall all packges and repeat the process above.

Unit Tests

Coming soon

Release Process

Once your component or feature is tested locally (as explained above), then you are ready to release a new version of the Storybook package !

To do this, simply run yarn release. This will prepare the storybook for publication by automatically bumping the package version, bundling the code and create the release tag.

Then run git push --follow-tags origin MYBRANCH or simply git push --follow-tags.

No need to run yarn/npm publish as the CI will publish the new version.

Please note, in order to avoid too many version bumps, you should not release a new version for test purposes unless necessary.

Instead, you should test your components locally by following the steps listed in the "Local Testing" section beforehand.

Fix Load Stripe Problem

use ReactStripeScriptLoader to make sure the script is loaded before calling StripeProvider. link

Updated until

aa8dd52a4c5d438e70f7605d68e530f729b38312 (master)