@brighte/platform-core-utils

A shared internal utilities package for Brighte platform teams.

This package provides reusable helpers and utilities that are common across multiple repositories. It is designed to grow incrementally — each module is lightweight, independently testable, and isolated from unrelated dependencies. Currently includes Pact contract testing utilities, with more modules planned.

Modules

| Module | Entry point | Status | Description | | ------ | ----------- | ------ | ----------- | | pact | @brighte/platform-core-utils | ✅ Ready | Helpers for Pact consumer contract testing | | pact/config | @brighte/platform-core-utils/config | ✅ Ready | Vitest config factory for pact test runs | | pact/publish | @brighte/platform-core-utils/publish | ✅ Ready | Script helper to publish pacts to a broker |

New modules go in src/<module>/ and are exported from a dedicated subpath if they carry different dependencies. See CLAUDE.md for contribution guidelines.

Installation

npm install --save-dev @brighte/platform-core-utils

@pact-foundation/pact, graphql, and @graphql-typed-document-node/core install automatically as dependencies.

Install peer dependencies for optional features:

# For vitest config (createPactVitestConfig)
npm install --save-dev vitest vite-tsconfig-paths

# For publishing pacts (publishPacts)
npm install --save-dev @pact-foundation/pact-node

Note: Published to npm under the @brighte scope. Ensure your project's .npmrc is configured with the correct auth token.

Pact module

Creating a provider

import { createProvider } from '@brighte/platform-core-utils';

export const provider = createProvider({
  consumer: 'my-app',
  provider: 'api-service',
  logLevel: 'info', // optional, defaults to PACT_LOG_LEVEL env var or 'warn'
  dir: './generated-pacts', // optional, defaults to './generated-pacts'
});

Building GraphQL interactions

import { createGraphqlQueryInteraction } from '@brighte/platform-core-utils';
import { MatchersV3 } from '@pact-foundation/pact';
import { someQuery } from './queries.graphql';

const interaction = createGraphqlQueryInteraction({
  state: 'user with id 123 exists',
  uponReceiving: 'a request for user data',
  query: someQuery,
  variables: { id: '123' },
  responseBody: {
    user: MatchersV3.like({ id: '123', name: 'John Doe' }),
  },
});

Vitest config

// pact/setup/config.ts
import tsconfigPaths from 'vite-tsconfig-paths';
import { defineConfig } from 'vitest/config';
import { createPactVitestConfig } from '@brighte/platform-core-utils/config';

export default defineConfig({ ...createPactVitestConfig(), plugins: [tsconfigPaths()] });

Publishing pacts

// pact/setup/publish.pact.ts
import { publishPacts } from '@brighte/platform-core-utils/publish';

await publishPacts();

CI deploy checks

// pact/setup/can-i-deploy.ts
import { canIDeploy } from '@brighte/platform-core-utils';

const environment = process.env['ENVIRONMENT'];
if (!environment) { console.error('ENVIRONMENT is not set'); process.exit(1); }
canIDeploy({ pacticipant: 'my-app', toEnvironment: environment });

// pact/setup/record-deployment.ts
import { recordDeployment } from '@brighte/platform-core-utils';

const environment = process.env['ENVIRONMENT'];
if (!environment) { console.error('ENVIRONMENT is not set'); process.exit(1); }
recordDeployment({ pacticipant: 'my-app', environment });

For the full pact setup guide see docs/pact.md.

Development

npm install       # install deps
npm run build     # compile CJS + ESM to dist/
npm run lint      # eslint
npm test          # vitest
npm run clean     # remove dist/

Versioning and release

This package uses semantic versioning. Publishing to npm happens automatically on every merge to main.

1. Bump package.json version (e.g. 1.0.0 → 1.1.0)
2. Update CHANGELOG.md
3. Commit and open a PR against main
4. Once merged, publish.yml runs and publishes to npm

If the version in package.json was not changed, the publish step will skip (no re-publish of an existing version).

Publishing workflows

| Workflow | Trigger | Purpose | | -------- | ------- | ------- | | ci.yml | push / PR to main | build, lint, test, circular dep check | | publish.yml | merge to main | publish stable release to npm | | beta.yml | manual dispatch | publish beta dist-tag |