The Serverless Toolkit has support for two types of meta files that can be included in your project:
.twilioserverlessrc — a configuration file.
.twiliodeployinfo — an 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.
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. You can select any of these by adding a suitable file extension:
.twilioserverlessrc.js or .twilioserverlessrc.cjs — Important: you'll have to export an object using module.exports = { ... }.twilioserverlessrc.yml"twilioserverless" key to your package.jsontwilioserverless.config.jsYou 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.
In general, everything that can be configured using a CLI flag with the Serverless Toolkit is also accessible through the configuration. By convention, every configuration value uses lowerCamelCase notation: for example, --service-sid becomes serviceSid in the configuration. Here are some further examples:
1{2"commands": {},3"environments": {},4"projects": {},5// "assets": true /* Upload assets. Can be turned off with --no-assets */,6// "assetsFolder": null /* Specific folder name to be used for static assets */,7// "buildSid": null /* An existing Build SID to deploy to the new environment */,8// "config": null /* Location of the config file. Absolute path or relative to current working directory (cwd) */,9// "createEnvironment": false /* Creates environment if it couldn't find it. */,10// "cwd": null /* Sets the directory of your existing Serverless project. Defaults to current directory */,11// "detailedLogs": false /* Toggles detailed request logging by showing request body and query params */,12// "edge": null /* Twilio API Region */,13// "env": null /* Path to .env file for environment variables that should be installed */,14// "environment": "dev" /* The environment name (domain suffix) you want to use for your deployment */,15// "extendedOutput": false /* Show an extended set of properties on the output */,16// "force": false /* Will run deployment in force mode. Can be dangerous. */,17// "forkProcess": true /* Disable forking function processes to emulate production environment */,18// "functionSid": null /* Specific Function SID to retrieve logs for */,19// "functions": true /* Upload functions. Can be turned off with --no-functions */,20// "functionsFolder": null /* Specific folder name to be used for static functions */,21// "inspect": null /* Enables Node.js debugging protocol */,22// "inspectBrk": null /* Enables Node.js debugging protocol, stops execution until debugger is attached */,23// "legacyMode": false /* Enables legacy mode, it will prefix your asset paths with /assets */,24// "live": true /* Always serve from the current functions (no caching) */,25// "loadLocalEnv": false /* Includes the local environment variables */,26// "loadSystemEnv": false /* Uses system environment variables as fallback for variables specified in your .env file. Needs to be used with --env explicitly specified. */,27// "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. */,28// "logLevel": "info" /* Level of logging messages. */,29// "logs": true /* Toggles request logging */,30// "ngrok": null /* Uses ngrok to create a public url. Pass a string to set the subdomain (requires a paid-for ngrok account). */,31// "outputFormat": "" /* Output the log in a different format */,32// "overrideExistingProject": false /* Deploys Serverless project to existing service if a naming conflict has been found. */,33// "port": "3000" /* Override default port of 3000 */,34// "production": false /* Promote build to the production environment (no domain suffix). Overrides environment flag */,35// "properties": null /* Specify the output properties you want to see. Works best on single types */,36// "region": null /* Twilio API Region */,37// "runtime": null /* The version of Node.js to deploy the build to. (node10 or node12) */,38// "serviceName": null /* Overrides the name of the Serverless project. Default: the name field in your package.json */,39// "serviceSid": null /* SID of the Twilio Serverless Service to deploy to */,40// "sourceEnvironment": null /* SID or suffix of an existing environment you want to deploy from. */,41// "tail": false /* Continuously stream the logs */,42// "template": null /* undefined */,43}
Some configuration properties are shared across multiple commands and will always be executed. However, there are situations where you might want a configuration to apply only in certain scenarios. This is where scoped configurations come into play.
In addition to defining configuration values on a top level, you can scope them to:
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 specify an Account SID.Which one you use depends on your set up but some common use cases are:
Another common example is using different environment variables for different environments. Take the following configuration:
1{2"environments": {3"dev": {4"env": ".env.dev"5},6"stage": {7"env": ".env.stage"8},9"*": {10"env": ".env.prod"11}12}13}
In this case depending on which value you pass to --environment it will also change the .env file the CLI will read to get environment variables. More specifically:
twilio serverless:deploy uses the file .env.devtwilio serverless:deploy --environment stage uses the file .env.stagetwilio serverless:deploy --production uses the file .env.prodtwilio serverless:start falls back to the default meaning .envThis file keeps track of information resulting from your latest deployments. It does so 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 other 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.
In previous versions of the Serverless Toolkit you might have found a .twilio-functions file. This file was fulfilling the role of the .twilioserverlessrc and .twiliodeployinfo files with less functionality and more confusion. We deprecated this file in new versions. If you have this file in your project and want to upgrade the latest version of the Serverless Toolkit, you should 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.