twilio-labs · mikefaille · Apr 20, 2025
diff --git a/.changeset/heavy-moose-appear.md b/.changeset/heavy-moose-appear.md
@@ -0,0 +1,27 @@
+---
+'@twilio-labs/serverless-runtime-types': major
+'twilio-run': major
+'create-twilio-function': minor
+'@twilio/runtime-handler': minor
+---
+
+feat: Upgrade Twilio SDK to v5 and use peer dependency
+
+**WHAT:**
+- Upgraded the core `twilio` Node.js helper library to v5.5.2 across the toolkit.
+- Changed `@twilio-labs/serverless-runtime-types` and `@twilio-labs/twilio-run` to require `twilio` as a `peerDependency` instead of a direct dependency.
+- Updated type definitions (`ClientOpts`) for compatibility with `[email protected]`.
+- Updated default dependencies (`twilio`, `typescript`, `serverlessRuntimeTypes`) used by `@twilio-labs/create-twilio-function`.
+
+**WHY:**
+- Aligns the toolkit with the latest Twilio SDK features, improvements, and security updates.
+- Resolves potential type conflicts (e.g., `TS2322`/`TS2352`) by ensuring a single `twilio` instance, managed by the user's project.
+
+**HOW:**
+**BREAKING CHANGE:** Users of `@twilio-labs/twilio-run` or projects importing types from `@twilio-labs/serverless-runtime-types` **must** now add `twilio` as a direct dependency to their project:
+```bash
+npm install twilio@^5.5.2
+# or
+yarn add twilio@^5.5.2
+```
+After updating toolkit packages and adding `twilio`, perform a clean install (delete `node_modules` and lock file, then run `npm install` or `yarn install`).
diff --git a/package.json b/package.json
@@ -26,7 +26,7 @@
     "@changesets/cli": "^2.26.0",
     "@commitlint/cli": "^19.1.0",
     "@commitlint/config-conventional": "^19.1.0",
-    "@twilio/test-dep": "npm:twilio@4.22.0",
+    "@twilio/test-dep": "npm:twilio@5.2.2",
     "@types/jest": "^29.2.4",
     "all-contributors-cli": "^6.1.2",
     "commitizen": "^4.2.4",
@@ -45,6 +45,9 @@
     "typedoc": "^0.27.4",
     "typescript": "^5.3.3"
   },
+  "peerDependencies": {
+			"twilio": "^5.5.2"
+  },		
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": [
       "prettier --write",

diff --git a/packages/create-twilio-function/package.json b/packages/create-twilio-function/package.json
@@ -24,7 +24,7 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@twilio/runtime-handler": "^2.0.3",
+    "@twilio/runtime-handler": "^2.1.0",
     "nock": "^11.3.4"
   },
   "dependencies": {

diff --git a/packages/create-twilio-function/src/create-twilio-function/versions.js b/packages/create-twilio-function/src/create-twilio-function/versions.js
@@ -1,13 +1,13 @@
 const pkgJson = require('../../package.json');
 
 module.exports = {
-  twilio: '5.0.3',
+  twilio: '5.5.2',
   twilioRuntimeHandler: pkgJson.devDependencies[
     '@twilio/runtime-handler'
   ].replace(/[\^~]/, ''),
   twilioRun: pkgJson.dependencies['twilio-run'],
   node: '18',
-  typescript: '^5.3.3',
-  serverlessRuntimeTypes: '^4.0.0',
+  typescript: '^5.8.0',
+  serverlessRuntimeTypes: '^4.0.1',
   copyfiles: '^2.4.1',
 };
diff --git a/packages/runtime-handler/package.json b/packages/runtime-handler/package.json
@@ -70,7 +70,7 @@
     "nocache": "^2.1.0",
     "normalize.css": "^8.0.1",
     "serialize-error": "^7.0.1",
-    "twilio": "4.23.0"
+    "twilio": "5.5.2"
   },
   "gitHead": "6db273648ed19474f4125042556b10c051529912"
 }
