@box/blueprint-web

• Blueprint web
  • Overview
  • Contribution
    • Step 1: Create a feature branch
    • Step 2: Push your feature branch
    • Step 3: Open Pull request
    • Commit Types
  • Package Installation
  • Component Development
  • Prerequisites
  • Project setup
  • Use Blueprint web components
    • Project scripts
  • Ownership
  • Testing

Blueprint web

Blueprint web is a comprehensive collection of UI components that can be used by engineering teams for product development. You can check out already delivered components in our Portal.

Overview

Blueprint web is next step after BUIE library which currently has a list of disadvantages. Learn more about the investigation and decision on Blueprint web from the initial investigation.

The main benefits of Blueprint web:

• no need to create Box widely used UI components from scratch
• all components are placed in one package
• all components have up-to-dated UI
• component are well-composable and easy to use
• repository is maintained by the #blueprint team.

Contribution

Step 1: Create a feature branch

Create a branch with a descriptive name, such as add-icon-button.

Step 2: Push your feature branch

We use semantic-release and the conventional commit message format.

Keep a separate feature branch for each issue you want to address. As you develop code, continue to push code to your feature branch.

The commit message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. For a list of tags, please click here. See the default release rules based on the commit tag. Note that you must include the exact keyword "BREAKING CHANGE" for breaking changes, to learn more click here.

Shown below are examples of the release type that will be done based on a commit message.

Step 3: Open Pull request

Make sure the title of your PR includes a Jira ticket number - this will automatically update your Jira ticket and move it to 'In Review' status.

Add a pull request description - describe the expected outcome and motivation for your change. Link to the PR will be included in the changelog, so a good description will make it easy to understand and provide migration/usage guidelines for your code.

Commit Types

"Semantic versioning" means that changes to the version number of the package (e.g. 3.42.11 to 3.43.0) are done according to rules that indicate how the change will affect consumers. Read more on the npm page.

The version number is broken into 3 positions — Major.Minor.Patch. In semantic release terms, changes to the numbers follow Breaking.Feature.Fix. The semantic-release script parses commit messages and decides what type of release to make based on the types of commits detected since the last release.

The rules for commit types are:

• Anything that changes or removes an API, option, or output format is a BREAKING CHANGE.
• Anything that adds new functionality in a backwards-compatible way is a feature (feat). Consumers have to upgrade to the new version to use the feature, but nothing will break if they do so.
• Bugfixes (fix) for existing behavior are a patch. Consumers don't have to do anything but upgrade.
  • Performance fixes (perf) and reverts (revert) are treated as patch releases.
  • Automated commits from Box's internalization team cause a patch because they will use the format fix(moji): ***.
• Other prefixes, such as docs, don't trigger releases and don't appear in the changelog. These tags signal that there are no external changes to any APIs (including non-breaking ones). Changes from these types of commits will get released only when the release script detects other releasable commits ( feat/fix) going out at the same time.
  • build, ci, chore, docs, refactor, style, test

In most cases, commits will be a feat or fix. Make sure to include the BREAKING CHANGE string in the summary if there are non-backwards-compatible changes in the commit.

See more in Contribution docs.

Package Installation

If you want to use Blueprint web as a package, you need to install it as a dependency:

yarn add @box/blueprint-web

Blueprint web requires certain peer dependencies to be installed manually to prevent library duplication. For a list of required peer dependencies, see package.json.

Component Development

If you want to start developing and adding your own components, you need to set up the project first. The library is generated with Nx.

Prerequisites

• The required node version is >=18.16 < 19.0.0.

Project setup

To set up the development environment, perform the following steps:

1. Clone the repository using SSH protocol by following the guide here

2. At the root directory, run the following commands to run the storybook:

    yarn install
   
    yarn bootstrap
   
    yarn nx storybook blueprint-web
   

Use Blueprint web components

This example shows a way you can use the Button component in your app. Styles are automatically imported when you import any Blueprint web component.

import { Button } from '@box/blueprint-web';

function App() {
    return (
        <div className="App">
            <Button>Button</Button>
        </div>
    );
}

export default App;

You also need to extend your project webpack.config.js with next rule:

module: {
    rules: [
        {
            test: /\.(js|mjs)$/,
            resolve: {
                fullySpecified: false, // don't require .mjs extension for module packages
            },
        },
    ];
}

Project scripts

• yarn nx storybook blueprint-web to build and run Storybook
• yarn nx test blueprint-web to execute unit&accessibility tests via Jest
• yarn nx lint blueprint-web to check linting
• yarn nx g @nx/react:component MyNewComponentName --project=blueprint-web --export to generate new component (Documentation)
• yarn nx g @nx/react:component-story --project=blueprint-web --componentPath lib/MyNewComponentName/MyNewComponentName.tsx to generate new Storybook story for your component

Ownership

This repo is owned and maintained by the Design System Team, you can reach out to us in the #blueprint Slack channel.

Testing

See more in Testing docs.