Cloudflare WorkerEntrypointConstructor ignores its Env generic

[matthew-gizmo]

Environment

• @sentry/cloudflare: 10.65.0
• TypeScript: 7.0.2
• Wrangler: 4.110.0
• Cloudflare Workers runtime types: 4.20260410.1

What is the problem?

The published WorkerEntrypointConstructor declaration exposes an Env generic, but its constructor parameter ignores that generic and always uses typeof cloudflareEnv:

export type WorkerEntrypointConstructor<
  Env = typeof cloudflareEnv,
  Props = {}
> = new (
  ctx: ExecutionContext,
  env: typeof cloudflareEnv
) => InstanceType<typeof WorkerEntrypoint<Env, Props>>;

As a result, passing a normal WorkerEntrypoint<CustomEnv> class to withSentry() is rejected even though the callback and class use the same environment:

interface CustomEnv {
  SENTRY_DSN: string;
  MY_BINDING: KVNamespace;
}

class MyWorker extends WorkerEntrypoint<CustomEnv> {
  fetch() {
    return new Response('ok');
  }
}

export default Sentry.withSentry(
  (env: CustomEnv) => ({ dsn: env.SENTRY_DSN }),
  MyWorker
);

The generic constraint on withSentry() also uses the unconstrained/default WorkerEntrypointConstructor, which reinforces the mismatch.

Expected behavior

WorkerEntrypointConstructor<Env> should accept env: Env, and withSentry<Env>() / instrumentWorkerEntrypoint<Env>() should constrain the class using WorkerEntrypointConstructor<Env>.

Suggested declaration change

export type WorkerEntrypointConstructor<
  Env = typeof cloudflareEnv,
  Props = {}
> = new (
  ctx: ExecutionContext,
  env: Env
) => InstanceType<typeof WorkerEntrypoint<Env, Props>>;

export declare function instrumentWorkerEntrypoint<
  Env = typeof cloudflareEnv,
  T extends WorkerEntrypointConstructor<Env> = WorkerEntrypointConstructor<Env>
>(
  optionsCallback: (env: Env) => CloudflareOptions | undefined,
  WorkerEntrypointClass: T
): T;

The withSentry() union should similarly use WorkerEntrypointConstructor<Env>.

Both build/types and build/types-ts3.8 contain the same incorrect declaration. This is declaration-only; the 10.65 runtime behavior is not implicated.

[linear-code]

JS-3023

[isaacs]

Thanks for the report! You're right, this is a real bug. WorkerEntrypointConstructor declares the Env generic but its constructor parameter hardcodes env: typeof cloudflareEnv (instrumentWorkerEntrypoint.ts), so the generic is only half-wired. It's used for the instance/return type but not for the env the caller actually passes. That's why a WorkerEntrypoint<CustomEnv> class is rejected. Its constructor wants env: CustomEnv, but the constraint asks for the (unrelated) ambient env type. It's declaration-only; the runtime never depends on the env type, so no 10.65 runtime behavior is affected.

Your suggested change to WorkerEntrypointConstructor (env: Env) and to instrumentWorkerEntrypoint<Env> is the right shape, and it's backwards-compatible since Env still defaults to typeof cloudflareEnv.

Two things to flag on the withSentry() side before we (or you, if you'd like to PR) land a fix for this:

• withSentry's signature is a ExportedHandler | WorkerEntrypointConstructor union, and threading Env through the WorkerEntrypoint branch means inferring it from a construct-signature position inside a union. That's easy to get subtly wrong and can regress inference for plain ExportedHandler users. There's also an existing TODO(v11) in that file noting the generics need a rework, with the planned direction being to loosen the union to WorkerEntrypointConstructor<any, any> (which would also accept your class). So for withSentry specifically we'd probably lean toward that loosening rather than full <Env> threading, and keep the strict <Env> typing on instrumentWorkerEntrypoint/WorkerEntrypointConstructor where inference is clean.
• Because this is entirely type-level and the cloudflare package doesn't yet have type tests, a fix should probably come with a small compile/type-test fixture (e.g. asserting withSentry((env: CustomEnv) => { ... }, MyWorker) and instrumentWorkerEntrypoint((env: CustomEnv) => { ... }, MyWorker) both type-check). That's what lets us prevent it from regressing.

@JPeer264 Do you agree with this assessment?

[JPeer264]

#22310 is actually fixing that issue.

[github-actions]

A PR closing this issue has just been released 🚀

This issue was referenced by PR #22310, which was included in the 10.67.0 release.