Skip to contentSkip to navigationSkip to topbar
On this page

General Usage


(information)

This is a Twilio Labs project

This means this project is 100% open-source. You can find its source code in the Twilio Labs GitHub organization(link takes you to an external page).

We currently don't support the projects through our official support channels. But you are welcome to reach out to us on GitHub for any questions, issues or suggestions or to contribute to this project.

Learn more about Twilio Labs.

There are two ways you can use the toolkit. If you are already using the Twilio CLI, you can install it via a plugin. Alternatively, you can use the toolkit as a standalone using twilio-run via npm or another Node.js package manager.

Throughout the docs we'll reference the Twilio CLI commands.


Create a Project

create-a-project page anchor

There's a variety of ways you can get started with a Twilio Serverless project. If you are intending to use the Twilio Serverless Toolkit, you'll have to have a project that adheres to a certain structure (more below). The toolkit actually supports scaffolding projects to get some example Functions and the right folder structure.

Create Twilio Serverless project

create-twilio-serverless-project page anchor
1
# Intialize a new project with the name my-project
2
twilio serverless:init my-project
3
4
# Change into that new project directory
5
cd my-project

By default the Twilio Serverless Toolkit uses the filesystem structure of your project to make conclusions of what to do. If you use the Toolkit to create your project, you'll already have a valid structure like this:

1
my-project
2
├── .env
3
├── .gitignore
4
├── .nvmrc
5
├── .twilioserverlessrc
6
├── .twiliodeployinfo
7
├── assets
8
├── index.html
9
├── message.private.js
10
└── style.css
11
├── functions
12
├── hello-world.js
13
├── private-message.js
14
└── sms
15
└── reply.protected.js
16
├── package-lock.json
17
└── package.json

Configuration and Meta Files

configuration-and-meta-files page anchor

By default the Twilio Serverless Toolkit uses conventions over configuration. However we do provide some configuration options and store some meta information in your project in the shape of .twilioserverlessrc and .twiliodeployinfo files. You can learn more about them in the Configurations section.

Anything that will be found in the dependencies field of your package.json in your project directory will be available both for local development as well as installed in your deployed project.

You can add new dependencies by using any Node.js package manager that writes to the package.json like npm to install dependencies.

(warning)

Warning

Dependencies that are installed locally but are not under dependencies, like anything installed as devDependencies, might be available during local development but will not be available during deployment. The deploy command will list all dependencies that are being installed upon deployment.

We use .env files for all environment variables. By default we will not make any other environment variables on your system available for your local development. We'll use the same file to determine the values that should be uploaded for deployment. You can change the location of your .env file using the --env flag (for example: --env=./.env.staging) or by using the configuration file.

Learn more about .env files:

There are a few variables that behave differently. Namely:

  • DOMAIN_NAME and PATH . These are automatically set both during local develoment and in your deployed environment unless they are overriden by a value in your .env file.
  • ACCOUNT_SID and AUTH_TOKEN . During local development these are set through your .env file. During deployment they'll be replaced with the relevant account information you deployed to.
  • SERVICE_SID and ENVIRONMENT_SID . During local development these will be undefined by default and will log a warning starting with @twilio/runtime-handler version 1.1.2 . In your deployed version these will be populated with the relevant information for your deployment unless you overrode the values using the .env file with your own custom values.

How to use SERVICE_SID and ENVIRONMENT_SID in local development

how-to-use-service_sid-and-environment_sid-in-local-development page anchor

The most common use case for using SERVICE_SID and ENVIRONMENT_SID is to retrieve or manipulate things related to a deployment. For example permanently updating an environment variable by calling the Serverless API directly.

Since your local development environment only imitates the Twilio Functions Runtime there is no actual Service and therefore no Service SID and Environment SID that we can provide. Instead these values will be undefined. You will, however, see a warning emitted into your local development logs when accessing this undefined value to warn you that during deployment these will automatically be populated. You can use this information to gate behavior to only happen in your deployed instance. By writing code similar to this:

1
exports.handler = function(context, event, callback) {
2
if (context.SERVICE_SID) {
3
callback(null, 'Ahoy from the Twilio Cloud!');
4
} else {
5
callback(null, 'Hello from my local environment');
6
}
7
}

