From d8224cda0eb56f99a26d365b9543653eed87c74e Mon Sep 17 00:00:00 2001 From: Philippe Serhal Date: Tue, 21 Oct 2025 18:48:49 -0400 Subject: [PATCH 1/2] docs: fix misleading comments --- packages/edge-functions/prod/src/main.ts | 5 ++--- packages/runtime/src/lib/globals.ts | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/packages/edge-functions/prod/src/main.ts b/packages/edge-functions/prod/src/main.ts index 60c57a70..d718f858 100644 --- a/packages/edge-functions/prod/src/main.ts +++ b/packages/edge-functions/prod/src/main.ts @@ -1,9 +1,8 @@ import type { NetlifyGlobal } from '@netlify/types' declare global { - // Using `var` so that the declaration is hoisted in such a way that we can - // reference it before it's initialized. - + // Using `var` instead of `const` to allow TypeScript declaration merging. + // Multiple packages can declare the same global with `var`, but `const` cannot be redeclared. var Netlify: NetlifyGlobal } diff --git a/packages/runtime/src/lib/globals.ts b/packages/runtime/src/lib/globals.ts index 8b201dbe..a90e2953 100644 --- a/packages/runtime/src/lib/globals.ts +++ b/packages/runtime/src/lib/globals.ts @@ -4,9 +4,8 @@ import type { Context, NetlifyGlobal } from '@netlify/types' import { GlobalScope } from './util.js' declare global { - // Using `var` so that the declaration is hoisted in such a way that we can - // reference it before it's initialized. - + // Using `var` instead of `const` to allow TypeScript declaration merging. + // Multiple packages can declare the same global with `var`, but `const` cannot be redeclared. var Netlify: NetlifyGlobal } From a44d0ff514cc5ae746d8bf2662fcf3a29d30a5b8 Mon Sep 17 00:00:00 2001 From: Philippe Serhal Date: Tue, 21 Oct 2025 18:52:09 -0400 Subject: [PATCH 2/2] fix(types): allow `global.Netlify` declaration merging This fixes a TypeScript error that occurs when both `@netlify/edge-functions@3.x` and `@netlify/functions` are installed in a project (with `skipLibCheck: false`). It would fail with: ``` Error: TS2451: Cannot redeclare block-scoped variable 'Netlify' ``` See for example https://github.com/netlify/primitives/issues/489. You would think it wouldn't be valid to use both those packages at once, but TypeScript global module augmentation is truly _global_ - it doesn't care where you import a package that performs global module augmentation; your whole TS project is compiled/typechecked as one program, unless you explicitly configure things completely separately for your `./netlify/functions` vs. `./netlify/edge-functions` vs. `src/`... which pretty much no one does. TypeScript allows multiple `var` declarations in a scope to merge, but `const` declarations are cannot be redeclared. When both packages declare `global.Netlify`, they must both use `var` for the declarations to merge successfully. We were actually already doing this correctly, but unfortunately there was a comment that was lying about _why_ (and there was no type test covering this). This led me to change it to `const` in https://github.com/netlify/primitives/pull/434. I went down a rabbit hole trying to add a regression type test for this but I had to cut my losses after running into some issues. --- packages/functions/prod/src/main.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/functions/prod/src/main.ts b/packages/functions/prod/src/main.ts index 736ee659..ac79a7fd 100644 --- a/packages/functions/prod/src/main.ts +++ b/packages/functions/prod/src/main.ts @@ -1,7 +1,9 @@ import type { NetlifyGlobal } from '@netlify/types' declare global { - const Netlify: NetlifyGlobal + // Using `var` instead of `const` to allow TypeScript declaration merging. + // Multiple packages can declare the same global with `var`, but `const` cannot be redeclared. + var Netlify: NetlifyGlobal } export { builder } from './lib/builder.js'