@cloudflare/workers-types

What is @cloudflare/workers-types?

@cloudflare/workers-types provides TypeScript type definitions for Cloudflare Workers, enabling developers to write type-safe code for Cloudflare's serverless platform.

What are @cloudflare/workers-types's main functionalities?

FetchEvent

The FetchEvent interface represents the event that is fired when a Fetch request is made. This allows you to intercept and handle HTTP requests.

addEventListener('fetch', (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request: Request): Promise<Response> {
  return new Response('Hello, world!');
}

KVNamespace

KVNamespace provides type definitions for Cloudflare Workers KV, a key-value storage system. This allows you to interact with KV storage in a type-safe manner.

declare const MY_KV_NAMESPACE: KVNamespace;

async function handleRequest(request: Request): Promise<Response> {
  const value = await MY_KV_NAMESPACE.get('my-key');
  return new Response(value || 'Key not found');
}

DurableObjectNamespace

DurableObjectNamespace provides type definitions for Durable Objects, which are stateful objects that can be used to manage state across multiple requests.

declare const MY_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;

class MyDurableObject {
  state: DurableObjectState;
  constructor(state: DurableObjectState) {
    this.state = state;
  }

  async fetch(request: Request): Promise<Response> {
    return new Response('Durable Object response');
  }
}

addEventListener('fetch', (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request: Request): Promise<Response> {
  const id = MY_DURABLE_OBJECT_NAMESPACE.idFromName('object-name');
  const stub = MY_DURABLE_OBJECT_NAMESPACE.get(id);
  return stub.fetch(request);
}

Other packages similar to @cloudflare/workers-types

@types/aws-lambda

@types/aws-lambda provides TypeScript type definitions for AWS Lambda, another serverless computing platform. While it offers type safety for AWS Lambda functions, it does not cover Cloudflare-specific features.

@types/express

@types/express provides TypeScript type definitions for Express.js, a web application framework for Node.js. While it helps in building server-side applications, it does not offer the serverless and edge computing capabilities of Cloudflare Workers.

README

Cloudflare Workers Types

Install

npm install -D @cloudflare/workers-types
-- Or
yarn add -D @cloudflare/workers-types

Usage

The following is a minimal tsconfig.json for use alongside this package:

tsconfig.json

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "lib": ["esnext"],
    "types": ["@cloudflare/workers-types"]
  }
}

Compatibility dates

The Cloudflare Workers runtime manages backwards compatibility through the use of Compatibility Dates. Using different compatibility dates affects the runtime types available to your Worker, and so it's important you specify the correct entrypoint to the workers-types package to match your compatibility date (which is usually set in your wrangler.toml configuration file). workers-types currently exposes the following entrypoints to choose from:

• @cloudflare/workers-types

  The default entrypoint exposes the runtime types for a compatibility date before 2021-11-03.

• @cloudflare/workers-types/2021-11-03

  This entrypoint exposes the runtime types for a compatibility date between 2021-11-03 and 2022-01-31.

• @cloudflare/workers-types/2022-01-31

  This entrypoint exposes the runtime types for a compatibility date between 2022-01-31 and 2022-03-21.

• @cloudflare/workers-types/2022-03-21

  This entrypoint exposes the runtime types for a compatibility date between 2022-03-21 and 2022-08-04.

• @cloudflare/workers-types/2022-08-04

  This entrypoint exposes the runtime types for a compatibility date between 2022-08-04 and 2022-10-31.

• @cloudflare/workers-types/2022-10-31

  This entrypoint exposes the runtime types for a compatibility date between 2022-10-31 and 2022-11-30.

• @cloudflare/workers-types/2022-11-30

  This entrypoint exposes the runtime types for a compatibility date between 2022-11-30 and 2023-03-01.

• @cloudflare/workers-types/2023-03-01

  This entrypoint exposes the runtime types for a compatibility date between 2023-03-01 and 2023-07-01.

• @cloudflare/workers-types/2023-07-01

  This entrypoint exposes the runtime types for a compatibility date after 2023-07-01.

• @cloudflare/workers-types/experimental

  This entrypoint exposes the runtime types for the latest compatibility date. The types exposed by this entrypoint will change over time to always reflect the latest version of the Workers runtime.

To use one of these entrypoints, you need to specify them in your tsconfig.json. For example, this is a sample tsconfig.json for using the 2022-08-04 entrypoint.

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "lib": ["esnext"],
    "types": ["@cloudflare/workers-types/2022-08-04"]
  }
}

Importable Types

It's not always possible (or desirable) to modify the tsconfig.json settings for a project to include all the Cloudflare Workers types. For use cases like that, this package provides importable versions of its types, which are usable with no additional tsconfig.json setup. For example:

import type { Request as WorkerRequest, ExecutionContext } from "@cloudflare/workers-types/experimental"

export default {
  fetch(request: WorkerRequest, env: unknown, ctx: ExecutionContext) {
    return new Response("OK")
  }
}

Using bindings

It's recommended that you create a type file for any bindings your Worker uses. Create a file named worker-configuration.d.ts in your src directory.

If you're using Module Workers, it should look like this:

// worker-configuration.d.ts
interface Env {
  MY_ENV_VAR: string;
  MY_SECRET: string;
  myKVNamespace: KVNamespace;
}

For Service Workers, it should augment the global scope:

// worker-configuration.d.ts
declare global {
  const MY_ENV_VAR: string;
  const MY_SECRET: string;
  const myKVNamespace: KVNamespace;
}
export {}

Wrangler can also generate this for you automatically from your wrangler.toml configuration file, using the wrangler types command.