Bootstrapping a Typescript Worker

Cloudflare Workers allows you to quickly deploy Javascript code to our 150+ data centers around the world and execute very close to your end-user. The edit/compile/debug story is already pretty amazing using the Workers IDE with integrated Chrome Dev Tools. However, for those hankering for some Typescript and an IDE with static analysis, autocomplete and that jazz, follow along to see one way to set up a Typescript project with Webstorm and npm run upload your code straight to the edge.

My environment looks like this:

• macOS High Sierra

• node v8.11.3

• npm v5.6.0

• Webstorm v2018.1.3

You'll also need a Cloudflare domain and to activate Workers on it.

I'll be using cryptoserviceworker.com

I'll also use Yeoman to build our initial scaffolding. Install it with npm install yo -g

Let's start with a minimal node app with a "hello world" class and a test.

mkdir cryptoserviceworker && cd cryptoserviceworker
npm install generator-node-typescript -g
yo node-typescript

That generator creates the following directory structure:

drwxr-xr-x   16 steve  staff     512 Jun 18 20:40 .
drwxr-xr-x   10 steve  staff     320 Jun 18 20:35 ..
-rw-r--r--    1 steve  staff     197 Jun 18 20:40 .editorconfig
-rw-r--r--    1 steve  staff      96 Jun 18 20:40 .gitignore
-rw-r--r--    1 steve  staff     147 Jun 18 20:40 .npmignore
-rw-r--r--    1 steve  staff     267 Jun 18 20:40 .travis.yml
drwxr-xr-x    5 steve  staff     160 Jun 18 20:40 .vscode
-rw-r--r--    1 steve  staff    1066 Jun 18 20:40 LICENSE
-rw-r--r--    1 steve  staff    2071 Jun 18 20:40 README.md
drwxr-xr-x    4 steve  staff     128 Jun 18 20:40 __tests__
drwxr-xr-x  479 steve  staff   15328 Jun 18 20:40 node_modules
-rw-r--r--    1 steve  staff  244624 Jun 18 20:40 package-lock.json
-rw-r--r--    1 steve  staff    1506 Jun 18 20:40 package.json
drwxr-xr-x    4 steve  staff     128 Jun 18 20:40 src
-rw-r--r--    1 steve  staff     454 Jun 18 20:40 tsconfig.json
-rw-r--r--    1 steve  staff      73 Jun 18 20:40 tslint.json

It includes default settings, a task runner, an initial Typescript config and more. We won't use all of it, but it's a good starting point.

If we take a look at the contents of src/greeter.ts, we'll see it's a very Typescript implementation of hello world.

$ cat greeter.ts 
export class Greeter {
  private greeting: string;

  constructor(message: string) {
    this.greeting = message;
  }

  public greet(): string {
    return `Bonjour, ${this.greeting}!`;
  }
}

Because Yeoman has set up our test infrastructure, we should be able exercise the code using the greeter test in __tests__/greeter-spec.ts

import { Greeter } from '../src/greeter';

test('Should greet with message', () => {
  const greeter = new Greeter('friend');
  expect(greeter.greet()).toBe('Bonjour, friend!');
});

This generator uses jest. It's installed locally, but let's install it globally for convenience and run it!

npm install jest -g
jest
 PASS  __tests__/greeter-spec.ts
 PASS  __tests__/index-spec.ts

Test Suites: 2 passed, 2 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        1.867s
Ran all test suites.

OK, so we have a testable Typescript template. Let's fire up Webstorm and write some code!

A hello world implementation in Typescript might look something like this:

Webstorm doesn't like it as you can see from the red error highlights. Even though Request and Response are part of the Service Worker API and will be available to us in the V8 runtime, Typescript doesn't know about them yet. node-fetch provides an implementation for node, so let’s install that.

npm install node-fetch
npm install @types/node-fetch

That made Webstorm happier. It’s been able to locate the type definitions.

