fix: conditionally access builder properties that only exist on the latest SvelteKit (#14233)

teemingc · web-flow · commit 758ec17e1c99 · 2025-08-16T19:16:48.000+08:00
* add null checks for builder properties that may not exist

* changeset

* format

* fix type errors where we're sure it won't be null or undefined
diff --git a/.changeset/pretty-fans-peel.md b/.changeset/pretty-fans-peel.md
@@ -0,0 +1,8 @@
+---
+'@sveltejs/adapter-cloudflare': patch
+'@sveltejs/adapter-netlify': patch
+'@sveltejs/adapter-vercel': patch
+'@sveltejs/adapter-node': patch
+---
+
+fix: avoid erroring on builder properties that only exist on the latest version of SvelteKit
diff --git a/packages/adapter-auto/index.js b/packages/adapter-auto/index.js
@@ -4,6 +4,17 @@ import path from 'node:path';
 import fs from 'node:fs';
 import process from 'node:process';
 
+/**
+ * @template T
+ * @template {keyof T} K
+ * @typedef {Partial<Omit<T, K>> & Required<Pick<T, K>>} PartialExcept
+ */
+
+/**
+ * We use a custom `Builder` type here to support the minimum version of SvelteKit.
+ * @typedef {PartialExcept<import('@sveltejs/kit').Builder, 'log' | 'rimraf' | 'mkdirp' | 'config' | 'prerendered' | 'routes' | 'createEntries' | 'generateFallback' | 'generateEnvModule' | 'generateManifest' | 'getBuildDirectory' | 'getClientDirectory' | 'getServerDirectory' | 'getAppPath' | 'writeClient' | 'writePrerendered' | 'writePrerendered' | 'writeServer' | 'copy' | 'compress'>} Builder2_0_0
+ */
+
 /** @type {Record<string, (name: string, version: string) => string>} */
 const commands = {
 	npm: (name, version) => `npm install -D ${name}@${version}`,
@@ -138,10 +149,11 @@ async function get_adapter() {
 /** @type {() => Adapter} */
 export default () => ({
 	name: '@sveltejs/adapter-auto',
+	/** @param {Builder2_0_0} builder */
 	adapt: async (builder) => {
 		const adapter = await get_adapter();
 
-		if (adapter) return adapter.adapt(builder);
+		if (adapter) return adapter.adapt(/** @type {import('@sveltejs/kit').Builder} */ (builder));
 
 		builder.log.warn(
 			'Could not detect a supported production environment. See https://svelte.dev/docs/kit/adapters to learn how to configure your app to run on the platform of your choosing'
diff --git a/packages/adapter-auto/tsconfig.json b/packages/adapter-auto/tsconfig.json
@@ -4,6 +4,7 @@
 		"checkJs": true,
 		"noEmit": true,
 		"noImplicitAny": true,
+		"strictNullChecks": true,
 		"target": "es2022",
 		"module": "node16",
 		"moduleResolution": "node16",
diff --git a/packages/adapter-cloudflare/index.js b/packages/adapter-cloudflare/index.js
@@ -9,10 +9,22 @@ import { is_building_for_cloudflare_pages, validate_worker_settings } from './ut
 const name = '@sveltejs/adapter-cloudflare';
 const [kit_major, kit_minor] = VERSION.split('.');
 
+/**
+ * @template T
+ * @template {keyof T} K
+ * @typedef {Partial<Omit<T, K>> & Required<Pick<T, K>>} PartialExcept
+ */
+
+/**
+ * We use a custom `Builder` type here to support the minimum version of SvelteKit.
+ * @typedef {PartialExcept<import('@sveltejs/kit').Builder, 'log' | 'rimraf' | 'mkdirp' | 'config' | 'prerendered' | 'routes' | 'createEntries' | 'generateFallback' | 'generateEnvModule' | 'generateManifest' | 'getBuildDirectory' | 'getClientDirectory' | 'getServerDirectory' | 'getAppPath' | 'writeClient' | 'writePrerendered' | 'writePrerendered' | 'writeServer' | 'copy' | 'compress'>} Builder2_0_0
+ */
+
 /** @type {import('./index.js').default} */
 export default function (options = {}) {
 	return {
 		name,
+		/** @param {Builder2_0_0} builder */
 		async adapt(builder) {
 			if (existsSync('_routes.json')) {
 				throw new Error(
@@ -113,8 +125,8 @@ export default function (options = {}) {
 					ASSETS: assets_binding
 				}
 			});
-			if (builder.hasServerInstrumentationFile()) {
-				builder.instrument({
+			if (builder.hasServerInstrumentationFile?.()) {
+				builder.instrument?.({
 					entrypoint: worker_dest,
 					instrumentation: `${builder.getServerDirectory()}/instrumentation.server.js`
 				});
@@ -197,12 +209,14 @@ export default function (options = {}) {
 }
 
 /**
- * @param {import('@sveltejs/kit').Builder} builder
+ * @param {Builder2_0_0} builder
  * @param {string[]} assets
  * @param {import('./index.js').AdapterOptions['routes']} routes
  * @returns {import('./index.js').RoutesJSONSpec}
  */
-function get_routes_json(builder, assets, { include = ['/*'], exclude = ['<all>'] }) {
+function get_routes_json(builder, assets, routes) {
+	let { include = ['/*'], exclude = ['<all>'] } = routes || {};
+
 	if (!Array.isArray(include) || !Array.isArray(exclude)) {
 		throw new Error('routes.include and routes.exclude must be arrays');
 	}
@@ -297,7 +311,7 @@ _redirects
 }
 
 /**
- * @param {string} config_file
+ * @param {string | undefined} config_file
  * @returns {import('wrangler').Unstable_Config}
  */
 function validate_wrangler_config(config_file = undefined) {
diff --git a/packages/adapter-cloudflare/src/worker.js b/packages/adapter-cloudflare/src/worker.js
@@ -100,7 +100,7 @@ export default {
 					cf: req.cf
 				},
 				getClientAddress() {
-					return req.headers.get('cf-connecting-ip');
+					return /** @type {string} */ (req.headers.get('cf-connecting-ip'));
 				}
 			});
 		}
diff --git a/packages/adapter-cloudflare/tsconfig.json b/packages/adapter-cloudflare/tsconfig.json
@@ -4,6 +4,7 @@
 		"checkJs": true,
 		"noEmit": true,
 		"noImplicitAny": true,
+		"strictNullChecks": true,
 		"target": "es2022",
 		"module": "node16",
 		"moduleResolution": "node16",
diff --git a/packages/adapter-netlify/index.js b/packages/adapter-netlify/index.js
@@ -17,6 +17,17 @@ const [kit_major, kit_minor] = VERSION.split('.');
  * } & toml.JsonMap} NetlifyConfig
  */
 
+/**
+ * @template T
+ * @template {keyof T} K
+ * @typedef {Partial<Omit<T, K>> & Required<Pick<T, K>>} PartialExcept
+ */
+
+/**
+ * We use a custom `Builder` type here to support the minimum version of SvelteKit.
+ * @typedef {PartialExcept<import('@sveltejs/kit').Builder, 'log' | 'rimraf' | 'mkdirp' | 'config' | 'prerendered' | 'routes' | 'createEntries' | 'findServerAssets' | 'generateFallback' | 'generateEnvModule' | 'generateManifest' | 'getBuildDirectory' | 'getClientDirectory' | 'getServerDirectory' | 'getAppPath' | 'writeClient' | 'writePrerendered' | 'writePrerendered' | 'writeServer' | 'copy' | 'compress'>} Builder2_4_0
+ */
+
 const name = '@sveltejs/adapter-netlify';
 const files = fileURLToPath(new URL('./files', import.meta.url).href);
 
@@ -30,7 +41,7 @@ const FUNCTION_PREFIX = 'sveltekit-';
 export default function ({ split = false, edge = edge_set_in_env_var } = {}) {
 	return {
 		name,
-
+		/** @param {Builder2_4_0} builder */
 		async adapt(builder) {
 			if (!builder.routes) {
 				throw new Error(
@@ -114,7 +125,7 @@ export default function ({ split = false, edge = edge_set_in_env_var } = {}) {
 }
 /**
  * @param { object } params
- * @param {import('@sveltejs/kit').Builder} params.builder
+ * @param {Builder2_4_0} params.builder
  */
 async function generate_edge_functions({ builder }) {
 	const tmp = builder.getBuildDirectory('netlify-tmp');
@@ -202,16 +213,16 @@ async function generate_edge_functions({ builder }) {
 			outfile: '.netlify/edge-functions/render.js',
 			...esbuild_config
 		}),
-		builder.hasServerInstrumentationFile() &&
+		builder.hasServerInstrumentationFile?.() &&
 			esbuild.build({
 				entryPoints: [`${builder.getServerDirectory()}/instrumentation.server.js`],
 				outfile: '.netlify/edge/instrumentation.server.js',
 				...esbuild_config
 			})
 	]);
 
-	if (builder.hasServerInstrumentationFile()) {
-		builder.instrument({
+	if (builder.hasServerInstrumentationFile?.()) {
+		builder.instrument?.({
 			entrypoint: '.netlify/edge-functions/render.js',
 			instrumentation: '.netlify/edge/instrumentation.server.js',
 			start: '.netlify/edge/start.js'
@@ -222,7 +233,7 @@ async function generate_edge_functions({ builder }) {
 }
 /**
  * @param { object } params
- * @param {import('@sveltejs/kit').Builder} params.builder
+ * @param {Builder2_4_0} params.builder
  * @param { string } params.publish
  * @param { boolean } params.split
  */
@@ -294,8 +305,8 @@ function generate_lambda_functions({ builder, publish, split }) {
 
 			writeFileSync(`.netlify/functions-internal/${name}.mjs`, fn);
 			writeFileSync(`.netlify/functions-internal/${name}.json`, fn_config);
-			if (builder.hasServerInstrumentationFile()) {
-				builder.instrument({
+			if (builder.hasServerInstrumentationFile?.()) {
+				builder.instrument?.({
 					entrypoint: `.netlify/functions-internal/${name}.mjs`,
 					instrumentation: '.netlify/server/instrumentation.server.js',
 					start: `.netlify/functions-start/${name}.start.mjs`,
@@ -318,8 +329,8 @@ function generate_lambda_functions({ builder, publish, split }) {
 
 		writeFileSync(`.netlify/functions-internal/${FUNCTION_PREFIX}render.json`, fn_config);
 		writeFileSync(`.netlify/functions-internal/${FUNCTION_PREFIX}render.mjs`, fn);
-		if (builder.hasServerInstrumentationFile()) {
-			builder.instrument({
+		if (builder.hasServerInstrumentationFile?.()) {
+			builder.instrument?.({
 				entrypoint: `.netlify/functions-internal/${FUNCTION_PREFIX}render.mjs`,
 				instrumentation: '.netlify/server/instrumentation.server.js',
 				start: `.netlify/functions-start/${FUNCTION_PREFIX}render.start.mjs`,
@@ -356,8 +367,8 @@ function get_netlify_config() {
 }
 
 /**
- * @param {NetlifyConfig} netlify_config
- * @param {import('@sveltejs/kit').Builder} builder
+ * @param {NetlifyConfig | null} netlify_config
+ * @param {Builder2_4_0} builder
  **/
 function get_publish_directory(netlify_config, builder) {
 	if (netlify_config) {
diff --git a/packages/adapter-netlify/src/serverless.js b/packages/adapter-netlify/src/serverless.js
@@ -11,8 +11,9 @@ import process from 'node:process';
 export function init(manifest) {
 	const server = new Server(manifest);
 
+	/** @type {Promise<void> | null} */
 	let init_promise = server.init({
-		env: process.env,
+		env: /** @type {Record<string, string>} */ (process.env),
 		read: (file) => createReadableStream(`.netlify/server/${file}`)
 	});
 
@@ -25,7 +26,7 @@ export function init(manifest) {
 		const response = await server.respond(to_request(event), {
 			platform: { context },
 			getClientAddress() {
-				return event.headers['x-nf-client-connection-ip'];
+				return /** @type {string} */ (event.headers['x-nf-client-connection-ip']);
 			}
 		});
 
@@ -56,13 +57,11 @@ export function init(manifest) {
  * @param {import('@netlify/functions').HandlerEvent} event
  * @returns {Request}
  */
-function to_request(event) {
-	const { httpMethod, headers, rawUrl, body, isBase64Encoded } = event;
-
+function to_request({ httpMethod, headers, rawUrl, body, isBase64Encoded }) {
 	/** @type {RequestInit} */
 	const init = {
 		method: httpMethod,
-		headers: new Headers(headers)
+		headers: new Headers(/** @type {Record<string, string>} */ (headers))
 	};
 
 	if (httpMethod !== 'GET' && httpMethod !== 'HEAD') {
diff --git a/packages/adapter-netlify/tsconfig.json b/packages/adapter-netlify/tsconfig.json
@@ -4,6 +4,7 @@
 		"checkJs": true,
 		"noEmit": true,
 		"noImplicitAny": true,
+		"strictNullChecks": true,
 		"target": "es2022",
 		"module": "node16",
 		"moduleResolution": "node16",
diff --git a/packages/adapter-node/index.js b/packages/adapter-node/index.js
@@ -5,6 +5,17 @@ import { nodeResolve } from '@rollup/plugin-node-resolve';
 import commonjs from '@rollup/plugin-commonjs';
 import json from '@rollup/plugin-json';
 
+/**
+ * @template T
+ * @template {keyof T} K
+ * @typedef {Partial<Omit<T, K>> & Required<Pick<T, K>>} PartialExcept
+ */
+
+/**
+ * We use a custom `Builder` type here to support the minimum version of SvelteKit.
+ * @typedef {PartialExcept<import('@sveltejs/kit').Builder, 'log' | 'rimraf' | 'mkdirp' | 'config' | 'prerendered' | 'routes' | 'createEntries' | 'findServerAssets' | 'generateFallback' | 'generateEnvModule' | 'generateManifest' | 'getBuildDirectory' | 'getClientDirectory' | 'getServerDirectory' | 'getAppPath' | 'writeClient' | 'writePrerendered' | 'writePrerendered' | 'writeServer' | 'copy' | 'compress'>} Builder2_4_0
+ */
+
 const files = fileURLToPath(new URL('./files', import.meta.url).href);
 
 /** @type {import('./index.js').default} */
@@ -13,7 +24,7 @@ export default function (opts = {}) {
 
 	return {
 		name: '@sveltejs/adapter-node',
-
+		/** @param {Builder2_4_0} builder */
 		async adapt(builder) {
 			const tmp = builder.getBuildDirectory('adapter-node');
 
@@ -54,7 +65,7 @@ export default function (opts = {}) {
 				manifest: `${tmp}/manifest.js`
 			};
 
-			if (builder.hasServerInstrumentationFile()) {
+			if (builder.hasServerInstrumentationFile?.()) {
 				input['instrumentation.server'] = `${tmp}/instrumentation.server.js`;
 			}
 
@@ -97,8 +108,8 @@ export default function (opts = {}) {
 				}
 			});
 
-			if (builder.hasServerInstrumentationFile()) {
-				builder.instrument({
+			if (builder.hasServerInstrumentationFile?.()) {
+				builder.instrument?.({
 					entrypoint: `${out}/index.js`,
 					instrumentation: `${out}/server/instrumentation.server.js`,
 					module: {
diff --git a/packages/adapter-node/src/handler.js b/packages/adapter-node/src/handler.js
@@ -35,7 +35,7 @@ const dir = path.dirname(fileURLToPath(import.meta.url));
 const asset_dir = `${dir}/client${base}`;
 
 await server.init({
-	env: process.env,
+	env: /** @type {Record<string, string>} */ (process.env),
 	read: (file) => createReadableStream(`${asset_dir}/${file}`)
 });
 
@@ -44,22 +44,24 @@ await server.init({
  * @param {boolean} client
  */
 function serve(path, client = false) {
-	return (
-		fs.existsSync(path) &&
-		sirv(path, {
-			etag: true,
-			gzip: true,
-			brotli: true,
-			setHeaders:
-				client &&
-				((res, pathname) => {
-					// only apply to build directory, not e.g. version.json
-					if (pathname.startsWith(`/${manifest.appPath}/immutable/`) && res.statusCode === 200) {
-						res.setHeader('cache-control', 'public,max-age=31536000,immutable');
-					}
-				})
-		})
-	);
+	return fs.existsSync(path)
+		? sirv(path, {
+				etag: true,
+				gzip: true,
+				brotli: true,
+				setHeaders: client
+					? (res, pathname) => {
+							// only apply to build directory, not e.g. version.json
+							if (
+								pathname.startsWith(`/${manifest.appPath}/immutable/`) &&
+								res.statusCode === 200
+							) {
+								res.setHeader('cache-control', 'public,max-age=31536000,immutable');
+							}
+						}
+					: undefined
+			})
+		: undefined;
 }
 
 // required because the static file server ignores trailing slashes
@@ -77,7 +79,7 @@ function serve_prerendered() {
 		}
 
 		if (prerendered.has(pathname)) {
-			return handler(req, res, next);
+			return handler?.(req, res, next);
 		}
 
 		// remove or add trailing slash as appropriate
@@ -190,5 +192,6 @@ function get_origin(headers) {
 }
 
 export const handler = sequence(
-	[serve(path.join(dir, 'client'), true), serve_prerendered(), ssr].filter(Boolean)
+	/** @type {(import('sirv').RequestHandler | import('polka').Middleware)[]} */
+	([serve(path.join(dir, 'client'), true), serve_prerendered(), ssr].filter(Boolean))
 );
diff --git a/packages/adapter-node/tsconfig.json b/packages/adapter-node/tsconfig.json
@@ -4,6 +4,7 @@
 		"checkJs": true,
 		"noEmit": true,
 		"noImplicitAny": true,
+		"strictNullChecks": true,
 		"allowSyntheticDefaultImports": true,
 		"target": "es2022",
 		"module": "node16",
diff --git a/packages/adapter-static/index.js b/packages/adapter-static/index.js
@@ -5,7 +5,7 @@ import { platforms } from './platforms.js';
 export default function (options) {
 	return {
 		name: '@sveltejs/adapter-static',
-
+		/** @param {import('./internal.js').Builder2_0_0} builder */
 		async adapt(builder) {
 			if (!options?.fallback && builder.config.kit.router?.type !== 'hash') {
 				const dynamic_routes = builder.routes.filter((route) => route.prerender !== true);
diff --git a/packages/adapter-static/internal.d.ts b/packages/adapter-static/internal.d.ts
diff --git a/packages/adapter-static/platforms.js b/packages/adapter-static/platforms.js
diff --git a/packages/adapter-static/tsconfig.json b/packages/adapter-static/tsconfig.json
diff --git a/packages/adapter-vercel/index.js b/packages/adapter-vercel/index.js
diff --git a/packages/adapter-vercel/tsconfig.json b/packages/adapter-vercel/tsconfig.json

Original file line number	Diff line number	Diff line change
`@@ -100,7 +100,7 @@ export default {`
`100`	`100`	`cf: req.cf`
`101`	`101`	`},`
`102`	`102`	`getClientAddress() {`
`103`		`- return req.headers.get('cf-connecting-ip');`
	`103`	`+ return /** @type {string} */ (req.headers.get('cf-connecting-ip'));`
`104`	`104`	`}`
`105`	`105`	`});`
`106`	`106`	`}`