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
- Generate a new repository from bojagi-tutorial-setup-full template on GitHub: https://github.com/Bojagi/bojagi-tutorial-setup-full/generate.
- Repository Name
bojagi-tutorial-setup-full
. - 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 install
Once completed, add the Bojagi CLI to your project:
$ 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 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 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.