feat: enable prebundling by default

.changeset/calm-rules-push.md

@@ -0,0 +1,14 @@
+---
+'@sveltejs/vite-plugin-svelte': minor
+---
+
+enable `prebundleSvelteLibraries` by default to improve page loading for the dev server.
+
+If you are using deep imports for svelte libraries that are now prebundled, update your imports to use the package index instead.
+
+```diff
+- import SomeComponent from 'some-library/src/SomeComponent.svelte'
++ import {SomeComponent} from 'some-library'
+```
+
+see [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 support for Vite optimizeDeps to pre-bundle 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,39 @@ 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.
+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.
+
+For prebundled svelte libraries it is recommended that you do not use deep imports.
+
+```diff
+- import SomeComponent from 'some-library/src/SomeComponent.svelte'
++ import {SomeComponent} from 'some-library'
+```
+
+For huge libraries where you only import a few components this can lead to slower first start, as all components have to be compiled once, even if you never use them.
+It also slows down re-prebundling, which can happen when vite discovers new dependencies or you change your svelte config.
+
+In that case, add these huge libraries to optimizeDeps.exclude and use deep imports to import the components you need.
+
+e.g.
+
+```js
+// vite.config.js
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['svelte-2000-icons'] // do not pre-bundle svelte-2000-icons
+  }
+});
+```
+
+```html
+<!-- src/.../SomeSvelte.svelte -->
+<script>
+  // use deep import to avoid loading all components of svelte-2000-icons in the browser
+  import OneIcon from 'svelte-2000-icons/src/icons/OneIcon.svelte';
+</script>
+<OneIcon />
+```

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)
@@ -551,9 +552,11 @@ export interface PluginOptions {
 	disableDependencyReinclusion?: boolean | string[];
 
 	/**
-	 * Force Vite to pre-bundle Svelte libraries
+	 * Enable support for vite optimizeDeps to pre-bundle Svelte libraries
 	 *
-	 * @default false
+	 * to disable pre-bundling for a specific library, add it to optimizeDeps.exclude.
+	 *
+	 * @default true
 	 */
 	prebundleSvelteLibraries?: boolean;