feat: bring prebundleSvelteLibraries out of experimental (#476)

Co-authored-by: bluwy <bjornlu.dev@gmail.com>

.changeset/twelve-islands-jump.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/vite-plugin-svelte': minor
+---
+
+Bring `prebundleSvelteLibraries` out of experimental, it is now a top-level option

docs/config.md

@@ -201,6 +201,13 @@ A [picomatch pattern](https://github.com/micromatch/picomatch), or array of patt
 
   > This is currently required for hybrid packages like Routify, that export both Node and browser code.
 
+### prebundleSvelteLibraries
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+  Force Vite to pre-bundle Svelte libraries. Setting this `true` should improve initial page load performance, especially when using large Svelte libraries. See the [FAQ](./faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies) for details of the pre-bundling implementation.
+
 ## Experimental options
 
 These options are considered experimental and breaking changes to them can occur in any release! Specify them under the `experimental` option.
@@ -240,13 +247,6 @@ export default {
 
   Use extra preprocessors that delegate style and TypeScript preprocessing to native Vite plugins. TypeScript will be transformed with esbuild. Styles will be transformed using [Vite's CSS plugin](https://vitejs.dev/guide/features.html#css), which handles `@imports`, `url()` references, PostCSS, CSS Modules, and `.scss`/`.sass`/`.less`/`.styl`/`.stylus` files. Do not use together with TypeScript or style preprocessors from `svelte-preprocess` as attempts to transform the content twice will fail!
 
-### prebundleSvelteLibraries
-
-- **Type:** `boolean`
-- **Default:** `false`
-
-  Force Vite to pre-bundle Svelte libraries. Setting this `true` should improve initial page load performance, especially when using large Svelte libraries. See the [FAQ](./faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies) for details of the pre-bundling implementation.
-
 ### generateMissingPreprocessorSourcemaps
 
 - **Type:** `boolean`

docs/faq.md

@@ -99,10 +99,4 @@ For reference, check out [windicss](https://github.com/windicss/vite-plugin-wind
 
 ### What is going on with Vite and `Pre-bundling dependencies:`?
 
-Pre-bundling dependencies is an [optimization in Vite](https://vitejs.dev/guide/dep-pre-bundling.html). It is required for CJS dependencies, as Vite's development server only works with ES modules on the client side.
-
-Historically, Svelte components had issues being pre-bundled, causing [deduplication issues](https://github.com/vitejs/vite/issues/3910) and [CJS interoperability issues](https://github.com/vitejs/vite/issues/3024). Since Vite 2.5.2, [a new API in Vite](https://github.com/vitejs/vite/pull/4634) allowed us to [automatically handle Svelte library pre-bundling](https://github.com/sveltejs/vite-plugin-svelte/pull/157) for you.
-
-This feature had served us well, however a caveat remained that large Svelte component libraries often slows down the initial page load. If this affects you, try setting [experimental.prebundleSvelteLibraries](./config.md#prebundleSvelteLibraries) option to `true` to speed things up.
-
-In case you still run into errors like `The requested module 'xxx' does not provide an export named 'yyy'`, please check our [open issues](https://github.com/sveltejs/vite-plugin-svelte/issues).
+Pre-bundling dependencies is an [optimization in Vite](https://vitejs.dev/guide/dep-pre-bundling.html). It is required for CJS dependencies, as Vite's development server only works with ES modules on the client side. Importantly for Svelte libraries and ESM modules, prebundling combines component libraries into a single file to speed up the initial page load. Try setting the [`prebundleSvelteLibraries`](./config.md#prebundleSvelteLibraries) option to `true` to speed things up. This will likely be enabled by default in future version of the plugin.

packages/vite-plugin-svelte/src/index.ts

@@ -85,7 +85,7 @@ export function svelte(inlineOptions?: Partial<Options>): Plugin[] {
 			},
 
 			async buildStart() {
-				if (!options.experimental?.prebundleSvelteLibraries) return;
+				if (!options.prebundleSvelteLibraries) return;
 				const isSvelteMetadataChanged = await saveSvelteMetadata(viteConfig.cacheDir, options);
 				if (isSvelteMetadataChanged) {
 					// Force Vite to optimize again. Although we mutate the config here, it works because

packages/vite-plugin-svelte/src/utils/options.ts

@@ -34,6 +34,7 @@ const allowedPluginOptions = new Set([
 	'hot',
 	'ignorePluginPreprocessors',
 	'disableDependencyReinclusion',
+	'prebundleSvelteLibraries',
 	'experimental'
 ]);
 
@@ -188,6 +189,7 @@ export function resolveOptions(
 	const merged = mergeConfigs<ResolvedOptions>(defaultOptions, preResolveOptions, extraOptions);
 
 	removeIgnoredOptions(merged);
+	handleDeprecatedOptions(merged);
 	addSvelteKitOptions(merged);
 	addExtraPreprocessors(merged, viteConfig);
 	enforceOptionsForHmr(merged);
@@ -288,6 +290,15 @@ function addSvelteKitOptions(options: ResolvedOptions) {
 	}
 }
 
+function handleDeprecatedOptions(options: ResolvedOptions) {
+	if ((options.experimental as any)?.prebundleSvelteLibraries) {
+		options.prebundleSvelteLibraries = (options.experimental as any)?.prebundleSvelteLibraries;
+		log.warn(
+			'experimental.prebundleSvelteLibraries is no longer experimental and has moved to prebundleSvelteLibraries'
+		);
+	}
+}
+
 // vite passes unresolved `root`option to config hook but we need the resolved value, so do it here
 // https://github.com/sveltejs/vite-plugin-svelte/issues/113
 // https://github.com/vitejs/vite/blob/43c957de8a99bb326afd732c962f42127b0a4d1e/packages/vite/src/node/config.ts#L293
@@ -318,7 +329,7 @@ export function buildExtraViteConfig(
 		config.optimizeDeps
 	);
 
-	if (options.experimental?.prebundleSvelteLibraries) {
+	if (options.prebundleSvelteLibraries) {
 		extraViteConfig.optimizeDeps = {
 			...extraViteConfig.optimizeDeps,
 			// Experimental Vite API to allow these extensions to be scanned and prebundled
@@ -378,7 +389,7 @@ function buildOptimizeDepsForSvelte(
 	}
 
 	// If we prebundle svelte libraries, we can skip the whole prebundling dance below
-	if (options.experimental?.prebundleSvelteLibraries) {
+	if (options.prebundleSvelteLibraries) {
 		return { include, exclude };
 	}
 
@@ -540,6 +551,13 @@ export interface PluginOptions {
 	 */
 	disableDependencyReinclusion?: boolean | string[];
 
+	/**
+	 * Force Vite to pre-bundle Svelte libraries
+	 *
+	 * @default false
+	 */
+	prebundleSvelteLibraries?: boolean;
+
 	/**
 	 * These options are considered experimental and breaking changes to them can occur in any release
 	 */
@@ -594,13 +612,6 @@ export interface ExperimentalOptions {
 	 */
 	useVitePreprocess?: boolean;
 
-	/**
-	 * Force Vite to pre-bundle Svelte libraries
-	 *
-	 * @default false
-	 */
-	prebundleSvelteLibraries?: boolean;
-
 	/**
 	 * If a preprocessor does not provide a sourcemap, a best-effort fallback sourcemap will be provided.
 	 * This option requires `diff-match-patch` to be installed as a peer dependency.