Svelte 5: Hydration fails when SvelteKit app is run as a dependency

[samlfair]

Describe the bug

I have a SvelteKit application with Svelte 5, which runs as an npm dependency. The project runs fine on its own:

https://stackblitz.com/~/github.com/samlfair/svelte-dependency

It also runs fine with csr disabled. However, if I try to run it as an npm dependency with csr enabled, hydration fails and the page breaks:

https://stackblitz.com/edit/node-kortck?file=package.json

I see this error:

chunk-JTKFLJAK.js?v=ce2151a9:1507 ERR_SVELTE_HYDRATION_MISMATCH: Hydration failed because the initial UI does not match what was rendered on the server. Error: onMount can only be used during component initialisation.
    at onMount (svelte.js?v=2ff9db38:405:11)
    at Root (root.svelte:28:2)
    at Object.fn (hmr.js?v=ce2151a9:31:29)
    at execute_reaction_fn (runtime.js?v=ce2151a9:257:20)
    at execute_effect (runtime.js?v=ce2151a9:421:18)
    at create_effect (effects.js?v=ce2151a9:83:4)
    at branch (effects.js?v=ce2151a9:244:9)
    at Object.fn (hmr.js?v=ce2151a9:29:13)
    at execute_reaction_fn (runtime.js?v=ce2151a9:257:20)
    at execute_effect (runtime.js?v=ce2151a9:421:18)
hydrate @ chunk-JTKFLJAK.js?v=ce2151a9:1507
Show 1 more frame
Show less
svelte.js?v=2ff9db38:405 Uncaught (in promise) Error: onMount can only be used during component initialisation.
    at onMount (svelte.js?v=2ff9db38:405:11)
    at Root (root.svelte:28:2)
    at Object.fn (hmr.js?v=ce2151a9:31:29)
    at execute_reaction_fn (runtime.js?v=ce2151a9:257:20)
    at execute_effect (runtime.js?v=ce2151a9:421:18)
    at create_effect (effects.js?v=ce2151a9:83:4)
    at branch (effects.js?v=ce2151a9:244:9)
    at Object.fn (hmr.js?v=ce2151a9:29:13)
    at execute_reaction_fn (runtime.js?v=ce2151a9:257:20)
    at execute_effect (runtime.js?v=ce2151a9:421:18)

In one case, it also shows this error:

SyntaxError: The requested module '/@fs/Users/samlittlefair/Documents/asides/svelte-test-consumer/node_modules/debug/src/browser.js?v=ce2151a9' does not provide an export named 'default' (at create-tokenizer.js?v=ce2151a9:31:8)

But, as far as I can tell, the export should work fine.

Reproduction

Dependency:

https://stackblitz.com/~/github.com/samlfair/svelte-dependency

Consumer:

https://stackblitz.com/edit/node-kortck?file=package.json

Logs

chunk-JTKFLJAK.js?v=ce2151a9:1507 ERR_SVELTE_HYDRATION_MISMATCH: Hydration failed because the initial UI does not match what was rendered on the server. Error: onMount can only be used during component initialisation.
    at onMount (svelte.js?v=2ff9db38:405:11)
    at Root (root.svelte:28:2)
    at Object.fn (hmr.js?v=ce2151a9:31:29)
    at execute_reaction_fn (runtime.js?v=ce2151a9:257:20)
    at execute_effect (runtime.js?v=ce2151a9:421:18)
    at create_effect (effects.js?v=ce2151a9:83:4)
    at branch (effects.js?v=ce2151a9:244:9)
    at Object.fn (hmr.js?v=ce2151a9:29:13)
    at execute_reaction_fn (runtime.js?v=ce2151a9:257:20)
    at execute_effect (runtime.js?v=ce2151a9:421:18)
hydrate @ chunk-JTKFLJAK.js?v=ce2151a9:1507
Show 1 more frame
Show less
svelte.js?v=2ff9db38:405 Uncaught (in promise) Error: onMount can only be used during component initialisation.
    at onMount (svelte.js?v=2ff9db38:405:11)
    at Root (root.svelte:28:2)
    at Object.fn (hmr.js?v=ce2151a9:31:29)
    at execute_reaction_fn (runtime.js?v=ce2151a9:257:20)
    at execute_effect (runtime.js?v=ce2151a9:421:18)
    at create_effect (effects.js?v=ce2151a9:83:4)
    at branch (effects.js?v=ce2151a9:244:9)
    at Object.fn (hmr.js?v=ce2151a9:29:13)
    at execute_reaction_fn (runtime.js?v=ce2151a9:257:20)
    at execute_effect (runtime.js?v=ce2151a9:421:18)

System Info

Operating system: OS X 10.15.7
Browser: Chrome 123

Problem also occurs in Safari

Severity

blocking all usage of svelte

[dummdidumm]

The error happens because there are two copies of the Svelte runtime in your app when running the application like this. To keep this from happening, add

	optimizeDeps: {
		exclude: ['svelte']
	},

to the Vite config of your package.

It still doesn't fully work because some package seems to be resolved incorrectly, but that is unrelated to Svelte.

In general it's not recommended to run an application indirectly from inside node_modules like this due to the pitfalls this approach has.

[samlfair]

@dummdidumm You're right! It looks like these were all Vite dependency issues.

In general it's not recommended to run an application indirectly from inside node_modules like this

Can I ask more about this? This seems like a common use-case for developer tools. Is there another approach recommended for developers who want to serve a localhost UI for a package?

[dummdidumm]

I honestly haven't heard of the use case of running a localhost UI for a package before. What I know is that people put their docs/playground/whatever on an internet site, and when people want to know about the package they go there but not start up some local UI.

[samlfair]

As a follow-up:

If a library author creates documentation using src/routes in a SvelteKit project, what is the recommended way to run the documentation? As per: https://kit.svelte.dev/docs/packaging

I would assume that you might write a bin script to launch the SvelteKit server, but it seems like that won't work. Instead, is it recommended that the library user should download the codebase to run it? Or is it just assumed that src/routes will be used to build a website for the library?

[dummdidumm]

Yes, the assumption is that you build a website/showcase/playground/whatever you like from src/routes and host that on the internet. It's not intended to be shipped alongside your package.

[samlfair]

That's clear. Thanks for responding!