@spotify/backstage-plugin-soundcheck-common

Spotify Plugins for Backstage: Soundcheck - Common

Shared functionality for the Spotify Backstage Soundcheck plugin.

Validating Soundcheck YAML configs in CI

This package exports Zod schemas and validate* helpers so you can validate your Soundcheck YAML configuration files (checks, tracks, campaigns) offline in CI — no running Soundcheck instance required.

This complements the runtime CRUD API: schemas are pinned to your installed npm version, so CI builds remain green even if Soundcheck is down.

Basic usage

You'll need a YAML parser. We recommend yaml (yarn add -D yaml) or js-yaml. The examples below use yaml. The validate* helpers expect already-parsed JavaScript values, not raw YAML strings — call your parser first.

import yaml from 'yaml'; // or any YAML parser
import { readFileSync } from 'node:fs';
import { validateChecks } from '@spotify/backstage-plugin-soundcheck-common';

const result = validateChecks(yaml.parse(readFileSync('checks.yaml', 'utf8')));

if (!result.success) {
  result.error.issues.forEach(issue =>
    console.error(`✖ ${issue.path.join('.') || '<root>'}: ${issue.message}`),
  );
  process.exit(1);
}

// result.data is fully typed: an array of validated check objects.

The same pattern applies to validateTracks and validateCampaigns.

Example GitHub Actions workflow

# .github/workflows/validate-soundcheck.yml
name: Validate Soundcheck configs
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: node scripts/validate-soundcheck-configs.mjs

// scripts/validate-soundcheck-configs.mjs
import yaml from 'yaml';
import { readFileSync } from 'node:fs';
import {
  validateChecks,
  validateTracks,
  validateCampaigns,
} from '@spotify/backstage-plugin-soundcheck-common';

const files = [
  ['soundcheck/checks.yaml', validateChecks],
  ['soundcheck/tracks.yaml', validateTracks],
  ['soundcheck/campaigns.yaml', validateCampaigns],
];

let failed = 0;
for (const [path, validate] of files) {
  const result = validate(yaml.parse(readFileSync(path, 'utf8')));
  if (!result.success) {
    console.error(`\n✖ ${path}`);
    result.error.issues.forEach(issue =>
      console.error(`  ${issue.path.join('.') || '<root>'}: ${issue.message}`),
    );
    failed++;
  } else {
    console.log(`✓ ${path}`);
  }
}
process.exit(failed > 0 ? 1 : 0);