Now let's write a test. Create a new file tests/worker-spec.ts:

import { Request } from "node-fetch";
import { Worker } from "../src/worker";

test('Should say hello', () => {

  const worker = new Worker();
  const request = new Request("https://cryptoserviceworker.com/");
  const response = worker.handle(request);
  expect(response.status).toEqual(200);
  expect(response.body).toEqual("Hello, world!");
});

And delete the other files and tests so we're just working worker.ts and worker-spect.ts

Run jest

 PASS  __tests__/worker-spec.ts
 PASS  __tests__/worker-spec.js

Test Suites: 2 passed, 2 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        1.213s, estimated 2s

OK, so our test passed, but notice it ran both the Typescript and the Javascript? Let's restrict to just Typescript. Go into package.json, locate jest and change

"testRegex": "(/__tests__/.*|\\.(test|spec))\\.(ts|js)$", to"testRegex": "(/__tests__/.*)\\-spec.ts$"

Run it again:

jest
 PASS  __tests__/worker-spec.ts
  ✓ Should say hello (8ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.123s, estimated 2s
Ran all test suites.

Better. OK, ship it!

Let's take a look at src/worker.js to see how our Typescript transpiled.

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const node_fetch_1 = require("node-fetch");
class Worker {
    handle(request) {
        return new node_fetch_1.Response('Hello, world!');
    }
}
exports.Worker = Worker;

Actually, let's try it in the Cloudflare Workers IDE and try it for real. Go to your dashboard, click the Workers icon and then "Launch Editor"

First things first, check the canonical Hello World implementation works.

Awesome, now let's replace it with our "transpiled from Typescript" version:

Fail. OK, so the out of the box "transpiled from typescript" is not going to work. Let's make the changes necessary to get it run manually, then incorporate that into the build process.

Error #1: Uncaught ReferenceError: exports is not defined at line 2That's easy enough, let's add var exports = {}. Update Preview.

Error #2: Uncaught ReferenceError: require is not defined at line 4

True, we're running in V8 on the Cloudflare Edge and the only code is what we uploaded. There are no "node_modules" to include. Plus, that line was only for dev anyway. Remove it. Update Preview.

Error #3: No event handlers were registered. This script does nothing.

Right, we need to invoke the code. Let's add a snippet to the top of the file to actually invoke our worker.

addEventListener('fetch', event => {
  let worker = new exports.Worker();
  event.respondWith(worker.handle(event.request));
})

Error #4: Uncaught ReferenceError: node_fetch_1 is not defined

Right, we removed that because Response is a native object when it runs in the context of a worker. So remove the node_fetch_1 prefix.

Error #5: exports.__esModule = true does nothing

So let's remove that.

Success!!

OK, so with some massaging, we got a Worker transpiled from Typescript to execute. We:

• Added a line to create an exports object

• Removed the dev dependency on "node_fetch"

• Removed the exports.__esModule = true line

Let's add that to our build process so we can have "Worker-ready" Javascript every time we make a change to our Typescript.

I'm going to use Grunt to automate that. Here's my new worker.ts

// --BEGIN PREAMBLE--
/// //Invoke worker
/// var exports = {};
/// addEventListener('fetch', event => {
///   event.respondWith(fetchAndApply(event.request))
/// });
///
/// async function fetchAndApply(request) {
///   let worker = new exports.Worker();
///   return worker.handle(request);
/// }
// --END PREAMBLE--

// --BEGIN COMMENT--
// mock the methods and objects that will be available in the browser
import { Request, Response } from 'node-fetch';
// --END COMMENT--
export class Worker {
  public handle(request: Request) {
    return new Response("Hello, world!")
  }
}

I want to uncomment the preamble to invoke our script, comment out the dev dependencies and remove the __esmodule line. Let's install Grunt, a text-replace module and create a Gruntfile.js

npm install grunt-cli -g
npm install grunt --save-dev
npm install grunt-replace --save-dev
touch Gruntfile.js

My Gruntfile.js looks like this

module.exports = function (grunt) {

  grunt.loadNpmTasks('grunt-replace');
  grunt.initConfig({
    replace: {
      comments: {
        options: {
          patterns: [
            {
              /* Comment imports for node during dev */
              match: /--BEGIN COMMENT--[\s\S]*?--END COMMENT--/g,
              replacement: 'Dev environment code block removed by build'
            },
            {
              /* Uncomment preamble for production to process the request */
              match: /\/\/\//mg,
              replacement: ''
            }
          ]
        },
        files: [
          { expand: true, flatten: true, src: ['src/worker.ts'], dest: 'build/' }
        ]
      },
      exports: {
        //remove the exports line that typescript includes without an option to
        //suppress, but is not in the v8 env that workers run in.
        options: {
          patterns: [
            {
              match: /exports.__esModule = true;/g,
              replacement: "// exports line commented by build"
            }
          ]
        },
        files: [
          { expand: true, flatten: true, src: ['build/worker.js'], dest: 'build/' }
        ]
      }
    }
  });

  grunt.registerTask('prepare-typescript', 'replace:comments');
  grunt.registerTask('fix-export', 'replace:exports');
};

There are two tasks. The first is the comment/uncomment step that we want before our Typescript is transpiled.

The second is to remove the exports.__esmodule = true line

$ grunt prepare-typescript
Running "replace:comments" (replace) task
>> 11 replacements in 1 file.

Done.

If we open build/worker.ts, we see this:

// --BEGIN PREAMBLE--
 //Invoke worker
 var exports = {};
 addEventListener('fetch', event => {
   event.respondWith(fetchAndApply(event.request))
 });

 async function fetchAndApply(request) {
   let worker = new exports.Worker();
   return worker.handle(request);
 }
// --END PREAMBLE--

// Dev environment code block removed by build
export class Worker {
  public handle(request: Request) {
    return new Response("Hello, world!")
  }
}

Opening build/worker.js you'll see a whole lot of code generated for handling async functions. That's because we're using the async keyword in the preamble.

"use strict";
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
    return new (P || (P = Promise))(function (resolve, reject) {
        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
        function step(result) { result.done ? resolve(result.value) : new P(function (resolve) { resolve(result.value); }).then(fulfilled, rejected); }
        step((generator = generator.apply(thisArg, _arguments || [])).next());
    });
};
var __generator = (this && this.__generator) || function (thisArg, body) {
    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
    function verb(n) { return function (v) { return step([n, v]); }; }
    function step(op) {
        if (f) throw new TypeError("Generator is already executing.");
        while (_) try {
            if (f = 1, y && (t = y[op[0] & 2 ? "return" : op[0] ? "throw" : "next"]) && !(t = t.call(y, op[1])).done) return t;
            if (y = 0, t) op = [0, t.value];
            switch (op[0]) {
                case 0: case 1: t = op; break;
                case 4: _.label++; return { value: op[1], done: false };
                case 5: _.label++; y = op[1]; op = [0]; continue;
                case 7: op = _.ops.pop(); _.trys.pop(); continue;
                default:
                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
                    if (t[2]) _.ops.pop();
                    _.trys.pop(); continue;
            }
            op = body.call(thisArg, _);
        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
    }
};
exports.__esModule = true;
// --BEGIN PREAMBLE--
//Invoke worker
var exports = {};
addEventListener('fetch', function (event) {
    event.respondWith(fetchAndApply(event.request));
});
function fetchAndApply(request) {
    return __awaiter(this, void 0, void 0, function () {
        var worker;
        return __generator(this, function (_a) {
            worker = new exports.Worker();
            return [2 /*return*/, worker.handle(request)];
        });
    });
}
// --END PREAMBLE--
// Dev environment code block removed by build
var Worker = /** @class */ (function () {
    function Worker() {
    }
    Worker.prototype.handle = function (request) {
        return new Response("Hello, world!");
    };
    return Worker;
}());
exports.Worker = Worker;

Now let's remove that exports.__esModule = true line.

grunt fix-export

and now we'll see instead in the worker.js // exports line commented by build.

I just want to run npm run build and get Worker-friendly Javascript. Let's modify package.json to do just that. Change

"build": "tsc --pretty" to "build": "grunt prepare-typescript && tsc build/*.ts --pretty --skipLibCheck; grunt fix-export",

And run it.

npm run build will result in

"use strict";
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
    return new (P || (P = Promise))(function (resolve, reject) {
        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
        function step(result) { result.done ? resolve(result.value) : new P(function (resolve) { resolve(result.value); }).then(fulfilled, rejected); }
        step((generator = generator.apply(thisArg, _arguments || [])).next());
    });
};
var __generator = (this && this.__generator) || function (thisArg, body) {
    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
    function verb(n) { return function (v) { return step([n, v]); }; }
    function step(op) {
        if (f) throw new TypeError("Generator is already executing.");
        while (_) try {
            if (f = 1, y && (t = y[op[0] & 2 ? "return" : op[0] ? "throw" : "next"]) && !(t = t.call(y, op[1])).done) return t;
            if (y = 0, t) op = [0, t.value];
            switch (op[0]) {
                case 0: case 1: t = op; break;
                case 4: _.label++; return { value: op[1], done: false };
                case 5: _.label++; y = op[1]; op = [0]; continue;
                case 7: op = _.ops.pop(); _.trys.pop(); continue;
                default:
                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
                    if (t[2]) _.ops.pop();
                    _.trys.pop(); continue;
            }
            op = body.call(thisArg, _);
        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
    }
};
// exports line commented by build
// --BEGIN PREAMBLE--
//Invoke worker
var exports = {};
addEventListener('fetch', function (event) {
    event.respondWith(fetchAndApply(event.request));
});
function fetchAndApply(request) {
    return __awaiter(this, void 0, void 0, function () {
        var worker;
        return __generator(this, function (_a) {
            worker = new exports.Worker();
            return [2 /*return*/, worker.handle(request)];
        });
    });
}
// --END PREAMBLE--
// Dev environment code block removed by build
var Worker = /** @class */ (function () {
    function Worker() {
    }
    Worker.prototype.handle = function (request) {
        return new Response('Hello, world!');
    };
    return Worker;
}());
exports.Worker = Worker;

Paste that into the Workers IDE... works first time.

It's going to get old uploading from our IDE to the Web IDE every time we want to test a change and we're going to want to auto deploy from CI at some point. Thankfully there's Workers Configuration API, which makes it very simple to upload a Worker automatically:

curl -X PUT "https://api.cloudflare.com/client/v4/zones/:zone_id/workers/script" -H "X-Auth-Email:YOUR_CLOUDFLARE_EMAIL" -H "X-Auth-Key:ACCOUNT_AUTH_KEY" -H "Content-Type:application/javascript" --data-binary "@PATH_TO_YOUR_WORKER_SCRIPT"

OK, so we need our zone ID, Cloudflare email, auth key and path to the binary. I'm going to create Grunt task that uses the dotenv package to load config from a .env file or environment variables.

Create a .env file that looks like this:

CF_WORKER_ZONE_ID=xxxxxxxxxxxxxxxxxxx
[email protected]
CF_WORKER_AUTH_KEY=xxxxxxxxxxxxxxxxxx
CF_WORKER_PATH=build/worker.js

To locate your zone ID and auth key, go to the dashboard, select your zone and click the "Overview" icon.

The zone ID is right there, then click "Get API key" and choose the "Global API Key" to get the Auth Key.

Fill out your .env with those values and then add the following to your Gruntfile which will:

• Read your config

• Upload to Cloudflare

• Parse any success or error messages.

grunt.registerTask('upload-worker', 'Uploads workers to Cloudflare', function(path) {

    require('dotenv').config();
    const fs = require('fs');
    const log = console;

    const done = this.async();
    const conf = readConfig();
    path = path || grunt.option('path') || process.env.CF_WORKER_PATH;
    if (!path) {
      fail("path is required");
    }
    if (!fs.existsSync(path)) {
      fail(`path not found ${path}`);
    }

    let script = fs.readFileSync(path);
    log.info("Uploading...");
    let url = `https://api.cloudflare.com/client/v4/zones/${conf.zoneId}/workers/script`;
    let options = {
      url: url,
      method: 'PUT',
      headers: {
        'Content-Type': 'application/javascript'
      },
      body: script
    };
    invokeApi(options, conf, done);
  });

  function invokeApi(options, conf, done) {

    // Add authentication to the request
    options.headers = options.headers || {};
    Object.assign(options.headers, {
      'X-Auth-Email': conf.email,
      'X-Auth-Key': conf.apiKey,
    });

    request(options, function(error, response) {
      try {
        if (error) {
          log.error(error);
          fail(`API failure ${response.statusCode} error: ${error}`);
          done();
          return;
        }
        let body = JSON.parse(response.body);
        if (body) {
          logResult(body);
        }
        done();
      } catch (e) {
        fail(`Unhandled error. ${e}`);
        done();
      }
    });
  }

  function logResult(body) {
    body.success ? log.error("Status: Success") : log.error("Status: Failed");
    let errors = body.errors || [];
    if (errors) {
      log.info(` Errors: ${errors.length}`);
      for (let e of errors) {
        log.error(` Code: ${e.code} Message: ${e.message}`);
      }
    }
    let messages = body.messages || [];
    if (messages) {
      log.info(` Messages ${messages.length}`);
      for (let msg of messages) {
        log.info(` ${msg}`);
      }
    }
    let result = body.result;
    log.info(" Result");
    log.info(` ${JSON.stringify(result, null, 2)}`);
  }

  function readConfig() {
    let zoneId = grunt.option('zoneId') || process.env.CF_WORKER_ZONE_ID;
    let email = grunt.option('email') || process.env.CF_WORKER_EMAIL;
    let apiKey = grunt.option('apiKey') || process.env.CF_WORKER_AUTH_KEY;

    log.debug("zoneID: " + zoneId);
    log.debug("email: " + email);
    log.debug("apiKey: " + "*".repeat(apiKey.length));

    if (!zoneId || !email || !apiKey) {
      fail("zone id, cloudflare email and api key are required");
    }
    return {
      zoneId: zoneId,
      email: email,
      apiKey: apiKey
    }
  }

  function fail(message) {
    grunt.fail.fatal(message, TASK_FAILED);
  }

Finally, let's add a new task to package.json so we can just npm run upload any time we update our Worker.

"upload": "grunt upload-worker"

npm run upload-worker

Running "upload-worker" task
zoneID: **************
email: [email protected]
apiKey: *************************************
Uploading...
Status: Success
 Errors: 0
 Messages 0
 Result
 {
  "script"...
 }

Voila! Script uploaded. OK, so if it's uploaded, we can call call it remotely:

$ curl https://cryptoserviceworker.com/hello

Hmmm... nothing. Ah, we haven't actually configured Workers to route any requests to our Worker. You can do this via the API, but since it's a one off, I'll do it in the web IDE.

And try again:

$ curl https://cryptoserviceworker.com/hello
Hello, world!

Success! OK, so to recap:

• We've bootstrapped a Typescript project using NodeJS and Webstorm

• Written a "Hello, World" worker in Typescript

• Setup build tasks to modify the code for Workers

• Automatically uploading to the Cloudflare edge with npm run upload

• ...

• Profit

---

If you have a worker you'd like to share, or want to check out workers from other Cloudflare users, visit the “Recipe Exchange” in the Workers section of the Cloudflare Community Forum.