# Using Twilio Serverless with TypeScript

The Twilio Serverless runtime currently does not support running TypeScript by itself but you can use the [TypeScript compiler](https://www.typescriptlang.org/) to compile your Functions ahead of time.

We published TypeScript definitions for our Serverless Runtime at [@twilio-labs/serverless-runtime-types](https://npm.im/@twilio-labs/serverless-runtime-types).

## Creating a new TypeScript Twilio Serverless project

You can create a new Twilio Serverless project via `npm init` or using the [serverless plugin](https://github.com/twilio-labs/plugin-serverless) for the [Twilio CLI](/docs/twilio-cli/quickstart). Either way you can opt to create your new project using TypeScript.

### npm init

To create a new TypeScript based Twilio Serverless project with [npm](https://npmjs.com) you can run `npm init twilio-function` with the `--typescript` option.

```sh title="New TypeScript Twilio Serverless project with npm"
npm init twilio-function project-name --typescript
```

You can also pass the `--typescript` option to the Twilio CLI serverless plugin's `init` command

```sh title="New TypeScript Twilio Serverless project from Twilio CLI"
twilio serverless:init project-name --typescript
```

Both commands will generate a new project with a `src`directory that contains your TypeScript source files. When you run `npm start` or `npm run deploy` the project will automatically be compiled into the `dist` directory and run or deployed from there.

## Converting an existing Twilio Serverless project

### Setup TypeScript

Start by installing the TypeScript compiler for your project using [npm](https://npmjs.com) or another Node.js package manager:

```sh title="Install TypeScript compiler"
# Using npm:
npm install --save-dev typescript

# Using yarn
yarn add --dev typescript
```

Afterwards create your [TypeScript configuration](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html). You can do this by manually creating a `tsconfig.json` in your project or by using the TypeScript compilers `--init` flag.

```sh title="Creating a TypeScript configuration"
# Using npm's npx command
npx tsc --init

# Using yarn
yarn tsc

# Without either
node_modules/.bin/tsc --init
```

Your resulting `tsconfig.json` should look something like this if you ignore the comments:

```bash
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true
  }
}

```

### Install Twilio Serverless Runtime definitions

We need to be able to tell TypeScript about the different types related to the Serverless Runtime. These are called TypeScript definitions and the ones for Serverless Runtime are all bundled in the `@twilio-labs/serverless-runtime-types` module on npm. You'll need to install it as a dependency for your project.

```sh title="Install Serverless Runtime TypeScript definitions"
# Using npm
npm install @twilio-labs/serverless-runtime-types

# Using yarn
yarn add @twilio-labs/serverless-runtime-types
```

### Convert your existing Functions

If you want to convert your existing Functions from JavaScript to TypeScript you'll need to:

* Rename your file to end with `.ts` instead of `.js`
* Change from `require()` statements to `import`
* Add import `'@twilio-labs/serverless-runtime-types';` to the top of your file
* Import additional types necessary from `@twilio-labs/serverless-runtime-types`
* Use `export const handler` instead of `exports.handler`

This is how an example TypeScript version of a Twilio Function would look like.

```typescript title="Example Twilio Serverless Function in TypeScript"
// Imports global types
import '@twilio-labs/serverless-runtime-types';
// Fetches specific types
import {
  Context,
  ServerlessCallback,
  ServerlessFunctionSignature,
} from '@twilio-labs/serverless-runtime-types/types';

export const handler: ServerlessFunctionSignature = function(
  context: Context,
  event: {},
  callback: ServerlessCallback
) {
  const twiml = new Twilio.twiml.VoiceResponse();
  twiml.say('Hello World!');
  callback(null, twiml);
};

```

Since Twilio Serverless and the Toolkit don't support TypeScript out of the box yet, we need to run the compiler before the local development or deployment.

```sh title="Run the TypeScript compiler"
# Use npm
npx tsc

# Use yarn
yarn tsc

# Run the compiler directly
./node_modules/.bin/tsc
```

Afterwards you can [deploy the project](/docs/labs/serverless-toolkit/general-usage#deploy-a-project) or [locally run your project](/docs/labs/serverless-toolkit/general-usage#start-developing-locally).

### Caveats

Right now we are compiling the TypeScript files in a way that results for the JavaScript output files to live side-by-side with the TypeScript files. This is great because that means the Toolkit commands work without any additional arguments.

To move the output somewhere else, set the `outDir` option of the `compilerOptions` inside the `tsconfig.json` file. Afterwards you'll have to call the Toolkit's *start* and *deploy* commands with the `--functions-folder` flag to point again the `functions/` directory inside your output directory.

## What's next?

Now that you know how to combine Twilio Serverless and TypeScript, why not check out some other resources to see what you can do with the Twilio Serverless Toolkit?

* [General Usage](/docs/labs/serverless-toolkit/general-usage)
  * [Create a project](/docs/labs/serverless-toolkit/general-usage#create-a-project)
  * [Project structure](/docs/labs/serverless-toolkit/general-usage#project-structure)
  * [Start developing locally](/docs/labs/serverless-toolkit/general-usage#start-developing-locally)
  * [Create a new Twilio Function](/docs/labs/serverless-toolkit/general-usage#create-a-new-twilio-function)
  * [Deploy a project](/docs/labs/serverless-toolkit/general-usage#deploy-a-project)
* [Examples](/docs/labs/serverless-toolkit/examples)