Menu

Expand
Rate this page:

Configuration & Meta Files

The Serverless Toolkit has support for two types of meta files as part of your project:

  • .twilioserverlessrc (configuration file)
  • .twiliodeployinfo (autogenerated / meta file)

These configuration files are only supported by @twilio-labs/plugin-serverless version 2.0.0 or newer and twilio-run version 3.0.0 or newer. For older versions check out the section for .twilio-functions further down.

Configuration

Location & Format

By default the Serverless Toolkit will try to load any configuration file from the root of your project by looking for .twilioserverlessrc. The format of the configuration file is JSON5 which supports regular JSON as well as features such as comments. Additionally, we support alternative formats for your configuration file by adding a file extension such as:

  • JavaScript: .twilioserverlessrc.js or .twilioserverlessrc.cjs (Important: you'll have to export an object using module.exports = { ... })
  • YAML: .twilioserverlessrc.yml
  • Package.json: add a "twilioserverless" key to your package.json
  • Config JavaScript file: twilioserverless.config.js

You can also provide a different location for your config file by specifying the location using the -c flag.

In this guide we'll use the JSON5 syntax.

Configuration Options

In general everything that can be configured using a CLI flag with the Serverless Toolkit is also accessible through the configuration. The convention here is that every configuration value uses the camelCase notation. So for example --service-sid becomes serviceSid in the configuration. Here are some examples:

{
	"commands": {},
	"environments": {},
	"projects": {},
	// "assets": true 	/* Upload assets. Can be turned off with --no-assets */,
	// "assetsFolder": null 	/* Specific folder name to be used for static assets */,
	// "buildSid": null 	/* An existing Build SID to deploy to the new environment */,
	// "config": null 	/* Location of the config file. Absolute path or relative to current working directory (cwd) */,
	// "createEnvironment": false 	/* Creates environment if it couldn't find it. */,
	// "cwd": null 	/* Sets the directory of your existing Serverless project. Defaults to current directory */,
	// "detailedLogs": false 	/* Toggles detailed request logging by showing request body and query params */,
	// "edge": null 	/* Twilio API Region */,
	// "env": null 	/* Path to .env file for environment variables that should be installed */,
	// "environment": "dev" 	/* The environment name (domain suffix) you want to use for your deployment */,
	// "extendedOutput": false 	/* Show an extended set of properties on the output */,
	// "force": false 	/* Will run deployment in force mode. Can be dangerous. */,
	// "forkProcess": true 	/* Disable forking function processes to emulate production environment */,
	// "functionSid": null 	/* Specific Function SID to retrieve logs for */,
	// "functions": true 	/* Upload functions. Can be turned off with --no-functions */,
	// "functionsFolder": null 	/* Specific folder name to be used for static functions */,
	// "inspect": null 	/* Enables Node.js debugging protocol */,
	// "inspectBrk": null 	/* Enables Node.js debugging protocol, stops execution until debugger is attached */,
	// "legacyMode": false 	/* Enables legacy mode, it will prefix your asset paths with /assets */,
	// "live": true 	/* Always serve from the current functions (no caching) */,
	// "loadLocalEnv": false 	/* Includes the local environment variables */,
	// "loadSystemEnv": false 	/* Uses system environment variables as fallback for variables specified in your .env file. Needs to be used with --env explicitly specified. */,
	// "logCacheSize": null 	/* Tailing the log endpoint will cache previously seen entries to avoid duplicates. The cache is topped at a maximum of 1000 by default. This option can change that. */,
	// "logLevel": "info" 	/* Level of logging messages. */,
	// "logs": true 	/* Toggles request logging */,
	// "ngrok": null 	/* Uses ngrok to create a public url. Pass a string to set the subdomain (requires a paid-for ngrok account). */,
	// "outputFormat": "" 	/* Output the log in a different format */,
	// "overrideExistingProject": false 	/* Deploys Serverless project to existing service if a naming conflict has been found. */,
	// "port": "3000" 	/* Override default port of 3000 */,
	// "production": false 	/* Promote build to the production environment (no domain suffix). Overrides environment flag */,
	// "properties": null 	/* Specify the output properties you want to see. Works best on single types */,
	// "region": null 	/* Twilio API Region */,
	// "runtime": null 	/* The version of Node.js to deploy the build to. (node10 or node12) */,
	// "serviceName": null 	/* Overrides the name of the Serverless project. Default: the name field in your package.json */,
	// "serviceSid": null 	/* SID of the Twilio Serverless Service to deploy to */,
	// "sourceEnvironment": null 	/* SID or suffix of an existing environment you want to deploy from. */,
	// "tail": false 	/* Continuously stream the logs */,
	// "template": null 	/* undefined */,
}

Some configuration properties are shared across multiple commands and will always be executed. However, there are situations where you might want a configuration to only apply in certain scenarios. That's where scoped configurations come into play.

Scoped Configuration

Additionally to defining configuration values on a top level you can scope them based on:

  • commands: based on the CLI command you use, e.g. start, deploy, list, promote, logs, etc.
  • environments: based on the value you pass to --environment or by using "*" for --production
  • projects: based on the Account SID you deploy to. This doesn't work if you use --username and --password with twilio-run unless you use an Account SID.

Which one you use depends on your set up but some common use cases are:

Another common example would be wanting to use different environment variables for different environments. Take for example the following configuration:

{
  "environments": {
    "dev": {
      "env": ".env.dev"
    },
    "stage": {
      "env": ".env.stage"
    },
    "*": {
      "env": ".env.prod"
    }
  }
}

In this case depending on which value you pass to --environment it will also change the .env file the CLI will read to upload environment variables. More specifically in this case:

  • twilio serverless:deploy uses the file .env.dev
  • twilio serverless:deploy --environment stage uses the file .env.stage
  • twilio serverless:deploy --production uses the file .env.prod
  • twilio serverless:start falls back to the default meaning .env

Deploy Info (.twiliodeployinfo)

This file primarily keeps track of information resulting from your latest deployments. It keeps track of these on a per-project basis to make sure when you redeploy and switch between CLI profiles, we will still deploy to the right account. This file is autogenerated and you typically do not have to modify it yourself.

By default this file is included into your .gitignore since it should not be relevant for orther people using the same codebase. If you do share Twilio accounts/credentials you should instead configure the different serviceSid values in the configuration file. Check out this guide for more information.

Deprecated: .twilio-functions

In previous versions of the Serverless Toolkit you might have found a .twilio-functions file. This file was fulfilling both the role of the .twilioserverlessrc and .twiliodeployinfo files with less functionality and more confusion. We deprecated this file in new versions. If you have the file in your project and are upgrading to the latest version of the Serverless Toolkit, you should be able to run the following command to migrate:

npx -p twilio-run twilio-upgrade-config

This will convert your .twilio-functions file into a .twiliodeployinfo file. If you are using custom configuration you might have to copy some of that into the .twilioserverlessrc file manually.

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 browsing the Twilio tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more