@chordcommerce/analytics

The @chordcommerce/analytics library provides simple methods for sending tracking events to Chord from your website, with an optional debugging mode to validate event properties.

Visit docs.chord.co for guides, examples, and an API reference.

Requirements

The library supports sending events via Chord CDP or Segment. If using Segment, analytics.js must also be installed in your project.

Installation

To install @chordcommerce/analytics, run the following command in your project directory:

npm install @chordcommerce/analytics
# or
yarn add @chordcommerce/analytics

Usage

Initialize @chordcommerce/analytics as follows:

import ChordAnalytics from '@chordcommerce/analytics'

const chord = new ChordAnalytics(options) // see below for configuration options

chord.trackCartViewed({ cart }) // sends a "Cart Viewed" event to the CDP

CommonJS Import

If you are using an older version of NodeJS (<v11) or Webpack, importing using the above ES6 import will probably fail. You can instead import using CommonJS:

const { ChordPixel } = require('@chordcommerce/analytics/dist/cjs')

Configuration

@chordcommerce/analytics can be initialized with the following options:

| Property | Required | Description | | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cdp | false | Required when using a CDP other than Chord. A reference to the CDP library, or a function that returns a reference to the CDP library. For example, if using Segment's analytics.js library, this could be window.analytics or () => window.analytics. | | cdpDomain | false | Required when using Chord CDP. The Chord CDP domain. To be provided by the Chord team. | | cdpWriteKey | false | Required when using Chord CDP. The Chord CDP write key. To be provided by the Chord team. | | debug | false | Defaults to false. When set to true, events are validated against Chord's tracking plan and errors are logged. We recommend enabling this for development and disabling for production. | | enableLogging | false | Defaults to true. When set to true, errors are logged using console.log. | | formatters | true | Functions that are used to construct tracking events. There are two types of formatters, objects and events. formatters.objects is required. See below for details. | | metadata | true | Event metadata. See below for details. | | namespace | false | Defaults to chord. Changes where Chord is globally available (e.g. window.chord). Only applicable when using Chord CDP. | | stripNull | false | Defaults to true. When set to true, event properties with a null value are removed. CDPs typically treat null and undefined as separate values, so be sure you intend to send null values before setting to false. |

If cdp, cdpDomain, and cdpWriteKey are all omitted, no tracking events are sent.

Metadata

| Property | Required | Description | | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | metadata.i18n.currency | true | The order currency in ISO 4217 currency code, uppercase. For example, USD. | | metadata.i18n.locale | true | The order locale. For example, en-US. | | metadata.ownership.omsId | true | A UUID assigned by Chord. | | metadata.ownership.storeId | true | A UUID assigned by Chord. | | metadata.ownership.tenantId | true | A UUID assigned by Chord. | | metadata.platform.name | true | The e-commerce platform used. For example, Shopify. | | metadata.platform.type | true | The type of platform where the event originated. Either web or pos. | | metadata.store.domain | true | The domain of the site where the event originated. For Shopify, this should be the store slug that comes before .myshopify.com. |

Formatters

Formatters are Javascript functions that are used to construct tracking event properties. There are two types of formatters, objects and events. You must define object formatters. Event formatters are optional. See Chord’s documentation for more details and example formatters.

Object Formatters

A formatter must be provided for each of the four core data types that are used in Chord events. This formatter function transforms input data into the type Chord expects. See Chord’s documentation for more details on object formatters.

| Property | Required | Description | | ----------------------------- | -------- | ------------------------------------------- | | formatters.objects.cart | true | A function that creates a cart object. | | formatters.objects.checkout | true | A function that creates a checkout object. | | formatters.objects.lineItem | true | A function that creates a line item object. | | formatters.objects.product | true | A function that creates a product object. |

Event Formatters

A formatter can be provided for each event. This formatter is used to transform the event properties of a specific event after Chord constructs the event, just before it's sent to the CDP. See Chord’s documentation for more details on event formatters.

Using with Typescript

Optionally, you can instantiate ChordAnalytics with a custom type argument describing your data to improve type safety for formatters and SDK functions.

For instance, if you're working with objects like cart, product, etc., from a Shopify storefront API query, you might already have types like StorefrontCart defined for the response. Instantiate ChordAnalytics with a type argument:

interface ObjectTypes {
  Cart: StorefrontCart
  Checkout: StorefrontCart
  LineItem: StorefrontLineItem
  Product: StorefrontProduct
}

const chord = new ChordAnalytics<ObjectTypes>({ options })

Now, when you use an SDK method like chord.trackCartViewed({ cart }), cart has the StorefrontCart type.

Formatter types also support an optional generic type parameter for the function argument:

