\n\n- [About](#about)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Create a new project](#create-a-new-project)\n - [Project conventions](#project-conventions)\n - [Function templates](#function-templates)\n - [Deploy a project](#deploy-a-project)\n- [Commands](#commands)\n - [`twilio-run start [dir]`](#twilio-run-start-dir)\n - [Examples](#examples)\n - [`twilio-run deploy`](#twilio-run-deploy)\n - [Examples](#examples-1)\n - [`twilio-run list-templates`](#twilio-run-list-templates)\n - [Examples](#examples-2)\n - [`twilio-run new [namespace]`](#twilio-run-new-namespace)\n - [Examples](#examples-3)\n - [`twilio-run list [types]`](#twilio-run-list-types)\n - [Examples](#examples-4)\n - [`twilio-run activate`](#twilio-run-activate)\n - [Examples](#examples-5)\n - [`twilio-run logs`](#twilio-run-logs)\n - [Examples](#examples-6)\n- [API](#api)\n - [`runDevServer(port: number, baseDir: string): Promise`](#rundevserverport-number-basedir-string-promiseexpressapplication)\n - [`handleToExpressRoute(handler: TwilioHandlerFunction): Express.RequestHandler`](#handletoexpressroutehandler-twiliohandlerfunction-expressrequesthandler)\n- [Error Handling in Dev Server](#error-handling-in-dev-server)\n- [Contributing](#contributing)\n - [Code of Conduct](#code-of-conduct)\n- [Contributors](#contributors)\n- [License](#license)\n\n## About\n\nThis project is part of the [Serverless Toolkit](https://github.com/twilio-labs/serverless-toolkit). For a more extended documentation, check out the [Twilio Docs](https://www.twilio.com/docs/labs/serverless-toolkit).\n\n## Installation\n\nYou can install the CLI tool via `npm` or another package manager. Ideally install it as a dev dependency instead of global:\n\n```bash\n# Install it as a dev dependency\nnpm install twilio-run --save-dev\n\n# Afterwards you can use by using:\nnode_modules/.bin/twilio-run\n\nnpx twilio-run\n\n# Or inside your package.json scripts section as \"twilio-run\"\n```\n\n## Usage\n\nCheck out the [commands](#commands) for in depth usage, but here are some things you will want to know:\n\n### Create a new project\n\nTo create a new project with the Twilio Serverless Toolkit you can use [`create-twilio-function`](https://github.com/twilio-labs/serverless-toolkit/tree/main/packages/create-twilio-function) which will scaffold a new project that is ready to be used with `twilio-run`.\n\n```bash\n# Create a valid project, for example:\nnpm init twilio-function my-project\n\n# Navigate into project\ncd my-project\n```\n\nYou can then use `twilio-run` to run a local development server to serve your functions and assets.\n\n```bash\nnpx twilio-run start\n```\n\n### Project conventions\n\nBy default JavaScript Functions should be placed in the `functions` directory and assets, which can be JavaScript, images, CSS, or any static asset, should be placed in the `assets` directory. You can choose other directories by providing a `--functions-folder` or `--assets-folder` option to `twilio-run` commands.\n\nTwilio Functions and Assets can be public, protected or private. The differences are:\n\n* **Public**: Any one with the URL can visit the Function or Asset\n* **Protected**: Twilio signs webhook requests, making a Twilio Function protected means that the Function will validate the webhook signature and reject any incoming requests that don't match\n* **Private**: The Function or Asset doesn't a URL, it can only be required within another Function or Asset\n\nWithin `twilio-run` you can make your Functions or Assets public, protected or private by adding to the function filename. Functions and Assets are public by default. To make a Function or Asset protected or private, add `.protected` or `.private` to the filename before the extension. For example: `functions/secret.protected.js` or `assets/hidden.private.jpg`.\n\n### Function templates\n\nThere are a number of pre-written Function templates that you can add to your project. The [templates are available on GitHub](https://github.com/twilio-labs/function-templates) and you can also propose your own via pull request.\n\nTo list the available templates you can run:\n\n```bash\nnpx twilio-run list-templates\n```\n\nTo add a new function into your project from a template you can run:\n\n```bash\nnpx twilio-run new namespace\n```\n\nThe command will walk you through choosing the template.\n\n### Deploy a project\n\nTo deploy a project to the Twilio infrastructure you can run the command:\n\n```bash\nnpx twilio-run deploy\n```\n\nThis will deploy your project to the \"dev\" environment by default. You can then promote the project from \"dev\" to other environments with the command:\n\n```bash\nnpx twilio-run promote --from=dev --to=stage\n```\n\n## Commands\n\nThe CLI exposes a variety of commands. The best way to find out about the flags and commands available is to run `twilio-run --help` or `twilio-run [command] --help`\n\n### `twilio-run start [dir]`\n- Aliases: `twilio-run dev`, `twilio-run`\n\nStarts a local development server for testing and debugging of your environment. By default only variables in the `.env` file will be available via `process.env` or through the `context` argument inside Twilio Functions.\n\n#### Examples\n\n```bash\n# Serves all functions in current functions sub directory\ntwilio-run\n\n# Serves all functions in demo/functions\ntwilio-run demo\n\n# Serves functions on port 9000\nPORT=9000 twilio-run\n\n# Serves functions on port 4200\ntwilio-run --port=4200\n\n# Starts up the inspector mode for the node process\ntwilio-run --inspect\n\n# Exposes the Twilio functions via ngrok to share them\ntwilio-run --ngrok\n\n# Exposes the Twilio functions via ngrok using a custom subdomain (requires a paid ngrok account)\ntwilio-run --ngrok=myapp\n```\n\n### `twilio-run deploy`\n\nDeploys your project to Twilio. It will read dependencies automatically from your `package.json`'s `dependencies` field and install them. It will also upload and set the variables that are specified in your `.env` file. You can point it against a different `.env` file via command-line flags.\n\n#### Examples\n\n```bash\n# Deploys all functions and assets in the current working directory\ntwilio-run deploy\n\n# Creates an environment with the domain suffix \"prod\"\ntwilio-run deploy --environment=prod\n```\n\n### `twilio-run list-templates`\n\nLists the [available templates](https://github.com/twilio-labs/function-templates) that you can use to generate new functions and/or assets inside your current project with the [`twilio-run new` command](#twilio-run-new-namespace) below.\n\n#### Examples\n\n```bash\n# List available templates\ntwilio-run list-templates\n```\n\n### `twilio-run new [namespace]`\n\nCreates a new set of functions and/or assets inside your current project based on a [template](https://github.com/twilio-labs/function-templates).\n\n#### Examples\n\n```bash\n# Create a new function using the blank template\n# in a subfolder (namespace) demo\ntwilio-run new demo --template=blank\n```\n\n### `twilio-run list [types]`\n\nLists a set of available resources for different types related to your Account. Available resources that can be listed:\n- Services\n- Environments or Builds (requires to pass a Service)\n- Functions, Assets or Variables (requires to pass a Service and Environment)\n\n\n#### Examples\n\n```bash\n# Lists all existing services/projects associated with your Twilio Account\ntwilio-run list services\n# Lists all existing functions & assets associated with the `dev` environment of this service/project\ntwilio-run ls functions,assets --environment=dev --service-name=demo\n# Outputs all environments for a specific service with extended output for better parsing\ntwilio-run ls environments --service-sid=ZSxxxxx --extended-output\n# Only lists the SIDs and dates of last update for assets, variables and functions\ntwilio-run ls assets,variables,functions --properties=sid,date_updated\n```\n\n### `twilio-run activate`\n- Aliases: `twilio-run promote`\n\nPromotes an existing deployment to a new environment. It can also create a new environment if it doesn't exist.\n\n#### Examples\n\n```bash\n# Promotes the same build that is on the \"dev\" environment to the \"prod\" environment\ntwilio-run activate --environment=prod --source-environment=dev\n# Duplicates an existing build to a new environment called `demo`\ntwilio-run activate --environment=demo --create-environment --build-sid=ZB1234xxxxxxxxxx\n```\n\n### `twilio-run logs`\n\nPrint logs from your Twilio Serverless project\n\n#### Examples\n\n```bash\n# Gets the latest logs for the current project in the dev environment\ntwilio-run logs\n# Continuously streams the latest logs for the current project in the dev environment\ntwilio-run logs --tail\n# Gets the latest logs for the function sid in the production environment\ntwilio-run logs --function-sid ZFXXX --environment production\n```\n\n## API\n\nThe module also exposes two functions that you can use outside of the CLI tool to spin up local development.\n\nIf you want to interact with the Runtime API instead, [check out the `@twilio-labs/serverless-api` package](https://github.com/twilio-labs/serverless-api).\n\n### `runDevServer(port: number, baseDir: string): Promise`\n\nThis allows you to trigger running an express server that will expose all functions and assets. Example:\n\n```js\nconst { runDevServer } = require('twilio-run');\n\nrunDevServer(9000)\n .then(app => {\n console.log(`Server is running on port ${app.get('port')})`);\n })\n .catch(err => {\n console.error('Something failed');\n });\n```\n\n### `handleToExpressRoute(handler: TwilioHandlerFunction): Express.RequestHandler`\n\nYou can take the `handler` function of a Twilio Function file and expose it in an existing Express server. Example:\n\n```js\nconst express = require('express');\nconst bodyParser = require('body-parser');\nconst { handlerToExpressRoute } = require('twilio-run');\n\nconst { handler } = require('./path/to/function.js');\n\nconst app = express();\napp.use(bodyParser.urlencoded({ extended: false }));\n\napp.all(handlerToExpressRoute(handler));\n\napp.listen(3000, () => console.log('Server running on port 3000'));\n```\n\n## Error Handling in Dev Server\n\nIf your local Twilio Function throws an unhandled error or returns an `Error` instance via the `callback` method, we will return an HTTP status code of `500` and return the error object as JSON.\n\nBy default we will clean up the stack trace for you to remove internal code of the dev server and add it as `at [Twilio Dev Server internals]` into the stack trace.\n\nAn example would look like this:\n\n```\nError: What?\n at format (/Users/dkundel/dev/twilio-run/examples/basic/functions/hello.js:5:9)\n at exports.handler (/Users/dkundel/dev/twilio-run/examples/basic/functions/hello.js:13:3)\n at [Twilio Dev Server internals]\n```\n\nIf you want to have the full un-modified stack trace instead, set the following environment variable, either in your Twilio Function or via `.env`:\n\n```\nTWILIO_SERVERLESS_FULL_ERRORS=true\n```\n\nThis will result into a stack trace like this:\n\n```\nError: What?\n at format (/Users/dkundel/dev/twilio-run/examples/basic/functions/hello.js:5:9)\n at exports.handler (/Users/dkundel/dev/twilio-run/examples/basic/functions/hello.js:13:3)\n at twilioFunctionHandler (/Users/dkundel/dev/twilio-run/dist/runtime/route.js:125:13)\n at app.all (/Users/dkundel/dev/twilio-run/dist/runtime/server.js:122:82)\n at Layer.handle [as handle_request] (/Users/dkundel/dev/twilio-run/node_modules/express/lib/router/layer.js:95:5)\n at next (/Users/dkundel/dev/twilio-run/node_modules/express/lib/router/route.js:137:13)\n at next (/Users/dkundel/dev/twilio-run/node_modules/express/lib/router/route.js:131:14)\n at next (/Users/dkundel/dev/twilio-run/node_modules/express/lib/router/route.js:131:14)\n at next (/Users/dkundel/dev/twilio-run/node_modules/express/lib/router/route.js:131:14)\n at next (/Users/dkundel/dev/twilio-run/node_modules/express/lib/router/route.js:131:14)\n```\n\nIn general you'll want to use the cleaned-up stack trace since the internals might change throughout time.\n\n\n\n## Contributing\n\nThis project welcomes contributions from the community. Please see the [`CONTRIBUTING.md`](https://github.com/twilio-labs/serverless-toolkit/blob/main/docs/CONTRIBUTING.md) file for more details.\n\n### Code of Conduct\n\nPlease be aware that this project has a [Code of Conduct](CODE_OF_CONDUCT.md). The tldr; is to just be excellent to each other ❤️\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):\n\n\n\n| [ Dominik Kundel](https://dkundel.com) [💻](https://github.com/dkundel/twilio-run/commits?author=dkundel \"Code\") | [ dbbidclips](https://github.com/dbbidclips) [💻](https://github.com/dkundel/twilio-run/commits?author=dbbidclips \"Code\") [🐛](https://github.com/dkundel/twilio-run/issues?q=author%3Adbbidclips \"Bug reports\") | [ Shelby Hagman](https://shagman.codes) [🐛](https://github.com/dkundel/twilio-run/issues?q=author%3AShelbyZ \"Bug reports\") [💻](https://github.com/dkundel/twilio-run/commits?author=ShelbyZ \"Code\") | [ JavaScript Joe](https://joeprevite.com/) [🐛](https://github.com/dkundel/twilio-run/issues?q=author%3Ajsjoeio \"Bug reports\") | [ Stefan Judis](https://www.stefanjudis.com/) [🐛](https://github.com/dkundel/twilio-run/issues?q=author%3Astefanjudis \"Bug reports\") [💻](https://github.com/dkundel/twilio-run/commits?author=stefanjudis \"Code\") | [ Phil Nash](https://philna.sh) [🐛](https://github.com/dkundel/twilio-run/issues?q=author%3Aphilnash \"Bug reports\") [💻](https://github.com/dkundel/twilio-run/commits?author=philnash \"Code\") [👀](#review-philnash \"Reviewed Pull Requests\") |\n| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |\n\n\nThis project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}
![\"npm](\"https://img.shields.io/npm/v/twilio-run.svg?style=flat-square\")
![\"npm\"](\"https://img.shields.io/npm/dt/twilio-run.svg?style=flat-square\")
![\"GitHub\"](\"https://img.shields.io/github/license/twilio-labs/twilio-run.svg?style=flat-square\")
![\"All](\"https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square\"){kind=icon}
![\"Code](\"https://img.shields.io/badge/%F0%9F%92%96-Code%20of%20Conduct-blueviolet.svg?style=flat-square\"){kind=icon}
![\"PRs](\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\"){kind=icon}
\n![\"Dominik](\"https://avatars3.githubusercontent.com/u/1505101?v=4\")
![\"dbbidclips\"/](\"https://avatars1.githubusercontent.com/u/41997517?v=4\")
![\"Shelby](\"https://avatars0.githubusercontent.com/u/1033099?v=4\")
![\"JavaScript](\"https://avatars3.githubusercontent.com/u/3806031?v=4\")
![\"Stefan](\"https://avatars3.githubusercontent.com/u/962099?v=4\")
![\"Phil](\"https://avatars3.githubusercontent.com/u/31462?v=4\")