All Functions have to be under a common root directory. By default this will be functions/ but you can alternatively use src/. If neither of them works, there's a flag --functions-folder or functionsFolder config option that you can use to specify a different directory as the root directory for your Functions.

Anything under that root directory will be uploaded as a Twilio Function. The path for each function is relative to the root directory with the .js strapped away.

For example a functions/ directory like this:

1
my-project
2
├── functions
3
├── example.js
4
└── sms
5
└── reply.js

Would result in two Functions being created at the paths /example and /sms/reply.

If you would deploy these files both of these Functions would be publicly accessible. If you want to lock them down to only be accessible by Twilio, for example to use them as a webhook, you can mark a Function as protected. This can be done renaming your file to have an extension of .protected.js.

Note: This will not influence the path of the Function. Meaning a file functions/example.js and functions/example.protected.js will both result in a path of /example but the second one will make sure to enforce a valid Twilio request signature.

Creating Assets works similar to creating Functions. By default the toolkit will look for an assets/ or alternatively static/ folder. With the --assets-folder flag or assetsFolder config option you can change this directory to any other root directory.

However, Assets will preserve their extensions for the path. So for example a file under assets/index.html would result in a path of /index.html.

Assets are a great way for you to also host resources that you want to access from your Functions that are not other Functions or should not be available to the public. For example configuration files or other JavaScript files you want to require(). You can store those as private Assets.

To mark an Asset as private, include .private. in the filename. This will create a private Asset but the .private. annotation will be removed during upload. In order to accessing a private asset you'll have to use the global Runtime.getAssets() function. You can learn more about it in the Runtime documentation.


Start developing locally

start-developing-locally page anchor

The Twilio Serverless Toolkit allows you to develop locally to test out your Functions and Assets before deploying them to Twilio. It also allows you to attach a debugger to debug your Function logic or even spin up an ngrok tunnel to test your Functions directly with Twilio.

There's a variety of options that you can use when kicking off the local development command but the quick way to get started is to run it without any arguments.

Run a Serverless project locally

run-a-serverless-project-locally page anchor
1
# Start the local development environment with live reloading of Functions
2
twilio serverless:start

Create a new Twilio Function

create-a-new-twilio-function page anchor

Since any JavaScript file inside your functions directory of your project will turn into a Function, creating a new Twilio Function can be as quick as creating a new file with this content:

1
exports.handler = function(context, event, callback) {
2
const twiml = new Twilio.twiml.VoiceResponse();
3
twiml.say("Hello World!");
4
callback(null, twiml);
5
};

If you want to learn more about the different variables passed into this Function during the execution or other things that will be available during the execution, make sure to check out the documentation of the Twilio Function Runtime.

To make creating a new Twilio Function more convenient and get you started quicker, we added another command that lets you create a new Function and pick from a collection of existing templates.

Create a new Twilio Serverless Function

create-a-new-twilio-serverless-function page anchor
1
# Creates a new function with the path and name /my-new-function
2
twilio serverless:new my-new-function

These templates are dynamically loaded from our Function Templates repository on GitHub(link takes you to an external page) and we always welcome new contributions.

If you want to see a list of available templates with a short description directly in you terminal, you can use the serverless:list-templates command to list all templates.

List available Function templates

list-available-function-templates page anchor
1
# List all available Function templates
2
twilio serverless:list-templates

Once you have your project setup, you are just one command away from deploying your Twilio Serverless project. The deploy command will set some defaults based on your filesystem:

  • The toolkit will create a Twilio Serverless service for you. By default it will read the name entry in your package.json . You can use the --service-name flag to override this name
  • Twilio Serverless introduces the concept of Environments . By default the toolkit will deploy to an environment with the domain suffix dev and the name dev-environment . This can be changed through the --environment flag.
  • The toolkit will upload all variables set in your .env file for your deployment. You can change it to use a different .env file using the --env flag.
  • Any dependency that is listed in the dependencies field in your package.json will automatically be installed in your deployment.

Deploy a Twilio Serverless project

deploy-a-twilio-serverless-project page anchor
1
# Run a basic deployment with default settings
2
twilio serverless:deploy

Now that you were able to deploy your first Twilio Serverless project, it's time to learn more about some of the other options that you have.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.