@guardian/braze-components

中文文档
23.0.2发布于 2026/06/24MITTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 1.6万

React components to render messages from Braze

原始使用文档
文档目录7 节
  1. Development
  2. Local Setup
  3. Storybook
  4. Point a project to your local version of @guardian/braze-co…
  5. Publishing to NPM
  6. Steps following merge to main
  7. CI/CD

Braze Components

A library of React components for displaying Braze messages on DCR and frontend.

Braze messages are exposed in two ways to address two separate use cases.

  1. One-shot messages
  2. Persistent notifications

One-shot messages use Braze's in-app messages to show a user a single message impression. This is analagous to an ad impression. As with ads, these messages are often competing with other systems for shared message slots on the page. These messages are exposed by the BrazeMessages class.

Persistent notifications are backed by Braze content cards. These notifications persist until they are dismissed (automatically or by the user), or they expire. Notifications from different sources can peacfully co-exist. These notifications are exposed by the BrazeCards class.

Development

Local Setup

$ bin/setup

Storybook

We use Storybook when building components. Run Storybook with:

$ pnpm storybook

The Grid image picker integration in Storybook requires auth. If necessary you'll be redirected to the gutools login service. When developing, this means running the login service locally. Often when developing you won't need to use the image picker. In this case you can skip auth entirely by running Storybook like this:

$ STORYBOOK_DISABLE_AUTH=true pnpm storybook

This means you won't need to run the login service locally.

Point a project to your local version of @guardian/braze-components

Sometimes it's useful to test a braze-components change against a locally running version of a project which uses it, for example DCR.

It is recommended to use yalc to do this.

Install yalc

Follow the instructions in the yalc README.

Build @guardian/braze-components locally

$ pnpm build

Publish your local @guardian/braze-components to the local yalc registry

In your local checkout of @guardian/braze-components, at the root:

$ yalc publish

Use the version of braze-components from the local yalc registry

$ yalc add @guardian/braze-components

For example, for DCR this should be run from within the dotcom-rendering sub-project.

This will update the local package.json with a yalc ref. This is expected, but the change shouldn't be committed.

Notes

The steps above should be repeated when you make a change to braze-components and you want to see it locally. Don't forget to re run pnpm build!

Publishing to NPM

Releasing to NPM is handled with changesets and is performed by CI.

On your feature branch, before merging, run pnpm changeset. This will interactively ask you what kind of change this is (major, minor, patch) and allow you to describe the change. Commit the generated changeset file to git and push to your branch.

When you merge the branch, a version release PR will be automatically opened. When this PR is merged, a new release will be pushed to NPM. The version change will be based on the information in your changeset file. If the version release PR isn't merged straight away, that's fine. Any other PRs with changesets merged in the meantime will cause the release PR to be updated.

Not all PRs require releasing and therefore don't need a changeset. For example a change to the README.

Steps following merge to main

For dotcom-rendering:

  • Run checkout main branch and git pull
  • Run checkout -b to start a new branch for the update PR
  • Update the braze-components dependency in dotcom-components/dotcom-components/package.json
  • Run pnpm to update the pnpm.lock file in the DCR root
  • Push the branch and create the PR in GitHub.
  • If the change involves visual changes to components, capture this via screenshots and include in the PR
  • If the change involves updates to component layout, add code to DCR Storybook files to reflect those changes
  • If necessary (it isn't always), take DCR CODE (announce first in the P&E/Dotcom CODE Semaphore chat) and deploy code there.
  • If all is good and the PR is approved, merge PR to main (in GitHub)

For frontend:

  • Run checkout main branch and git pull
  • Run checkout -b to start a new branch for the update PR
  • Update the braze-components dependency in /package.json
  • Run make install compile to update dependency lock file
  • Push the branch and create the PR in GitHub.
  • If necessary (it isn't always), take Frontend CODE (announce first in the P&E/Dotcom CODE Semaphore chat) and deploy code there.
  • If all is good and the PR is approved, merge PR to main (in GitHub)

CI/CD

Whenever you push to GitHub actions will be triggered to run Jest tests, the TypeScript compiler etc. A TeamCity build will also be triggered. On the main branch if the TeamCity build is successful Riff Raff will deploy Storybook to https://braze-components.gutools.co.uk.

版本与发布记录

@guardian/braze-components 共发布 96 个版本,首次发布于 2020/08/11;过去 12 个月发布了 2 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
23.0.2latest2026/06/244 个月前
23.0.12026/06/155 个月前
22.2.02025/04/021.6 年前
22.0.02025/03/211.7 年前
21.0.02024/09/232 年前
20.1.02024/08/282 年前

其他发布通道:beta → 13.3.0-0。

关于 @guardian/braze-components 的常见问题

@guardian/braze-components 是什么?

React components to render messages from Braze

如何安装 @guardian/braze-components?

在项目目录运行 npm install @guardian/braze-components,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@emotion/react(11.1.2)、@guardian/libs(27.1.0)、@guardian/source(12.2.0)、react(17.0.2 || 18.2.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@guardian/braze-components 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@guardian/braze-components 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@guardian/braze-components 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js 24.2。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@guardian/braze-components 可以商用吗?

@guardian/braze-components 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@guardian/braze-components 的下载量有多少?

根据 npm 官方下载统计,@guardian/braze-components 在 2026/10/17 – 2026/11/15 这 30 天内被下载 15,859 次,日均约 529 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@guardian/braze-components 还在维护吗?

最新版本 23.0.2 发布于 2026/06/24(4 个月前);至今共发布 96 个版本,其中过去 12 个月发布了 2 个;首次发布于 2020/08/11。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。