Spectral 10.35 Upgrade Guide

@prismatic-io/spectral@10.35.1 adds public entry points for the HTTP client and testing utilities, and deprecates imports from Spectral's dist/ paths, such as @prismatic-io/spectral/dist/clients/http.

Why this change?

A dist/ path points at a file in Spectral's compiled output rather than at a supported API, so it can break when Spectral's build changes. The public entry points name the API you're using, and they resolve with both the node and bundler TypeScript moduleResolution settings, so they work with the legacy webpack toolchain and the recommended toolchain.

Do I need to change my imports now?

Not right away. In Spectral 10.35.1 and later, dist/ paths that existed before 10.35.1 still resolve to the same modules, so existing custom connectors and code-native integrations keep building. They'll be removed in a future release, so move to the public entry points when you upgrade.

Public entry points

Import from	For
@prismatic-io/spectral	Everything else, including the conditionalLogic and util namespaces, error classes, types, and context helpers
@prismatic-io/spectral/http	The HTTP client, such as createClient and handleErrors
@prismatic-io/spectral/testing	Testing utilities, such as invoke, invokeFlow, and createConnection

Update existing projects

Update Spectral

npm install @prismatic-io/spectral@latest

The public entry points require Spectral 10.35.1 or later.

Run the public entry points codemod

Commit or stash your work, then run the public-entry-points codemod from your project's directory:

npx @prismatic-io/spectral-codemod@latest public-entry-points --target-spectral 10.37.0 .

Set --target-spectral to the Spectral version you installed in the previous step.

The codemod rewrites imports of these paths, including the same paths with a .js extension or a trailing slash, and in require() calls, dynamic import(), and mocks such as vi.mock():

From	To
@prismatic-io/spectral/dist, @prismatic-io/spectral/dist/index	@prismatic-io/spectral
@prismatic-io/spectral/dist/clients/http, @prismatic-io/spectral/dist/clients/http/index	@prismatic-io/spectral/http
@prismatic-io/spectral/dist/testing	@prismatic-io/spectral/testing

src/client.ts

-import { createClient } from "@prismatic-io/spectral/dist/clients/http";
+import { createClient } from "@prismatic-io/spectral/http";

Add --dry-run to list the files that would change without writing them. For more options, see Spectral codemods.

Update the remaining dist/ imports

The codemod prints a warning: line for each file that still imports another dist/ path, because those paths don't map one-to-one to an entry point. Update them by hand. Most of what they provide is exported from @prismatic-io/spectral:

If you import from	Import instead
@prismatic-io/spectral/dist/conditionalLogic	conditionalLogic from @prismatic-io/spectral, then call conditionalLogic.isEqual
@prismatic-io/spectral/dist/errors	The error classes from @prismatic-io/spectral
@prismatic-io/spectral/dist/types	The types from @prismatic-io/spectral
@prismatic-io/spectral/dist/util	util from @prismatic-io/spectral
@prismatic-io/spectral/dist/serverTypes	requireContext, requireIntegrationContext, or findUserDefinedComponentKey from @prismatic-io/spectral

src/flows.ts

-import { isEqual } from "@prismatic-io/spectral/dist/conditionalLogic";
+import { conditionalLogic } from "@prismatic-io/spectral";

-if (isEqual(left, right)) {
+if (conditionalLogic.isEqual(left, right)) {

Build and test

Run your type checker, tests, and build to confirm that every import resolves:

npx tsc --noEmit
npm test
npm run build