Spectral 10.22 Upgrade Guide

@prismatic-io/spectral@10.22 and @prismatic-io/prism@10.0 introduce a new recommended toolchain for code-native integrations and custom connectors.

Why this change?

The legacy toolchain we've recommended in the past (webpack, eslint, etc) was cutting-edge when we first introduced custom connectors and code-native integrations, but the JavaScript ecosystem has changed a lot since then. The new toolchain is more modern, faster, and easier to use.

Do I need to change my toolchain?

No. While we have a recommended toolchain, you can use any Node.js tool that can import @prismatic-io/spectral and produce a a CJS bundle. Some of our customers have successfully used esbuild, rollup, bun, and other tools.

Can I create a new code-native integration or custom connector with the legacy toolchain?

Yes. Run prism integrations:init --toolchain legacy or prism components:init --toolchain legacy to create a new code-native integration or custom connector with the legacy toolchain.

New recommended toolchain

	Legacy Tool	New Recommended Tool
Build	webpack	tsdown
Formatting/Linting	eslint / prettier	biome
Unit Testing	jest	vitest
TypeScript	typescript@5.x	typescript@6.x

Update existing projects

If you'd like to update an existing code-native integration or custom connector to use the new recommended toolchain, take the following steps:

Update your dependencies

Remove legacy toolchain:

npm uninstall --save-dev @prismatic-io/eslint-config-spectral @types/jest copy-webpack-plugin eslint jest ts-jest ts-loader webpack webpack-cli

Install new recommended tools:

npm install @prismatic-io/spectral@10.22.0
npm install --save-dev typescript@6.0.3
npm install --save-dev @biomejs/biome@2.5.1 tsdown@0.22.3 vitest@4.1.9

Update your package.json

Remove the unnecessary eslintConfig block from your package.json file and update build, test, and lint scripts to use the new recommended tools.

package.json

diff --git a/package.json b/package.json
index 67fee06..a7b1f27 100644
--- a/package.json
+++ b/package.json
@@ -4,20 +4,14 @@
   "main": "index.js",
   "private": true,
   "scripts": {
-    "build": "webpack",
+    "build": "tsdown",
     "publish": "npm run build && prism components:publish",
     "generate:manifest": "npm run build && npx @prismatic-io/spectral component-manifest",
     "generate:manifest:dev": "npm run build && npx @prismatic-io/spectral component-manifest --skip-signature-verify",
-    "test": "jest",
-    "lint": "eslint --ext .ts .",
+    "test": "vitest run",
+    "lint": "biome lint .",
     "typecheck": "tsc --noEmit"
   },
-  "eslintConfig": {
-    "root": true,
-    "extends": [
-      "@prismatic-io/eslint-config-spectral"
-    ]
-  },
   "dependencies": {
     "@prismatic-io/spectral": "10.21.0"
   },

Remove legacy toolchain configuration files

rm jest.config.js webpack.config.js

Add new toolchain configuration files

Create the following files:

biome.json

{
  "$schema": "https://biomejs.dev/schemas/2.5.1/schema.json",
  "files": {
    "includes": ["**", "!**/dist", "!**/node_modules"]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  },
  "linter": {
    "enabled": true,
    "rules": {
      "preset": "recommended",
      "suspicious": {
        "noExplicitAny": "off",
        "noTsIgnore": "off"
      }
    }
  }
}

tsdown.config.mts

import { defineConfig } from "tsdown";

export default defineConfig({
  entry: { index: "src/index.ts" },
  format: "cjs",
  outDir: "dist",
  platform: "node",
  clean: true,
  dts: false,
  deps: {
    alwaysBundle: () => true,
    onlyBundle: false,
  },
  outExtensions: () => ({ js: ".js" }),
  outputOptions: { exports: "named" },
  loader: {
    ".md": "text",
  },
  copy: [{ from: "assets/*", to: "dist" }],
});

vitest.config.ts

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    environment: "node",
  },
});

Update your tsconfig.json configuration

We've moved from TypeScript 5 to 6. Replace tsconfig.json with the following:

tsconfig.json

{
  "compilerOptions": {
    "target": "es2022",
    "lib": ["es2022"],
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "types": ["vitest/globals"],
    "skipLibCheck": true
  },
  "include": ["src", ".spectral/*"]
}