diff --git a/packages/serverless-runtime-types/README.md b/packages/serverless-runtime-types/README.md
@@ -22,6 +22,17 @@
 npm install @twilio-labs/serverless-runtime-types
 ```
 
+**Peer Dependency Requirement:**
+
+This package requires the core `twilio` Node.js library as a **peer dependency** (version `^5.5.2` or compatible). This is necessary to ensure type consistency and prevent version conflicts within your project.
+
+**You MUST explicitly install both `@twilio-labs/serverless-runtime-types` and a compatible version of `twilio` in your project.**
+
+```bash
+# Using npm
+npm install @twilio-labs/serverless-runtime-types twilio@^5.5.2 --save-dev
+```
+
 ## Example
 
 ### In JavaScript

diff --git a/packages/serverless-runtime-types/package.json b/packages/serverless-runtime-types/package.json
@@ -29,12 +29,14 @@
   },
   "dependencies": {
     "@types/express": "^4.17.21",
-    "@types/qs": "^6.9.4",
-    "twilio": "^4.23.0"
+    "@types/qs": "^6.9.4"
   },
+  "peerDependencies": {
+		"twilio": "^5.5.2"
+  },		
   "devDependencies": {
     "all-contributors-cli": "^6.7.0",
-    "typescript": "^5.3.3"
+    "typescript": "^5.8.0"
   },
   "publishConfig": {
     "access": "public"

diff --git a/packages/serverless-runtime-types/types.d.ts b/packages/serverless-runtime-types/types.d.ts
@@ -2,7 +2,7 @@ import * as twilio from 'twilio';
 import { ServiceContext } from 'twilio/lib/rest/sync/v1/service';
 import { SyncListListInstance } from 'twilio/lib/rest/sync/v1/service/syncList';
 import { SyncMapListInstance } from 'twilio/lib/rest/sync/v1/service/syncMap';
-import { TwilioClientOptions } from 'twilio/lib/rest/Twilio';
+import { ClientOpts } from 'twilio';
 
 export type EnvironmentVariables = {
   [key: string]: string | undefined;
@@ -187,7 +187,7 @@ export interface TwilioResponse {
   removeCookie(key: string): TwilioResponse;
 }
 
-export type RuntimeSyncClientOptions = TwilioClientOptions & {
+export type RuntimeSyncClientOptions = ClientOpts & {
   serviceName?: string;
 };
 
@@ -360,7 +360,7 @@ export type Context<T = {}> = {
    * };
    * ```
    */
-  getTwilioClient(options?: TwilioClientOptions): twilio.Twilio;
+  getTwilioClient(options?: ClientOpts): twilio.Twilio;
   /**
    * The domain name for the Service that contains this Function.
    */
@@ -412,6 +412,7 @@ export type GlobalTwilio = Omit<typeof twilio, 'default'> & {
 export { ServiceContext } from 'twilio/lib/rest/sync/v1/service';
 export { SyncListListInstance } from 'twilio/lib/rest/sync/v1/service/syncList';
 export { SyncMapListInstance } from 'twilio/lib/rest/sync/v1/service/syncMap';
-export { TwilioClientOptions } from 'twilio/lib/rest/Twilio';
+export { ClientOpts as TwilioClientOptions } from 'twilio/lib/rest/Twilio';
+
 export type TwilioClient = twilio.Twilio;
 export type TwilioPackage = typeof twilio;
diff --git a/packages/twilio-run/package.json b/packages/twilio-run/package.json
@@ -76,12 +76,14 @@
     "serialize-error": "^7.0.1",
     "terminal-link": "^1.3.0",
     "title": "^3.4.1",
-    "twilio": "^4.23.0",
     "type-fest": "^0.15.1",
     "window-size": "^1.1.1",
     "wrap-ansi": "^7.0.0",
     "yargs": "^17.2.1"
   },
+  "peerDependencies": {
+	  "twilio": "^5.5.2"
+	},		
   "optionalDependencies": {
     "ngrok": "^3.3.0"
   },
@@ -113,7 +115,7 @@
     "nock": "^12.0.2",
     "supertest": "^3.1.0",
     "typescript": "^4.9.4",
-    "@twilio/test-dep": "npm:twilio@4.22.0"
+    "@twilio/test-dep": "npm:twilio@5.5.2"
   },
   "files": [
     "bin/",

diff --git a/packages/twilio-run/src/runtime/internal/runtime.ts b/packages/twilio-run/src/runtime/internal/runtime.ts
@@ -16,7 +16,7 @@ import { getDebugFunction } from '../../utils/logger';
 
 const debug = getDebugFunction('twilio-run:runtime');
 
-const { getCachedResources } = require('./route-cache');
+import { getCachedResources } from './route-cache';
 
 function getAssets(): AssetResourceMap {
   const { assets } = getCachedResources();
@@ -72,9 +72,9 @@ export function create({ env }: StartCliConfig): RuntimeInstance {
         .join(',')})`,
     });
     const client = twilio(env.ACCOUNT_SID, env.AUTH_TOKEN, options);
-    const service = (client.sync.v1.services(
+    const service = client.sync.v1.services(
       serviceName || 'default'
-    ) as unknown) as RuntimeSyncServiceContext;
+    ) as unknown as RuntimeSyncServiceContext;
 
     service.maps = service.syncMaps;
     service.lists = service.syncLists;

diff --git a/packages/twilio-run/src/runtime/route.ts b/packages/twilio-run/src/runtime/route.ts
@@ -4,6 +4,7 @@ import {
   ServerlessEventObject,
   ServerlessFunctionSignature,
 } from '@twilio-labs/serverless-runtime-types/types';
+
 import { fork } from 'child_process';
 import {
   NextFunction,
@@ -23,7 +24,6 @@ import { cleanUpStackTrace } from '../utils/stack-trace/clean-up';
 import { Reply } from './internal/functionRunner';
 import { Response } from './internal/response';
 import * as Runtime from './internal/runtime';
-import * as PATH from 'path';
 
 const RUNNER_PATH =
   process.env.NODE_ENV === 'test'
@@ -40,7 +40,7 @@ export function constructEvent<T extends ServerlessEventObject>(
   return { ...req.query, ...req.body };
 }
 
-export function constructContext<T extends {} = {}>(
+export function constructContext(
   { url, env }: StartCliConfig,
   functionPath: string
 ): Context<{