chore: deprecate html in favour of body for render() (#11927)

trueadm · web-flow · commit 7714c934fe66 · 2024-06-06T12:28:40.000+02:00
Closes #11281
diff --git a/.changeset/hot-sloths-clap.md b/.changeset/hot-sloths-clap.md
@@ -0,0 +1,5 @@
+---
+"svelte": patch
+---
+
+chore: deprecate html in favour of body for render()
diff --git a/packages/svelte/src/internal/server/index.js b/packages/svelte/src/internal/server/index.js
@@ -13,13 +13,6 @@ import { current_component, pop, push } from './context.js';
 import { BLOCK_CLOSE, BLOCK_OPEN } from './hydration.js';
 import { validate_store } from '../shared/validate.js';
 
-/**
- * @typedef {{
- * 	head: string;
- * 	html: string;
- * }} RenderOutput
- */
-
 // https://html.spec.whatwg.org/multipage/syntax.html#attributes-2
 // https://infra.spec.whatwg.org/#noncharacter
 const INVALID_ATTR_NAME_CHAR_REGEX =
@@ -105,7 +98,7 @@ export let on_destroy = [];
 /**
  * @param {typeof import('svelte').SvelteComponent} component
  * @param {{ props: Record<string, any>; context?: Map<any, any> }} options
- * @returns {RenderOutput}
+ * @returns {import('#server').RenderOutput}
  */
 export function render(component, options) {
 	const payload = create_payload();
@@ -132,7 +125,8 @@ export function render(component, options) {
 
 	return {
 		head: payload.head.out || payload.head.title ? payload.head.out + payload.head.title : '',
-		html: payload.out
+		html: payload.out,
+		body: payload.out
 	};
 }
 
diff --git a/packages/svelte/src/internal/server/types.d.ts b/packages/svelte/src/internal/server/types.d.ts
@@ -20,3 +20,12 @@ export interface Payload {
 		anchor: number;
 	};
 }
+
+export interface RenderOutput {
+	/** HTML that goes into the `<head>` */
+	head: string;
+	/** @deprecated use `body` instead */
+	html: string;
+	/** HTML that goes somewhere into the `<body>` */
+	body: string;
+}
diff --git a/packages/svelte/src/legacy/legacy-server.js b/packages/svelte/src/legacy/legacy-server.js
@@ -27,7 +27,7 @@ export function asClassComponent(component) {
 		return {
 			css: { code: '', map: null },
 			head: result.head,
-			html: result.html
+			html: result.body
 		};
 	};
 	// @ts-expect-error this is present for SSR
diff --git a/packages/svelte/tests/runtime-browser/test-ssr.ts b/packages/svelte/tests/runtime-browser/test-ssr.ts
@@ -20,16 +20,16 @@ export async function run_ssr_test(
 		await compile_directory(test_dir, 'server', config.compileOptions);
 
 		const Component = (await import(`${test_dir}/_output/server/main.svelte.js`)).default;
-		const { html } = render(Component, { props: config.props || {} });
+		const { body } = render(Component, { props: config.props || {} });
 
-		fs.writeFileSync(`${test_dir}/_output/rendered.html`, html);
+		fs.writeFileSync(`${test_dir}/_output/rendered.html`, body);
 
 		if (config.ssrHtml) {
-			assert_html_equal_with_options(html, config.ssrHtml, {
+			assert_html_equal_with_options(body, config.ssrHtml, {
 				preserveComments: config.compileOptions?.preserveComments
 			});
 		} else if (config.html) {
-			assert_html_equal_with_options(html, config.html, {
+			assert_html_equal_with_options(body, config.html, {
 				preserveComments: config.compileOptions?.preserveComments
 			});
 		}
diff --git a/packages/svelte/tests/server-side-rendering/test.ts b/packages/svelte/tests/server-side-rendering/test.ts
@@ -23,18 +23,18 @@ const { test, run } = suite<SSRTest>(async (config, test_dir) => {
 	const Component = (await import(`${test_dir}/_output/server/main.svelte.js`)).default;
 	const expected_html = try_read_file(`${test_dir}/_expected.html`);
 	const rendered = render(Component, { props: config.props || {} });
-	const { html, head } = rendered;
+	const { body, head } = rendered;
 
-	fs.writeFileSync(`${test_dir}/_actual.html`, html);
+	fs.writeFileSync(`${test_dir}/_actual.html`, body);
 
 	try {
-		assert_html_equal_with_options(html, expected_html || '', {
+		assert_html_equal_with_options(body, expected_html || '', {
 			preserveComments: config.compileOptions?.preserveComments,
 			withoutNormalizeHtml: config.withoutNormalizeHtml
 		});
 	} catch (error: any) {
 		if (should_update_expected()) {
-			fs.writeFileSync(`${test_dir}/_expected.html`, html);
+			fs.writeFileSync(`${test_dir}/_expected.html`, body);
 			console.log(`Updated ${test_dir}/_expected.html.`);
 		} else {
 			error.message += '\n' + `${test_dir}/main.svelte`;
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
@@ -2112,10 +2112,14 @@ declare module 'svelte/server' {
 		props: Record<string, any>;
 		context?: Map<any, any>;
 	}): RenderOutput;
-	type RenderOutput = {
+	interface RenderOutput {
+		/** HTML that goes into the `<head>` */
 		head: string;
+		/** @deprecated use `body` instead */
 		html: string;
-	};
+		/** HTML that goes somewhere into the `<body>` */
+		body: string;
+	}
 }
 
 declare module 'svelte/store' {
diff --git a/playgrounds/demo/server.js b/playgrounds/demo/server.js
@@ -28,7 +28,7 @@ async function createServer() {
 
 		const template = fs.readFileSync(path.resolve(__dirname, 'index.html'), 'utf-8');
 		const transformed_template = await vite.transformIndexHtml(req.originalUrl, template);
-		const { html: appHtml, head: headHtml } = await vite.ssrLoadModule('./src/entry-server.ts');
+		const { body: appHtml, head: headHtml } = await vite.ssrLoadModule('./src/entry-server.ts');
 
 		const html = transformed_template
 			.replace(`<!--ssr-html-->`, appHtml)
diff --git a/playgrounds/demo/src/entry-server.ts b/playgrounds/demo/src/entry-server.ts
@@ -4,4 +4,4 @@ import { render } from 'svelte/server';
 import App from './App.svelte';
 
 // @ts-ignore
-export const { head, html, css } = render(App, { props: { initialCount: 0 } });
+export const { head, body, css } = render(App, { props: { initialCount: 0 } });
diff --git a/sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md b/sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md
@@ -119,7 +119,7 @@ Svelte provides reactive `Map`, `Set`, `Date` and `URL` classes. These can be im
 
 ### `render`
 
-Only available on the server and when compiling with the `server` option. Takes a component and returns an object with `html` and `head` properties on it, which you can use to populate the HTML when server-rendering your app:
+Only available on the server and when compiling with the `server` option. Takes a component and returns an object with `body` and `head` properties on it, which you can use to populate the HTML when server-rendering your app:
 
 ```js
 // @errors: 2724 2305 2307

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"svelte": patch
 +---
++
 +chore: deprecate html in favour of body for render()