- 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

$3

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

$3

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.

$3

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.

$3

"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 >=20.18

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.

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

function App() {
return (


export default App;
`

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

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

$3

- 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 Launchpad Team, you can reach out to us in the #blueprint Slack channel.

Testing

See more in Testing docs.