Feedback on wrangler types

[penalosa]

Hey everyone 👋 Yesterday we released a new experimental command that dynamically generates runtime types for your project, replacing the need for the @cloudflare/workers-types package. It is available as of wrangler 3.66.0.

What is the command?

# saves runtime types to ./.wrangler/types/runtime.d.ts
wrangler types --experimental-include-runtime

# using the shorthand alias
wrangler types --x-include-runtime
        
# saves runtime types to ./types.d.ts
wrangler types --x-include-runtime="./types.d.ts"

What does it do?

• generates types according to the compatibility_date and compatibility_flags entries of your wrangler.toml.
• replaces the need for @cloudflare/workers-types.

What is the plan?

This is the first step in attempting to remove any pain points in using TypeScript with workers. This manual command could eventually be used as part of an automated system that doesn't require user intervention.

It would therefore be extremely useful to learn about how you use this command, and any ideas you have for automating the process.

The initial docs are available at https://aj-runtime-types.cloudflare-docs-7ou.pages.dev/workers/languages/typescript/#dynamic-runtime-types-experimental

[GregBrimble]

Just making sure I'm understanding usage correctly. Does this all make sense to you, and can you confirm this is the most recommended path for generated types + experimental generated runtime types + Vitest?

- tsconfig.json
- tsconfig.tests.json
- packages/
  - my-worker/
    - wrangler.toml
    - tsconfig.json
    - worker-configuration.d.ts
    - vitest.config.ts
    - src/
      - index.ts
    - __tests__/
      - tsconfig.json
      - env.d.ts
      - index.test.ts

tsconfig.json

{
  "compilerOptions": {
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "ESNext",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "module": "Preserve",
    "moduleResolution": "Bundler",
    "noEmit": true,
    "lib": ["ESNext"]
  },
  "include": [
    "${configDir}/src/**/*.ts",
    "${configDir}/worker-configuration.d.ts"
  ]
}

tsconfig.tests.json

{
  "extends": "./tsconfig.json",
  "include": [
    "${configDir}/**/*.ts",
    "${configDir}/../worker-configuration.d.ts"
  ]
}

packages/my-worker/wrangler.toml

name = "my-worker"
main = "./src/index.ts"
compatibility_date = "2024-07-24"
compatibility_flags = ["nodejs_compat"]
[[migrations]]

tag = "v1"

new_classes = ["MyDO"]
[[durable_objects.bindings]]

name = "MY_DO"

class_name = "MyDO"

packages/my-worker/tsconfig.json

{
  "compilerOptions": {
    "types": ["./.wrangler/types/runtime.d.ts"]
  },
  "extends": "../../tsconfig.json"
}

packages/my-worker/worker-configuration.d.ts

// Generated by Wrangler on Wed Jul 24 2024 14:32:57 GMT-0400 (Eastern Daylight Time)
// by running `wrangler types --experimental-include-runtime`
interface Env {

MY_DO: DurableObjectNamespace<import("./src/index").MyDO>;

}

packages/my-worker/vitest.config.ts

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
export default defineWorkersConfig({

test: {

poolOptions: {

workers: {

wrangler: { configPath: "./wrangler.toml" },

},

},

},

});

packages/my-worker/src/index.ts

import { WorkerEntrypoint, DurableObject } from "cloudflare:workers";
export default class extends WorkerEntrypoint {

fetch(request) {

return new Response("Hello, world!");

}

}
export class MyDO extends DurableObject {}

packages/my-worker/src/__tests__/tsconfig.json

{
  "compilerOptions": {
    "types": [
      "@cloudflare/vitest-pool-workers",
      "../.wrangler/types/runtime.d.ts"
    ]
  },
  "extends": "../../../tsconfig.tests.json"
}

packages/my-worker/src/__tests__/end.d.ts

declare module "cloudflare:test" {
  interface ProvidedEnv extends Env {}
}

packages/my-worker/src/__tests__/index.test.ts

import { env } from "cloudflare:workers";
import { describe, it } from "vitest";
describe("my-worker", () => {

it("should work", ({ expect }) => {

expect(env.MY_DO.newUnique()).toBeTruthy();

});

});

Assuming that's all correct...

Feedback

• Would love it if ./packages/my-worker/__tests__/env.d.ts could be autogenerated (or hidden away entirely) somehow. I imagine every project has this boilerplate file with 99% of people making zero changes here.
• It's annoying that tsconfig's ${configDir} variable doesn't seem to work in compilerOptions.types. Not your fault, but this would let me set up a bunch of Workers in a monorepo and enforce a consistent file naming conventions and folder structure. Previously, I could at least get away with compilerOptions.types being inherited because they were just a Node module reference, but now that it's a relative file ref, it doesn't work.
• I only skimmed the docs, but I was a bit confused when I ran npx wrangler types --experimental-runtime-types. I saw in the stdout that we generated ./.wrangler/types/runtime.d.ts and so yeah, updated my tsconfig.json's compilerOptions.types to include that. But then Env wasn't there! I saw the TS interface was printed in stdout, so I knew it had been parsed from my wrangler.toml correctly. But it took me a minute to realize it had been output into worker-configuration.d.ts. Either, Env should go into ./.wrangler/types/runtime.d.ts (if that's appropriate), or we should print out something like "✨ Environment types written to ./worker-configuration.d.ts" just like we have for the runtime types. Without it, it wasn't clear that two files were generated and that I needed to now reference them both.
• I'd love to have a flag in wrangler dev which runs this runtime generation in watch mode. You're already watching wrangler.toml, and this generated file is gitignored by default, so to be able to easily update it without needing to remember to update types, and also for an easier onboarding of other team members, it would be cool if I essentially just get this for free with dev.

[GregBrimble]

Consider pulling in #5086 as part of this work?

[supfilistine]

I am using this method to generate the worker-types instead of the npm package of the same name and it has worked fine for me for the most part.

My linter has a quandary with some imports though. They are the abstract classes such as WorkerEntrypoint. They are under a "declare module {}", of name "cloudflare:workers".

I need a non-type import of them, but from a d.ts. Is that even the correct use of a d.ts file? Bun as a runtime just fails to run any of my workers that have this very common import.

tslint-eslint only recognizes the:

import type { WorkerEntrypoint } from "cloudflare:workers"

Omitting type makes both it and Bun complaint about missing package "cloudflare:workers".

I am curious how Wrangler is building this typescript when its a non type import? Which npm package is the actual definition of WorkerEntrypoint coming from?