Cloud Run - TypeScript boilerplate for getting started
Published: 2023-12-01 22:27:57

My goal for this article is to help you get started writing TypeScript apps that you can deploy to Cloud Run.

Because Google Cloud documentation is tailored primarily for JavaScript, it's not necessarily clear to developers that you can write TypeScript and deploy from source code to Cloud Run as long as you your `package.json` has the following [two run scripts](https://docs.npmjs.com/cli/v10/using-npm/scripts):

1. `build`
2. `start`

So if you just want to add a [tsconfig.json](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html), use [tsc](https://www.typescriptlang.org/docs/handbook/compiler-options.html) in the `build` script to transform TypeScript to JavaScript, and indicate which JavaScript file to run in your `start` script, then all you need to do to deploy a public service from your source is run the following:

    gcloud run deploy [SERVICE] \
      --project [PROJECT] \
      --region [REGION] \
      --allow-unauthenticated \
      --source .

But I'd like to help you more than that. I've created a repo ([cloud-run-app](https://github.com/subfuzion/cloud-run-app)) that contains boilerplate for a starter project.

You don't need to clone the repo. You can generate a new app on your machine with the following command:

    npx create-cloud-run-app [PATH]

- If `path` isn't specified, it defaults to the current working directory (`.`)
- The directory under `PATH` must be empty

The goal for this generator is to give you a bit of opinionated structure, but not too much:

* Your TypeScript code goes under `src`
* Your tests (`*.test.ts`) can go under `src` or `test`
* Your generated output goes under `dist`

I use [Express](https://expressjs.com/) and [Jest](https://jestjs.io/), but only enough to give you something to start with. You can substitute these out for your favorite web and test framework.

In fact, Express is the only one of two dependencies (the other is a cloud logging library). All the other dependencies are [devDependencies](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file) and they are there to provide you with comprehensive compiling, testing, linting, and formatting support.

This is arguably the real value of using this boilerplate, since configuring the integration of TypeScript, editorconfig, eslint, prettier, and Jest so that everything plays well together is a bit challenging. 

For me, it's been a cumulative effort over various projects this past year, but if I had to pin down the effort, I feel that it took days or even a week of toil banging at configuration.

> Side note: I'm totally open to any suggestions if you see ways to improve the configuration. Although you can leave comments below, it would be even better to open an issue or [start a discussion](https://github.com/subfuzion/cloud-run-app/discussions) in the repo.

Go ahead and inspect the generated package.json (or run `npm run-script`), but you these are the main scripts to be aware of:

- `build`
- `test` | `test:watch`
- `deploy`

## Trying it out

First run `npm test` to verify the very simple integration smoke tests pass.

Then, if you haven't already gotten set up with a Google Cloud project so you can deploy to Cloud Run, go see the previous article: [Cloud Run - getting started checklist](https://dev.to/subfuzion/cloud-run-getting-started-checklist-4c6o).

Once you have a cloud project, update the `.cloudconfig` file in your generated project.

> Note: if you want to update `.cloudconfig`, but not accidentally commit it, then make a copy and call it `cloudconfig`. This is automatically ignored by `.gitignore`. Going forward, I'll assume you did this and just refer to `cloudconfig`.

You'll need to set the following variables:

- `SERVICE` - with the name for your service
- `PROJECT` - with your cloud project ID
- `REGION` - with the [region](https://cloud.google.com/run/docs/locations) to deploy to

After updating `cloudconfig`, source the variables into your bash environment:

    source cloudconfig

Then run:

    npm run deploy

Answer yes to any prompts about enabling APIs and creating a repo in the project to store the app container image.

You should see output similar to this:

![deploy output](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ilnk7p4vfvtljo2yee8x.png)

The last line of output contains the service URL. Go ahead and open the link in a browser. You should see an "ok" response.

Congratulations, you have a starter project configured for TypeScript that you can deploy to Cloud Run.

## Next

In the next article, add cloud logging support.