Migration Guide
Upgrading to Node 26 (CDK v8)
From v8.0.0, CDK connectors must be compatible with Node v26.13.1 or higher, and the CDK CLI, DSL and runtime packages require it to build and test. Deployed CDK connectors run on Node 26, so testing on the same version locally is what keeps a connector that passes its tests from failing after deployment. v8.0.0 does not change the CDK API; connector code written for v7 builds unchanged. To upgrade an existing connector project:
-
Upgrade Node on your machine to v26.13.1 or higher. Verify with
node -v. With nvm:nvm install 26 && nvm use 26. Adding a.nvmrcfile containing26to the project keeps everyone on the same line. -
Update the CLI using
npm install -g @trayio/cdk-cli. Verify you are on 8.0.0 or higher usingtray-cdk version. -
Update the versions for
@trayio/cdk-dsland@trayio/cdk-runtimein the connector'spackage.jsonfile:
\{
"@trayio/cdk-dsl": "^8.0.0",
"@trayio/cdk-runtime": "^8.0.0"
\}
-
Delete the
node_modulesfolder andpackage-lock.jsonfile, then re-runnpm ion the connector directory to install dependencies freshly. Newer Node versions remove some deprecated APIs, so other third-party dependencies may need updating too. -
Run
npm run buildandnpm testto confirm the connector builds and its tests pass on Node 26, then deploy it again so the deployed version is the one you tested.
The platform refuses to build a connector whose package.json declares @trayio/cdk-dsl or @trayio/cdk-runtime with a range that cannot resolve to v7.0.0 or higher (for example "^6.0.0"). The deployment ends in BuildFailed with a message naming the package and the fix. "*", "^7.0.0" and "^8.0.0" are all fine. See Minimum CDK version for deployments.
Upgrading to Node 24 (CDK v7)
From v7.0.0, CDK connectors must be compatible with Node v24.22.1 or higher, and the CDK CLI, DSL and runtime packages require it to build and test. To upgrade an existing connector project:
-
Upgrade Node on your machine to v24.22.1 or higher. Verify with
node -v. -
Update the CLI using
npm update -g @trayio/cdk-cli. Verify you are on 7.0.0 or higher usingtray-cdk version. -
Update the versions for
@trayio/cdk-dsland@trayio/cdk-runtimein the connector'spackage.jsonfile:
\{
"@trayio/cdk-dsl": "7.0.0",
"@trayio/cdk-runtime": "7.0.0"
\}
-
Delete the
node_modulesfolder andpackage-lock.jsonfile, then re-runnpm ion the connector directory to install dependencies freshly. -
Run
npm run buildandnpm testto confirm the connector builds and its tests pass on Node 24 before deploying.
Upgrading CDK to v4
The v4 of CDK introduces two major changes. With v4, you get:
- a global config object that gets passed to every operation of the connector
- Raw HTTP operation
To use v4:
If you are building your first connector, update your cdk-cli using npm update -g @trayio/cdk-cli
and just follow the Quickstart guide which uses CDK v4.
If you have built a connector before using v3 or lower and want to migrate the connector to v4 you will have to make a few changes to the code.
Here are the recommended steps for upgrading existing connectors:
1. Update the CLI
Update your cdk-cli using npm update -g @trayio/cdk-cli. Verify you are on 4.0.0 or higher using tray-cdk -v.
2. Update the connector
-
Run
npm run buildon the connector folder. This will create aGlobalConfig.tsfile insrcfolder. -
You will also need update the versions for
@trayio/cdk-dsland@trayio/cdk-runtimein thepackage.jsonfile as shown below:
\{
"@trayio/cdk-dsl": "4.0.0",
"@trayio/cdk-runtime": "4.0.0"
\}
- Delete the
node_modulesfolder andpackage-lock.jsonfile. Now, re-runnpm ion the connector directory to install dependencies freshly.
GlobalConfig.ts
This file allows you set configs that can be used across all operations. Some things that can be initialized at the global level are:
- AuthType
- Base URL (withBaseUrl)
- Headers (withHeader)
Here is a sample where base_url and bearerToken have been initialized globally.
import { OperationGlobalConfigHttp } from "@trayio/cdk-dsl/connector/operation/OperationGlobalConfig";
import { TmdbAuth } from "./TmdbAuth";
/*
* IMPORTANT NOTE: DO NOT DELETE THIS FILE
* This is a global configuration that is used by all operations in the connector.
* Update OperationGlobalConfigHttp.create<never> to use the right Auth type of the connector e.g. OperationGlobalConfigHttp.create<AuthType>
* Update the baseUrl to the base url of the API.
* To configure the auth use the withBearerToken method or use addHeader method to add custom headers.
*
* IMPORTANT NOTE: Do not change the name of the variable `globalConfigHttp` as it is used by the internal Raw Http Operation.
* You can ignore this configuration if you have disabled the Raw Http Operation in connector.json
*/
export const globalConfigHttp = OperationGlobalConfigHttp.create<TmdbAuth>()
.withBaseUrl((_ctx) => `https://api.themoviedb.org`)
.withBearerToken((ctx) => ctx.auth!.user.access_token);
Update operations
Now that you have initialized the GlobalConfig.ts file, the global config can be passed to every operation using withGlobalConfiguration(globalConfigHttp). Here is a sample:
import { globalConfigHttp } from "../GlobalConfig";
export const getMoviesByGenreHandler = OperationHandlerSetup.configureHandler<
TmdbAuth,
GetMoviesByGenreInput,
GetMoviesByGenreOutput
>((handler) =>
handler.withGlobalConfiguration(globalConfigHttp).usingHttp((http) =>
http
.get("/3/discover/movie")
.handleRequest((_ctx, input, request) =>
request
.addQueryString("with_genres", input.genre.toString())
.withoutBody()
)
.handleResponse((_ctx, _input, response) =>
response.parseWithBodyAsJson()
)
)
);
You can always override the Global Configs at an operation level. E.g. passing a different value for a custom header (using withHeader) at the operation level than what was passed at the global level.
Update AuthType
Note: If your connector requires auth, then you don't need to make any changes. Please skip this step.
Till version 3 the default authType for a connector with no auth was never.
If your connector doesn't use an auth, it's authType should be set to any.
export type PdfProcessorAuth = any; // No Authentication
3. Deploy the connector
Now your connector is ready to be deployed again. Please check deployment guide if unsure.
4. Update the connector version in the workflows
Connector version isn't updated automatically in the workflows if you publish new versions. Your workflows NEED to be updated manually to use new version of the connector.