Bojagi Docs

Bojagi Docs

  • Docs

โ€บTUTORIALS

GETTING STARTED

  • Quick Start
  • Frequently Asked Questions

TUTORIALS

  • Setup Bojagi With React and Storybook
  • Setup Bojagi With React and Without Storybook

DOCUMENTATION

  • Write Stories
  • CLI
  • .bojagirc
  • Continuous Integration

Setup Bojagi With React and Without Storybook

In this tutorial you will learn how to setup Bojagi on a React project that doesn't use Storybook already. You don't need Storybook knowledge in advance, you will learn how to write stories here.

Prerequisites

  • Experience with React components

๐Ÿด Import the example repository

  1. Generate a new repository from bojagi-tutorial-setup-full template on GitHub: https://github.com/Bojagi/bojagi-tutorial-setup-full/generate.
  2. Repository Name bojagi-tutorial-setup-full.
  3. Press 'Create repository from template'.

Now clone your new repository:

$ git clone git@github.com:YOUR_GITHUB_USER_NAME/bojagi-tutorial-setup-full.git
$ cd bojagi-tutorial-setup-full

๐Ÿ‘ฉโ€๐Ÿ’ป Install Bojagi

First you need to install the project:

Yarn
NPM
$ yarn
$ npm install

Once completed, add the Bojagi CLI to your project:

Yarn
NPM
$ yarn add -D @bojagi/cli
$ npm install --save-dev @bojagi/cli

๐Ÿ““ Write a story

Now you are going to write your first story. Bojagi stories are functions that expose your component set up with a specific set of props. These stories are put in files that by default either have an .bojagi.(jsx|tsx) or .stories.(jsx|tsx) ending and should be put next to the file that holds the corresponding component.

Let's write a story for the Button component. Create a Button.bojagi.jsx file next to the Button.jsx file and copy this to the file:

// src/components/Button.bojagi.jsx
import React from 'react';
import { Button } from './Button.jsx';

export default {
  title: 'Button',
};

export const Normal = () =>
  <Button>Hello</Button>;

The last line of above example is the story function. It returns the Button with a 'Hello' label. The default export object contains the metadata about your story, for example the title to label the component on the Bojagi UI.

๐ŸŽจ Preview your stories

Use the preview command of the Bojagi CLI to render your stories locally.

Yarn
NPM
$ yarn bojagi preview
$ npx bojagi preview

This opens the Bojagi preview app in your browser. The Button component is now visible.

๐Ÿ“š Write more stories

Currently we have one state visible in preview. Looking at the code the button has multiple variants. To show different variations of a component you can add more stories to your Button.bojagi.jsx file. Each story represents a different state your component can have.

Add the following functions at the bottom of the story file:

// src/components/Button.bojagi.jsx
export const Outline = () =>
  <Button variant="outline">Goodbye</Button>

export const Dotted = () =>
  <Button variant="dotted">Ob-la-di Ob-la-da</Button>

Stop and start the bojagi preview command again, you will see the added states under the Story title. Click through them and look how the button changes. New stories and states currently need a complete restart. For updates on existing stories, states or components a browser reload is required. We will solve this issue in the future so story and state re-indexing will work without a restart.

You can also do more complex stories: Try to experiment with the other two components if you like.

โœ… Activate your repository on Bojagi

Let's try to see Bojagi in action and upload your stories!

First activate your repository on Bojagi. Go to https://bojagi.io/app and navigate to your user. If you can't find it, you need to install the Bojagi GitHub App on your GitHub user first. Make sure to give it at least access to the forked repository.

After Bojagi is installed you will see a list of repositories that you can activate. Now choose the repository you forked and click "activate". You should see a short instruction guide. Follow this guide to upload your stories (you might have done most of it already though).

You uploaded your first stories to Bojagi! Let's try to use Bojagi with a Pull Request now!

๐Ÿ“ฅ Creating a Pull Request

Uploading components for a Pull Request is not that different from doing it on the main branch.

First create a new branch:

$ git checkout -b my-new-change

You could just change the color of the Button:

/* Line 14 of src/components/Button.css */
background-color: #6347ff;

/* Line 5 to 7 of src/components/Button.css */
background-color: #4787ff;
color: #fff;
border: 1px solid #6347ff;

When you are done, commit the change, push it to GitHub.

$ git add .
$ git commit -m 'Updated Button styles'
$ git push origin my-new-change # Followed by creating a pull request for this branch on your GitHub repository

Visit the link provided in the git push output and create a Pull Request on GitHub.

Enumerating objects: 13, done.
Counting objects: 100% (13/13), done.
Delta compression using up to 8 threads
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 21.24 KiB | 3.03 MiB/s, done.
Total 7 (delta 6), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (6/6), completed with 6 local objects.
remote:
remote: Create a pull request for 'my-new-change' on GitHub by visiting:
remote:      https://github.com/YOUR_GITHUB_USER_NAME/bojagi-tutorial-setup-full/pull/new/my-new-change
remote:
To git@github.com:YOUR_GITHUB_USER_NAME/bojagi-tutorial-setup-full.git

Now use the same deploy command that you used before:

Yarn
NPM
$ yarn bojagi deploy
$ npx bojagi deploy

After the command is finished, go back to Bojagi in your Browser, click on "Pull Requests" on the left side menu and select the Pull Request you opened before on GitHub.

You should see the changes you have done in this PR visually with the real component rendered in Bojagi. On your Pull Request in GitHub you should also see a pending status check from Bojagi.

You can now review your changes. Any change to the review updates the status check on GitHub as well.

Done! You can now add Bojagi in your or your companies projects. Check out the remaining documentation for more insights. Maybe you you want to know how to integrate Bojagi into your CI pipeline.

โ† Setup Bojagi With React and StorybookWrite Stories โ†’
  • Prerequisites
  • ๐Ÿด Import the example repository
  • ๐Ÿ‘ฉโ€๐Ÿ’ป Install Bojagi
  • ๐Ÿ““ Write a story
  • ๐ŸŽจ Preview your stories
  • ๐Ÿ“š Write more stories
  • โœ… Activate your repository on Bojagi
  • ๐Ÿ“ฅ Creating a Pull Request
Bojagi
HomepageWeb AppGitHubIssue Tracker
Copyright ยฉ 2021 Bojagi