General Usage

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.

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

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.

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:

• Structure of a .env file
• A small tutorial on how to use .env files in general

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.

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.

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.

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.

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 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.

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.

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.

• Getting Started
  • Install the toolkit
  • Explore available commands
• Examples