fix: add `experimental.forkPreloads` flag (#15135)

* feat: add `experimental.enhancedPreloading` flag

Adds a new experimental flag to gate the use of Svelte's `fork` API for
preloading. The flag defaults to `false`, disabling the fork-based
preloading behavior until explicitly enabled.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* changeste

* chore: rename `enhancedPreloading` to `forkPreloads`

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

diff --git a/.changeset/tame-lights-push.md b/.changeset/tame-lights-push.md
new file mode 100644 (file)
index 0000000..1e80ae0
--- /dev/null
+++ b/.changeset/tame-lights-push.md
@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+fix: put forking behind `experimental.forkPreloads`

diff --git a/packages/kit/src/core/config/index.spec.js b/packages/kit/src/core/config/index.spec.js
index 3e923935059ea8ca19c8af59a70fd321beec3281..14ac3361701b6beec502016ca8df688e55eaecd0 100644 (file)
--- a/packages/kit/src/core/config/index.spec.js
+++ b/packages/kit/src/core/config/index.spec.js
@@ -80,7 +80,8 @@ const get_defaults = (prefix = '') => ({
                experimental: {
                        tracing: { server: false },
                        instrumentation: { server: false },
-                       remoteFunctions: false
+                       remoteFunctions: false,
+                       forkPreloads: false
                },
                files: {
                        src: join(prefix, 'src'),
@@ -479,6 +480,30 @@ test('errors on invalid tracing values', () => {
        }, /^config\.kit\.experimental\.tracing\.server should be true or false, if specified$/);
 });
 
+test('errors on invalid forkPreloads values', () => {
+       assert.throws(() => {
+               validate_config({
+                       kit: {
+                               experimental: {
+                                       // @ts-expect-error - given value expected to throw
+                                       forkPreloads: 'true'
+                               }
+                       }
+               });
+       }, /^config\.kit\.experimental\.forkPreloads should be true or false, if specified$/);
+
+       assert.throws(() => {
+               validate_config({
+                       kit: {
+                               experimental: {
+                                       // @ts-expect-error - given value expected to throw
+                                       forkPreloads: 1
+                               }
+                       }
+               });
+       }, /^config\.kit\.experimental\.forkPreloads should be true or false, if specified$/);
+});
+
 test('uses src prefix for other kit.files options', async () => {
        const cwd = join(__dirname, 'fixtures/custom-src');
 

diff --git a/packages/kit/src/core/config/options.js b/packages/kit/src/core/config/options.js
index 0d7d7fc5b3b6d761adda2ab47fc07cf9d2e27168..d16ba425358283272d551ea47e71a36a368d17b6 100644 (file)
--- a/packages/kit/src/core/config/options.js
+++ b/packages/kit/src/core/config/options.js
@@ -132,7 +132,8 @@ const options = object(
                                instrumentation: object({
                                        server: boolean(false)
                                }),
-                               remoteFunctions: boolean(false)
+                               remoteFunctions: boolean(false),
+                               forkPreloads: boolean(false)
                        }),
 
                        files: object({

diff --git a/packages/kit/src/exports/public.d.ts b/packages/kit/src/exports/public.d.ts
index 45f0ad4af3c237f4c2f91ebb6f701aceb97afebe..5aa821429dbef2178326cc2e6789661d3d56de3a 100644 (file)
--- a/packages/kit/src/exports/public.d.ts
+++ b/packages/kit/src/exports/public.d.ts
@@ -505,6 +505,12 @@ export interface KitConfig {
                 * @default false
                 */
                remoteFunctions?: boolean;
+
+               /**
+                * Whether to enable the experimental forked preloading feature using Svelte's fork API.
+                * @default false
+                */
+               forkPreloads?: boolean;
        };
        /**
         * Where to find various files within your project.

diff --git a/packages/kit/src/exports/vite/index.js b/packages/kit/src/exports/vite/index.js
index 68e5e90a4243f8b48e088205f00ee706ee2cc1ad..220942a4aba4c8e6b3c43925a2f63beef6fca2ff 100644 (file)
--- a/packages/kit/src/exports/vite/index.js
+++ b/packages/kit/src/exports/vite/index.js
@@ -346,6 +346,7 @@ async function kit({ svelte_config }) {
                                __SVELTEKIT_APP_DIR__: s(kit.appDir),
                                __SVELTEKIT_EMBEDDED__: s(kit.embedded),
                                __SVELTEKIT_EXPERIMENTAL__REMOTE_FUNCTIONS__: s(kit.experimental.remoteFunctions),
+                               __SVELTEKIT_FORK_PRELOADS__: s(kit.experimental.forkPreloads),
                                __SVELTEKIT_PATHS_ASSETS__: s(kit.paths.assets),
                                __SVELTEKIT_PATHS_BASE__: s(kit.paths.base),
                                __SVELTEKIT_PATHS_RELATIVE__: s(kit.paths.relative),

diff --git a/packages/kit/src/runtime/client/client.js b/packages/kit/src/runtime/client/client.js
index f8d987693ce2314ca3f592593d93a21eb84f47be..ddf2efb2ca60b98da1a4e9224084854aae522f70 100644 (file)
--- a/packages/kit/src/runtime/client/client.js
+++ b/packages/kit/src/runtime/client/client.js
@@ -532,7 +532,7 @@ async function _preload_data(intent) {
                        fork: null
                };
 
-               if (svelte.fork) {
+               if (__SVELTEKIT_FORK_PRELOADS__ && svelte.fork) {
                        const lc = load_cache;
 
                        lc.fork = lc.promise.then((result) => {
@@ -545,7 +545,7 @@ async function _preload_data(intent) {
                                                        update(result.props.page);
                                                });
                                        } catch {
-                                               // if it errors, it's because the experimental flag isn't enabled
+                                               // if it errors, it's because the experimental flag isn't enabled in Svelte
                                        }
                                }
 

diff --git a/packages/kit/src/types/global-private.d.ts b/packages/kit/src/types/global-private.d.ts
index 47c78935ba23080318dd575efcab6bc90930d351..94a63ea2e010fb56d5c4a676da2795023a2e095f 100644 (file)
--- a/packages/kit/src/types/global-private.d.ts
+++ b/packages/kit/src/types/global-private.d.ts
@@ -11,6 +11,8 @@ declare global {
        const __SVELTEKIT_SERVER_TRACING_ENABLED__: boolean;
        /** true if corresponding config option is set to true */
        const __SVELTEKIT_EXPERIMENTAL__REMOTE_FUNCTIONS__: boolean;
+       /** True if `config.kit.experimental.forkPreloads` is `true` */
+       const __SVELTEKIT_FORK_PRELOADS__: boolean;
        /** True if `config.kit.router.resolution === 'client'` */
        const __SVELTEKIT_CLIENT_ROUTING__: boolean;
        /** True if `config.kit.router.type === 'hash'` */

diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts
index 7c74c8990c934148e7c710e3467457bb13553c2f..0cd1dc26a3e81910880e13680e213266bb5be10e 100644 (file)
--- a/packages/kit/types/index.d.ts
+++ b/packages/kit/types/index.d.ts
@@ -481,6 +481,12 @@ declare module '@sveltejs/kit' {
                         * @default false
                         */
                        remoteFunctions?: boolean;
+
+                       /**
+                        * Whether to enable the experimental forked preloading feature using Svelte's fork API.
+                        * @default false
+                        */
+                       forkPreloads?: boolean;
                };
                /**
                 * Where to find various files within your project.