Quick Start

Getting Started

Disclaimer: This document is targeted to developers and/or system engineers. If you don't have the technical knowledge of your product, please contact a person in your organization that knows how to handle this.

To start using Bojagi you need to set up the following things:

  • Install the Bojagi app in GitHub
  • Activate your repository in the Bojagi webapp
  • Add/Install the Bojagi CLI to your CI environment
  • Build and upload your components using the Bojagi repository secret

After the first components have been uploaded you are able to see your components.

Currently components can only be rendered on a pull request. We will be soon introducing rendering components of all your branches.

Requirements

Currently Bojagi can only run when using the following technologies:

  • React 16.8+
  • Webpack 4+
  • Node.js 12+

In the future we will widen the supported technologies to support all your projects.

Activate your repository

Activating your repository on Bojagi is really easy. After logging into the Bojagi webapp you see all organizations and users that have the Bojagi GitHub app installed. Choose the one you want to activate the repository for. Please make sure the Bojagi GitHub App is installed on that organization, otherwise it will not show up in that list.

You will find a list of all the repositories. On the top you will find active ones, below the ones that are not used yet.

To activate a repository just click on one of the inactive ones. Here you need to click the "activate" button. Afterwards your repository will be active and a small introduction guide is shown.

Create a Component

Create a component file src/Box.js

import React from 'react';

export default function Box(props) {
  return (
    <div style={{backgroundColor: props.color, padding: '2rem'}}>
      {props.children}
    </div>
  );
}

Write your first story

Create a story file src/Box.bojagi.js

import React from 'react';
import Box from './Box';

export const yellow = () => <Box color="yellow">I am a yellow Box!</Box>;

export const green = () => <Box color="green">I am so green!</Box>;

For a more detailed documentation of how to write stories go to the Write Stories Section

Add the Bojagi CLI to your CI environment

Currently Bojagi only works in your CI (you can also use it manually, but it is not advised). We support the usual CI environments with almost no configuration. See a full list of supported CIs under the CI section.

Install the CLI in your repository through npm/yarn.

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

To test if the cli is installed correctly run

$ yarn bojagi --version
$ npx bojagi --version

Build and upload components

To authorize your calls to Bojagi you need to add the BOJAGI_SECRET environment variable to the CI settings. You can find the secret in the setup guide you will see after activating your repo.

export BOJAGI_SECRET=MY_TOP_SECRET_SECRET_123

Uploading components is as easy as this:

$ yarn bojagi deploy
$ npx bojagi deploy

The deploy command does the following things in one go:

  • scan for components
  • bundle components with webpack
  • upload the components to Bojagi

You can also use separate commands to perform these steps. This is particularly useful, when using additional analysis or you are collecting metadata (like props from storybook or jest).

For advanced usage of the CLI go to the CLI section.

Next steps

After all this is done and you created your first pull request that triggered the CLI in your CI environment, the components quickly show up on the webapp. Navigate to the repository and you will see all open Pull requests. Click on the one you committed changes to and see all your beautiful components!

Frequently Asked Questions →