feat: enable prebundling by default

.changeset/calm-rules-push.md

@@ -0,0 +1,7 @@
+---
+'@sveltejs/vite-plugin-svelte': minor
+---
+
+enable `prebundleSvelteLibraries` by default to improve page loading for the dev server.
+
+see the [FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies) for more information about `prebundleSvelteLibraries` and how to tune it.

docs/config.md

@@ -204,9 +204,13 @@ A [picomatch pattern](https://github.com/micromatch/picomatch), or array of patt
 ### prebundleSvelteLibraries
 
 - **Type:** `boolean`
-- **Default:** `false`
+- **Default:** `true`
+
+  Enable [Vite's dependency prebundling](https://vitejs.dev/guide/dep-pre-bundling.html) for Svelte libraries.
+
+  This option improves page loading for the dev server in most applications when using Svelte component libraries.
 
-  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.
+  See the [FAQ](./faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies) for details and how to fine-tune it for huge libraries.
 
 ## Experimental options
 

docs/faq.md

@@ -99,4 +99,76 @@ 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. 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.
+Prebundling dependencies is an [optimization in Vite](https://vitejs.dev/guide/dep-pre-bundling.html).
+
+> We only use prebundling during **development**, the following does not apply to or describe the built application
+
+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 ES modules, it also reduces the number of http requests when you load a page from the dev server and caches files so subsequent starts are even faster.
+
+The way prebundling Svelte libraries affects your dev-server load times depends on the import style you use, index or deep:
+
+#### index imports
+
+offers better DX but can cause noticable delays on your machine, esp. for libraries with many files.
+
+```diff
+import {SomeComponent} from 'some-library'
++ only one request per library
++ intellisense for the whole library after first import
+- compiles the whole library even if you only use a few components
+- slower build and dev-server ssr
+```
+
+#### deep imports
+
+offers snappier dev and faster builds for libraries with many files at the expense of some DX
+
+```diff
+import SomeComponent from 'some-library/src/SomeComponent.svelte'
++ compiles only the components you import
++ faster build and dev-server ssr
+- one request per import can slow down initial load if you use a lot of components
+- intellisense only for imported components
+```
+
+#### a word on import (re-)writing with plugins or preprocessors (auto-import, optimizeImports etc)
+
+**Do not use them in combination with prebundling!**
+
+Prebundling works by reading your .svelte files from disk. scanning them for imports. It cannot detect
+added/changed/removed imports and these then cause extra requests, delays and render the prebundled files from the initial scan moot.
+If you prefer to use these tools, please exclude the libraries you use them with from prebundling.
+
+#### excluding libraries from prebundling
+
+If you want to disable prebundling for a single library, use optimizeDeps.exclude
+
+```js
+// vite.config.js
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['some-library'] // do not pre-bundle some-library
+  }
+});
+```
+
+Or disable it for all Svelte libraries
+
+```js
+// svelte.config.js
+export default {
+  vitePlugin: {
+    prebundleSvelteLibraries: false
+  }
+};
+```
+
+#### recommendations
+
+There is no golden rule, but you can follow these recommendations:
+
+1. **Never** combine auto-import or optimizeImports with prebundling
+2. Start with index imports and if your dev-server or build process feels slow, check compile stats to see if switching to deep imports can improve the experience.
+3. Do not mix deep and index imports for the same library, use one style consistently.
+4. Use different import styles for different libraries where it helps. E.g. deep imports for the few icons of that one huge icon library, but index import for the component library that is heavily used.

packages/e2e-tests/package-json-svelte-field/__tests__/package-json-svelte-field.spec.ts

@@ -1,18 +1,5 @@
-import { getText, isBuild, readVitePrebundleMetadata } from '~utils';
+import { getText } from '~utils';
 
 test('should render component imported via svelte field in package.json', async () => {
 	expect(await getText('#test-id')).toBe('svelte field works');
 });
-
-if (!isBuild) {
-	test('should optimize nested cjs deps of excluded svelte deps', () => {
-		const metadataFile = readVitePrebundleMetadata();
-		const metadata = JSON.parse(metadataFile);
-		const optimizedPaths = Object.keys(metadata.optimized);
-		expect(optimizedPaths).not.toContain('e2e-test-dep-svelte-nested');
-		expect(optimizedPaths).not.toContain('e2e-test-dep-svelte-simple');
-		expect(optimizedPaths).toContain(
-			'e2e-test-dep-svelte-nested > e2e-test-dep-svelte-simple > e2e-test-dep-cjs-only'
-		);
-	});
-}

packages/e2e-tests/package-json-svelte-field/vite.config.js

@@ -4,6 +4,9 @@ import { defineConfig } from 'vite';
 export default defineConfig(({ command, mode }) => {
 	return {
 		plugins: [svelte()],
+		optimizeDeps: {
+			exclude: ['e2e-test-dep-scss-only']
+		},
 		build: {
 			// make build faster by skipping transforms and minification
 			target: 'esnext',

packages/e2e-tests/prebundle-svelte-deps/__tests__/prebundle-svelte-deps.spec.ts

@@ -1,29 +1,27 @@
-import { browserLogs, getText, isBuild, readVitePrebundleMetadata } from '~utils';
+import {
+	browserLogs,
+	editFile,
+	getText,
+	isBuild,
+	readVitePrebundleMetadata,
+	waitForServerRestartAndReloadPage
+} from '~utils';
 
-test('should not have failed requests', async () => {
+async function expectPageToWork() {
 	browserLogs.forEach((msg) => {
 		expect(msg).not.toMatch('404');
 	});
-});
-
-test('should render Hybrid import', async () => {
 	expect(await getText('#hybrid .label')).toBe('dependency-import');
-});
-
-test('should render Simple import', async () => {
 	expect(await getText('#hybrid .label')).toBe('dependency-import');
-});
-
-test('should render Nested import', async () => {
 	expect(await getText('#nested #message')).toBe('nested');
 	expect(await getText('#nested #cjs-and-esm')).toBe('esm');
-});
-
-test('should render api-only import', async () => {
 	expect(await getText('#api-only')).toBe('api loaded: true');
-});
+}
 
 if (!isBuild) {
+	test('page works with pre-bundling enabled', async () => {
+		await expectPageToWork();
+	});
 	test('should optimize svelte dependencies', () => {
 		const metadataFile = readVitePrebundleMetadata();
 		const metadata = JSON.parse(metadataFile);
@@ -39,4 +37,30 @@ if (!isBuild) {
 		const optimizedPaths = Object.keys(metadata.optimized);
 		expect(optimizedPaths).not.toContain('e2e-test-dep-scss-only');
 	});
+
+	test('page works with pre-bundling disabled', async () => {
+		editFile('svelte.config.js', (c) =>
+			c.replace('prebundleSvelteLibraries: true', 'prebundleSvelteLibraries: false')
+		);
+		await waitForServerRestartAndReloadPage();
+		await expectPageToWork();
+		const metadataFile = readVitePrebundleMetadata();
+		const metadata = JSON.parse(metadataFile);
+		const optimizedPaths = Object.keys(metadata.optimized);
+		expect(optimizedPaths).not.toContain('e2e-test-dep-svelte-simple');
+		expect(optimizedPaths).not.toContain('e2e-test-dep-svelte-hybrid');
+
+		// this is a bit surprising, we always include js-libraries using svelte
+		expect(optimizedPaths).toContain('e2e-test-dep-svelte-api-only');
+
+		expect(optimizedPaths).toContain('e2e-test-dep-svelte-hybrid > e2e-test-dep-cjs-only');
+		expect(optimizedPaths).toContain('e2e-test-dep-svelte-simple > e2e-test-dep-cjs-only');
+		expect(optimizedPaths).toContain(
+			'e2e-test-dep-svelte-nested > e2e-test-dep-svelte-simple > e2e-test-dep-cjs-only'
+		);
+	});
+} else {
+	test('page works', async () => {
+		await expectPageToWork();
+	});
 }

packages/e2e-tests/prebundle-svelte-deps/vite.config.js

@@ -13,5 +13,13 @@ export default defineConfig({
 		// make build faster by skipping transforms and minification
 		target: 'esnext',
 		minify: false
+	},
+	server: {
+		watch: {
+			// During tests we edit the files too fast and sometimes chokidar
+			// misses change events, so enforce polling for consistency
+			usePolling: true,
+			interval: 100
+		}
 	}
 });

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

@@ -131,7 +131,8 @@ export async function preResolveOptions(
 	};
 	const defaultOptions: Partial<Options> = {
 		extensions: ['.svelte'],
-		emitCss: true
+		emitCss: true,
+		prebundleSvelteLibraries: true
 	};
 	const svelteConfig = convertPluginOptions(
 		await loadSvelteConfig(viteConfigWithResolvedRoot, inlineOptions)
@@ -368,6 +369,8 @@ export async function buildExtraViteConfig(
 	if (options.prebundleSvelteLibraries) {
 		extraViteConfig.optimizeDeps = {
 			...extraViteConfig.optimizeDeps,
+			// only prebundle for dev, build isn't working with vite-plugin-svelte
+			disabled: 'build',
 			// Experimental Vite API to allow these extensions to be scanned and prebundled
 			// @ts-ignore
 			extensions: options.extensions ?? ['.svelte'],
@@ -378,6 +381,10 @@ export async function buildExtraViteConfig(
 				plugins: [{ name: facadeEsbuildSveltePluginName, setup: () => {} }]
 			}
 		};
+		extraViteConfig.ssr.optimizeDeps = {
+			// do not prebundle for ssr, not working with vite-plugin-svelte
+			disabled: true
+		};
 	}
 
 	// enable hmrPartialAccept if not explicitly disabled
@@ -551,9 +558,11 @@ export interface PluginOptions {
 	disableDependencyReinclusion?: boolean | string[];
 
 	/**
-	 * Force Vite to pre-bundle Svelte libraries
+	 * Enable support for Vite's dependency optimization to prebundle Svelte libraries
 	 *
-	 * @default false
+	 * to disable prebundling for a specific library, add it to `optimizeDeps.exclude`.
+	 *
+	 * @default true
 	 */
 	prebundleSvelteLibraries?: boolean;