https://github.com/trycourier/courier-web
Courier's browser SDKs
https://github.com/trycourier/courier-web
Last synced: 3 months ago
JSON representation
Courier's browser SDKs
- Host: GitHub
- URL: https://github.com/trycourier/courier-web
- Owner: trycourier
- License: mit
- Created: 2025-03-31T23:49:54.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-13T19:30:31.000Z (4 months ago)
- Last Synced: 2026-04-13T21:39:17.541Z (4 months ago)
- Language: TypeScript
- Homepage: https://www.courier.com
- Size: 1.96 MB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `courier-web`
A monorepo that contains all packages for Courier's browser SDKs.
## Getting Started
### In VSCode IDEs
1. Open the `.vscode` folder, click `courier-web.code-workspace` then click the blue **"Open Workspace"** button in the bottom right
2. Click the **"Sync Packages"** button to install all dependencies
This will set up your development environment with all the necessary packages and configurations.
> You may need to click **"Sync Packages"** during development if some local packages get out of sync with each other.
### In the console
The Courier Web monorepo uses [Yarn workspaces](https://classic.yarnpkg.com/blog/2017/08/02/introducing-workspaces/) to manage dependencies.
1. Get setup with Node (using [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating)) and [Yarn](https://classic.yarnpkg.com/lang/en/docs/install)
```sh
nvm use
```
2. From the `courier-web` directory, install workspace dependencies. This will:
- Install top-level dependencies
- symlink each workspace into the top-level **node_modules**
- Install workspaces' dependencies in their respective **node_modules**.
```sh
yarn install
```
3. Build the packages
```sh
yarn build-packages
```
## Packages
| Package | Description |
|---------|-------------|
| [`courier-js`](./@trycourier/courier-js) | The base API client and shared instance singleton for Courier's JavaScript Browser SDK |
| [`courier-ui-core`](./@trycourier/courier-ui-core) | Web components used in UI level packages |
| [`courier-ui-inbox`](./@trycourier/courier-ui-inbox) | Web components for Courier Inbox |
| [`courier-ui-toast`](./@trycourier/courier-ui-toast) | Web components for Courier Toast |
| [`courier-react-components`](./@trycourier/courier-react-components/) | Shared package of React components for `courier-react` and `courier-react-17` |
| [`courier-react`](./@trycourier/courier-react) | React 18+ components for Courier Inbox |
| [`courier-react-17`](./@trycourier/courier-react-17/) | React 17 components for Courier Inbox |
## API Extractor
The public API specification found in [**api**](./api/) is generated by
[API Extractor](https://api-extractor.com).
Maintaining the spec programmatically helps ensure any public-facing changes to a package's implementation are intentionally added to the spec. The
[build-package](.github/workflows/build-packages.yml) and
[release](.github/workflows/release.yml) workflows run API Extractor and fail if the
output differs from the API spec in the PR.
### Updating the API spec
If you make changes to the public API surface, re-run API Extractor locally to update
the spec in the same PR. API Extractor generates the spec from the _built_ package, rather
than the source files.
#### Updating all packages
To update the API spec for all packages, run:
```sh
yarn generate-api-docs
```
This will:
1. Build all packages locally
2. Generate API docs for all packages with the `--local` flag
#### Updating a single package
To update the spec for a single package, first build the package:
```sh
yarn workspace @trycourier/courier-js run build
```
Then run API Extractor:
```sh
yarn workspace @trycourier/courier-js run generate-api-doc --local
```
The `--local` flag automatically updates the spec in [**api**](./api/) based on the generated API. The CI runs _without_ this flag to validate the output matches the existing spec.
### API Extractor warnings
API Extractor may generate warnings on the command line or in the API spec itself.
For example [ae-forgotten-export](https://api-extractor.com/pages/messages/ae-forgotten-export/)
indicates a referenced symbol isn't exported by the API.
Warnings on the command line will fail a production build and must be resolved before
merging the updated spec. If a warning is safe to ignore, add it to the package's
respective **api-extractor.json** configuration to add to the API spec rather than log to the command line ([example](https://github.com/trycourier/courier-web/blob/c1a7b733d711c81cb3c472028b91462f45086ba0/%40trycourier/courier-js/api-extractor.json#L31-L34)). It is strongly preferred to resolve an instance of an error or warning
rather than ignore all instances.
## Versioning and releasing
Package versions and changelogs are maintained by [changesets](https://github.com/changesets/changesets).
### Steps for courier-web developers
1. [Add a changeset file](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md) to your PR,
either by running `yarn changeset` or using the [Changeset bot](https://github.com/apps/changeset-bot)
that validates PRs contain changeset files.
2. Changesets will maintain a PR titled "Version Packages" ([example](https://github.com/trycourier/courier-web/pull/127))
that bumps package versions appropriately and maintains the changelog.
3. Close then re-open the PR to trigger tests to run. This is a workaround since
[GitHub Actions do not run in response to PRs opened with `GITHUB_TOKEN`](https://docs.github.com/en/actions/concepts/security/github_token#when-github_token-triggers-workflow-runs).
4. When you're ready to release, merge the "Version Packages" PR. Changesets will release
the packages with version bumps automatically via GitHub Actions to npm.
### Troubleshooting releases
* **The "Version Packages" PR was merged, but packages weren't released**
This can happen if there is a problem building packages that didn't present when the CI
ran for the PR or if there was an issue connecting to the npm registry.
Solution:
1. Click **Revert** on the "Version Packages" PR to generate a clean revert PR
([example](https://github.com/trycourier/courier-web/pull/122)).
2. Get the revert PR approved then merge it to the **main** branch.
3. Make any changes to fix the build and release process in other PRs, and merge
those to **main**.
4. As the revert PR and any subsequent fixes are merged, Changesets will re-run to
generate a new "Version Packages" PR that will apply the original version bumps and
release packages.
* **The "Version Packages" PR is blocked on the "tests" check**
Running build and test workflows on the "Version Packages" PR is the best way to ensure
the build and tests will pass when the package is deployed to npm. The repository's
branch protection rules prevent merging PRs if tests haven't run or failed.
GitHub Actions events triggered by `GITHUB_TOKEN` will not create a new workflow run.
This prevents tests from automatically running when `GITHUB_TOKEN` is used to open the
"Version Packages" PR. See the
[GitHub docs](https://docs.github.com/en/actions/concepts/security/github_token#when-github_token-triggers-workflow-runs) for more details.
Solution:
1. Close then re-open the PR to trigger tests to run. This is a [documented workaround](https://github.com/peter-evans/create-pull-request/blob/b4733b9419fd47bbfa1807b15627e17cd70b5b22/docs/concepts-guidelines.md#workarounds-to-trigger-further-workflow-runs).
### Trusted Publishing
Packages are published using [NPM's trusted publishing workflow](https://docs.npmjs.com/trusted-publishers), meaning a long-lived write token is not required to publish.