import type { CartFormatter } from '@chordcommerce/analytics'

export const cartFormatter: CartFormatter<StorefrontCart> = (props) => {
  const { cart } = props // `cart` has type `StorefrontCart`
  return { ... }
}

addSourceMiddleware(func: AnalyticsMiddleware)

Registers a middleware function to modify event properties before they are sent to analytics providers. Middleware functions are executed synchronously in the order they were added during event tracking.

Parameters

• func (AnalyticsMiddleware) - A middleware function that receives event data and can return additional properties to merge into the event payload.

Return Value

The middleware function can return:

• Partial - Properties to merge into the event payload
• void - No additional properties to add

Useage Example

  analytics.addSourceMiddleware(({ payload }) => {
    const { searchParams } = payload.obj.context.page;

    return {
      utm_source: searchParams.utm_source,
      utm_medium: searchParams.utm_medium,
      utm_campaign: searchParams.utm_campaign
    };
  });

  analytics.addSourceMiddleware(({ payload }) => {
    return {
      session_id: getSessionId(),
      user_agent: navigator.userAgent,
      timestamp: Date.now()
    };
  });

API Reference

See Chord’s documentation for a full API reference.

Releasing

This package uses semantic-release to automate versioning and publishing. Releases are triggered automatically — no manual version bumps or publish steps are needed.

How it works

The repo has a single CI workflow (.github/workflows/ci.yml) with two jobs:

1. test — Runs lint, prettier, build, and tests for all packages. Triggers on every push to main/beta and on every pull request.
2. release — Runs only on main and beta branches, after test passes. Runs semantic-release to determine if a new version should be published.

The release flow:

1. Merge a PR into main (stable) or beta (pre-release).
2. The test job runs. If it passes, the release job starts.
3. semantic-release analyzes commit messages since the last release tag.
4. If releasable commits exist, the package is published to npm and GitHub Packages, CHANGELOG.md is updated, and a Git tag is created.
5. If no releasable commits exist, semantic-release exits cleanly and nothing is published.

PR titles must follow conventional commits

When using GitHub's squash merge (the default), the PR title becomes the first line of the squash commit message. Semantic-release only parses the first line to determine the version bump, so the PR title must use a conventional commit prefix (e.g., fix: resolve consent race condition). Individual commit messages in the PR body are ignored.

If the PR title does not start with a releasable prefix, no release will be published even if the individual commits within the PR use fix: or feat:.

When a release happens (and when it doesn't)

A release is published only when all three conditions are met:

1. A push lands on main or beta (via merged PR or direct push)
2. Tests pass
3. There are new commits since the last release tag with a releasable prefix (checked against the first line of each commit message)

Releasable commit prefixes (these trigger a version bump):

| Prefix | Version Bump | Example | | -------------------------- | --------------------- | --------------------------------------------------------- | | fix: | Patch (1.0.0 → 1.0.1) | fix: resolve race condition in consent adapter | | feat: | Minor (1.0.0 → 1.1.0) | feat: add trackOrderCompleted method | | BREAKING CHANGE: in body | Major (1.0.0 → 2.0.0) | Commit body contains BREAKING CHANGE: remove legacy API |

Non-releasable prefixes (these do NOT trigger a release):

chore:, ci:, docs:, refactor:, test:, style:, build:, perf:

If a merge to main or beta contains only non-releasable commits, the release job runs but semantic-release determines no release is needed and exits without publishing.

Monorepo scoping

This repo uses semantic-release-monorepo to scope releases to individual packages. Only commits that touch files within a package's directory (e.g., packages/core/) are considered when determining the next version. A feat: commit that only modifies .github/workflows/ or another package's directory will not trigger a release for @chordcommerce/analytics.

Pre-releases

Merging to beta creates pre-release versions (e.g., 1.22.0-beta.1). Use this for testing before promoting to main. Only main and beta are currently configured for automatic releases in the CI workflow. Additional prerelease branches (e.g., alpha) can be enabled by adding them to both the workflow's branch filter in ci.yml and the semantic-release branch config.

Beta release workflow

1. Create a feature branch off beta and do your work.
2. Create a PR targeting the beta branch and merge it.
3. The CI workflow runs tests, then semantic-release publishes a beta version (e.g., 1.22.0-beta.1).
4. Install with: npm install @chordcommerce/analytics@beta

Promoting beta to production

1. Create a PR from beta → main and merge it.
2. The CI workflow runs tests, then semantic-release publishes a stable version on main.

Dry run

You can preview what a release would do without publishing by manually triggering the CI workflow in GitHub Actions with dryRun set to true.

Support

For support with setup and configuration, please contact Chord directly at [email protected].