Functions and Assets Node.js v16 Upgrade

This Functions and Assets Node.js upgrade guide refers to a Node.js version prior to the current long-term support (LTS) version.

Please ensure you follow the Functions and Assets Node.js upgrade guide for the latest Node.js LTS version.

What do you need to know?

We are keeping your runtime up to date in accordance with industry standards. Based on the Node.js support schedule, Node.js v14 will no longer be in Maintenance long-term support (LTS) status after June 15th, 2023. Production applications should only use releases of Node.js that are Active LTS or Maintenance LTS.

What do you need to do?

Re-deploy and test your Functions on the Node.js v16 runtime before June 15th, 2023. A deployment will be required to make your Functions run on the new version of Node.js.

After June 15th, 2023, if you make changes to your Functions, they will need to be deployed on Node.js v16.

Currently, the Node.js version will only change if you explicitly set it via either the UI dropdown in the Dependencies tab, by passing runtime when using the Serverless Toolkit, or by explicitly setting the runtime parameter when creating a Build.

What happens if I do nothing?

Your currently deployed Functions will continue to execute on the existing Node.js v14 runtime if no changes are made.

  • After June 15th, 2023, if you create a new Service or deploy a Service that has not yet been deployed, it will use Node.js v16 by default.
  • If you have an existing build of a Service deployed, it will continue to use the previously set runtime. After June 15th, 2023, any new deployments must be made on Node.js v16; you will not be able to create any new deployments using Node.js v14.
  • If a Service contains only Assets, then the default Node.js runtime will be used automatically for builds (regardless of the runtime parameter that is sent as part of the Build request). After June 15th, 2023, the default runtime will be Node.js v16.

We encourage all customers to upgrade to Node.js v16, even if you are not planning on making any other changes to your Functions.

How do I upgrade to Node.js v16?

Follow the instructions below to upgrade, test, and deploy your code on Node.js v16 before the June 15th, 2023 deadline.

While there are no syntax changes required for the upgrade from Node.js v14 to v16, a possible area of impact is your Service's NPM dependencies. It is important to check that the dependencies you include are supported on Node.js v16.

Using the Functions Editor UI

If you have built your application with the latest Functions Editor, you can update your Node.js runtime by following these steps:

  1. Open the Dependencies tab of an existing Service that you wish to update.
  2. Open the Node Version dropdown menu, and select Node v16.
  3. Click the Deploy All button to build and deploy your Service. Once complete, all Functions within that Service will be running on Node.js v16.

Using the Serverless API

If you are using the Serverless API to build and deploy your Services, you can update your Node.js runtime by creating a new Build of your Service with the runtime parameter set to node16.

Using the Twilio CLI and your own Service SID, the command will be:

twilio api:serverless:v1:services:builds:create \
    --runtime node16

If you'd prefer to use an SDK to trigger this build, refer to the Build documentation for examples of how to trigger a build in every supported programming language.

Using the Serverless Toolkit

To avoid unexpected side effects when trying out Node.js v16 make sure to follow these exact steps. Learn more about the possible side effects.

Validate you are on the correct Serverless Toolkit version

You should be using @twilio-labs/plugin-serverless version 3.1.0 or newer. You can run twilio plugins to verify your version.

If your version of the Serverless Toolkit does not meet these requirements, you may upgrade to the latest version using the following commands:

twilio plugins:remove @twilio-labs/plugin-serverless
twilio plugins:install @twilio-labs/plugin-serverless@latest

Define your baseline Node.js version

Open the .twilioserverlessrc configuration file at the root of your project and make sure it includes:

  "runtime": "node14"

This will ensure that if you don't declare a specific Node.js runtime it will always use Node.js v14 to ensure that you are not accidentally switching to Node.js v16 before verifying it.

If you are working with multiple people or deploy as part of your CI/CD system, make sure that everyone in your team has the updated .twilioserverlessrc file, for example by pushing it to your version control system.

Create your first deployment with Node.js v16

To trigger a new deployment with Node.js v16 you can use the --runtime flag. Ideally deploy to a new environment so you can verify the functionality in isolation.

The deployment command will be:

twilio serverless:deploy --runtime node16 --environment verify-16

Your Functions will now be deployed and running on the Node.js v16 runtime on that environment.

Finalize your Node.js v16 transition

Once you have verified your code with Node.js v16, you can update the .twilioserverlessrc file to use node16 as the runtime.

  "runtime": "node16"

That means any future deployments will use Node.js v16 even if you don't pass in the specific runtime using the --runtime flag.

How do I verify that the upgrade was successful?

Your runtime's version of Node.js is exposed on the process.version variable, so creating, deploying, and calling a short Function like this will return the current version for verification purposes:

exports.handler = (context, event, callback) => {
  return callback(null, process.version);

What if I'm still using Functions(Classic)?

The simplest way to upgrade is to start by using the new Functions editor.

  1. Create a new Service in the New Functions editor.
  2. Copy your Functions code into the new Service as new Functions.
  3. Copy over any Environment Variables and/or Dependencies that your Function(s) use.
  4. Deploy your new Functions by clicking Deploy All. After June 15th, 2023, your code will be deployed using Node.js v16 by default.
  5. If you wish to test with Node.js v14, you can do so by navigating to the Dependencies tab, selecting Node v14 from the Node Version dropdown, and clicking Deploy All for the change to take effect.
  6. Test that your Functions work as expected in the new Service. Once confident, you can switch your Functions to use Node.js v16.

Be sure to update any references to your old Function (e.g. Studio Flows, Twilio number config) to use the new Function URL. You can copy your new Function URL by clicking Copy URL at the bottom right of the Function editor.

If you would like to change the Node.js runtime within Functions(Classic), please reach out to support with your Account SID and request that they change the Node.js runtime for you.

Possible Side Effects

If you are using the API directly or the Serverless Toolkit, you might encounter possible side effects if you don't explicitly specify a runtime with each deployment.

By default if you are not specifying a runtime when creating a Build the API will use the runtime you used for the last successful Build. That means if you successfully deployed your code with Node.js v16 once, any subsequent deployments that don't specify a specific runtime will automatically use Node.js v16 going forward.

To avoid these side effects:

  • With the API: Always pass a runtime parameter when creating a Build
  • With the Serverless Toolkit: Make sure to follow the steps outlined above, especially defining a default runtime in the .twilioserverlessrc file.
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!