Start a new Twilio Functions project the easy way

If you're building a Twilio project you will inevitably need to run some code in response to an incoming webhook request. One of the easiest ways to do this is with Twilio Functions, our serverless platform for running Node.js. Recently my colleague Dominik released the twilio-run package that makes it easier to develop, test and debug Twilio Functions locally.

I wanted to make it even easier to get started with a Twilio Functions project, so I built a project generator called create-twilio-function.

Let's take a look at how you can easily start and develop a Twilio Functions project using create-twilio-function and twilio-run.

Getting started

There are a few ways you can use create-twilio-function. The easiest is if you have npm version 6 or higher. You can check this out on the command line with:

$ npm --version
6.9.0

If you don't have an up to date version of npm you can update with:

$ npm install -g npm@latest

Take a look at this article if you have permissions errors when you try to install global modules.

If you're on Windows you have a bit more work to do and I recommend you read the instructions in the npm documentation.

Once you have npm up to date you can use create-twilio-function by running:

$ npm init twilio-function your-project-name

Alternatives

npm init <initializer> actually calls out to the npx tool. If you have npx installed you can call:

$ npx create-twilio-function your-project-name

The last option is installing create-twilio-function globally:

npm install -g create-twilio-function
create-twilio-function your-project-name

When you run create-twilio-function the script will either ask you for your Twilio Account SID and Auth Token or if you have credentials already stored in the environment it will ask if you want to use them.

If you supply your credentials, create-twilio-function will use them to create a .env that will make them available in your functions. You don't need to supply your credentials if you don't want to, your .env file will just be left blank.

create-twilio-function then generates a new project structure for you and installs the required dependencies.

Building with Twilio Functions

Once the script has run to completion you will have a brand new project setup for local Twilio Functions development. Change into the new directory and take a look at the file structure. It should look like this:

.env
.gitignore
.nvmrc
assets
functions
node_modules
package-lock.json
package.json

In order, the files and directories we see are:

• .env: which will contain your account sid and auth token if you supplied it. You can use this to add more environment variables for your functions
• .gitignore: The Node.js .gitignore file from GitHub's gitignore project
• .nvmrc: Twilio Functions currently supports Node.js version 8.10.0. If you are using nvm you can run nvm use and get the right version.
• assets: the directory you can store assets like images, HTML, CSS and JavaScript
• functions: the directory in which you write your Twilio Functions
• node_modules and package-lock.json: all your dependencies
• package.json: your dependencies, scripts and other metadata about the project

If you take a look in package.json you will see a start script is defined to run twilio-run --env. Call it with:

npm start

Your Functions project will start up showing which functions and assets you are hosting in this local environment. create-twilio-function has one example function to get you started.

Open up the example from functions/example.js to see how it's built. Currently, it is a "Hello World!" application for a voice webhook response using the Twilio Node.js library (which is provided in the Twilio Functions environment) to build the TwiML response.

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

If you make a request to http://localhost:3000/example using curl you'll see the TwiML output:

$ curl http://localhost:3000/example
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Hello World!</Say>
</Response>

With one command to create-twilio-function and another to npm start we've gone from zero to a full local development environment for Twilio Functions.

If you want to learn more about the advanced features of twilio-run, from serving your functions publicly using ngrok to hooking in with a debugger, check out Dominik's post.

What about deploying my functions and assets to run on Twilio?

Right now, you'll have to copy and paste Functions code and/or drag and drop asset files in the Twilio console to deploy them live. We're working hard on an API for deployment. Look out for that soon, and get in touch with me if you'd like to be one of the first to try it.

What's next?

create-twilio-function is a good way to get started building your own Twilio Functions and twilio-run makes it easy to run and test your functions locally.

Now it's your turn to write your own functions. If you're looking for some inspiration, check out my posts on forwarding SMS messages or faxes as emails using the SendGrid API, or translating WhatsApp messages into emoji all using Functions.

We're always interested in how we can help you build Twilio applications faster and better. If you have ideas for how create-twilio-function could help more, please let me know in the comments or open an issue on the GitHub repo.