From a66a37be481e91f4b0914417463161819d0a1a38 Mon Sep 17 00:00:00 2001 From: Brandon Ly Date: Fri, 17 Jan 2025 09:24:06 -0600 Subject: [PATCH 1/8] Update documentation for framework components page --- src/content/docs/en/guides/framework-components.mdx | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/framework-components.mdx b/src/content/docs/en/guides/framework-components.mdx index 75e6bac66d099..572b8470b4660 100644 --- a/src/content/docs/en/guides/framework-components.mdx +++ b/src/content/docs/en/guides/framework-components.mdx @@ -119,10 +119,15 @@ import Counter from '../components/Counter.svelte'; ``` -:::caution[Passing functions as props] + + +:::caution You can pass a function as a prop to a framework component, but it only works during server rendering. If you try to use the function in a hydrated component (for example, as an event handler), an error will occur. -This is because functions can't be _serialized_ (transferred from the server to the client) by Astro. +This is because functions can't be _serialized_ (transferred from the server to the client) by Astro. Objects with circular references are also not serializable. + +For hydrated components, props must be serializable. The following types are supported: +`plain object`, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity` ::: From 487a92867fcc8f6b0aa363f97582cf145607bf4c Mon Sep 17 00:00:00 2001 From: Brandon Ly Date: Fri, 24 Jan 2025 08:28:12 -0600 Subject: [PATCH 2/8] Rephrase serializable components --- src/content/docs/en/guides/framework-components.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/framework-components.mdx b/src/content/docs/en/guides/framework-components.mdx index 572b8470b4660..345f65063ef8d 100644 --- a/src/content/docs/en/guides/framework-components.mdx +++ b/src/content/docs/en/guides/framework-components.mdx @@ -126,7 +126,7 @@ You can pass a function as a prop to a framework component, but it only works du This is because functions can't be _serialized_ (transferred from the server to the client) by Astro. Objects with circular references are also not serializable. -For hydrated components, props must be serializable. The following types are supported: +For hydrated components, prop values that are passed in must be serializable. The following types are supported: `plain object`, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity` ::: From baad915c5ccc38bda0fdc7e30accd72213ef98be Mon Sep 17 00:00:00 2001 From: Brandon Ly Date: Fri, 24 Jan 2025 09:08:23 -0600 Subject: [PATCH 3/8] Rephrase serializable components --- src/content/docs/en/guides/framework-components.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/framework-components.mdx b/src/content/docs/en/guides/framework-components.mdx index 345f65063ef8d..5e56f6c6275ba 100644 --- a/src/content/docs/en/guides/framework-components.mdx +++ b/src/content/docs/en/guides/framework-components.mdx @@ -126,7 +126,7 @@ You can pass a function as a prop to a framework component, but it only works du This is because functions can't be _serialized_ (transferred from the server to the client) by Astro. Objects with circular references are also not serializable. -For hydrated components, prop values that are passed in must be serializable. The following types are supported: +Props provided to hydrated components must be serializable. The following prop types are supported: `plain object`, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity` ::: From f4bfc8ddfe44dd1fa27ebb9b359f265869cb54f2 Mon Sep 17 00:00:00 2001 From: Brandon Ly Date: Tue, 11 Feb 2025 18:28:19 -0600 Subject: [PATCH 4/8] Update documentation for server islands --- src/content/docs/en/guides/framework-components.mdx | 4 ++-- src/content/docs/en/guides/server-islands.mdx | 9 +++++++++ 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/framework-components.mdx b/src/content/docs/en/guides/framework-components.mdx index 5e56f6c6275ba..2a35103e280a0 100644 --- a/src/content/docs/en/guides/framework-components.mdx +++ b/src/content/docs/en/guides/framework-components.mdx @@ -122,9 +122,9 @@ import Counter from '../components/Counter.svelte'; :::caution -You can pass a function as a prop to a framework component, but it only works during server rendering. If you try to use the function in a hydrated component (for example, as an event handler), an error will occur. +You can pass a function as a prop to a framework component, but this only works during server rendering. If you try to use the function in a hydrated component (for example, as an event handler), an error will occur. -This is because functions can't be _serialized_ (transferred from the server to the client) by Astro. Objects with circular references are also not serializable. +This is because functions cannot be _serialized_ (transferred from the server to the client) by Astro. Objects with circular references are also not serializable. Props provided to hydrated components must be serializable. The following prop types are supported: `plain object`, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity` diff --git a/src/content/docs/en/guides/server-islands.mdx b/src/content/docs/en/guides/server-islands.mdx index e5e944bdccc0e..36347440762be 100644 --- a/src/content/docs/en/guides/server-islands.mdx +++ b/src/content/docs/en/guides/server-islands.mdx @@ -33,6 +33,15 @@ const avatarURL = await getUserAvatar(userSession); --- User avatar ``` +:::caution[Server Island Prop Limitations] +You can pass a function as a prop to a server island component, but this only works during server rendering. If you try to use the function in a hydrated component (for example, as an event handler), an error will occur. + +This is because functions cannot be _serialized_ (transferred from the server to the client) by Astro. Objects with circular references are also not serializable. + +Props provided to hydrated components must be serializable. The following prop types are supported: +`plain object`, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity` +::: + ## Server island fallback content From 7612c120df6bd73f54fbc80c60de09ddad4b74be Mon Sep 17 00:00:00 2001 From: Brandon Ly Date: Tue, 18 Feb 2025 19:24:33 -0600 Subject: [PATCH 5/8] Update src/content/docs/en/guides/framework-components.mdx Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- src/content/docs/en/guides/framework-components.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/guides/framework-components.mdx b/src/content/docs/en/guides/framework-components.mdx index 2a35103e280a0..f69ecc3faad0f 100644 --- a/src/content/docs/en/guides/framework-components.mdx +++ b/src/content/docs/en/guides/framework-components.mdx @@ -121,14 +121,13 @@ import Counter from '../components/Counter.svelte'; -:::caution -You can pass a function as a prop to a framework component, but this only works during server rendering. If you try to use the function in a hydrated component (for example, as an event handler), an error will occur. -This is because functions cannot be _serialized_ (transferred from the server to the client) by Astro. Objects with circular references are also not serializable. +Props that are passed to framework functions must be [serialized](https://developer.mozilla.org/en-US/docs/Glossary/Serialization): translated into a format suitable for transfer over a network, or storage. However, for performance and/or security reasons, Astro does not serialize every type of data structure. Therefore, there are some limitations on what can be passed as props. + +Notably, you can only pass a function as a prop to a framework component during server rendering. If you try to use the function in a hydrated component (for example, as an event handler), an error will occur. Similarly, passing an object with circular reference is not supported. -Props provided to hydrated components must be serializable. The following prop types are supported: +The following prop types are supported: `plain object`, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity` -::: ## Passing children to framework components From 45eeae1ba1037cd7ab358c83ffb5a386dd416408 Mon Sep 17 00:00:00 2001 From: Brandon Ly Date: Wed, 19 Feb 2025 05:00:29 -0600 Subject: [PATCH 6/8] feat: restructure framework components props guide --- src/content/docs/en/guides/framework-components.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/framework-components.mdx b/src/content/docs/en/guides/framework-components.mdx index f69ecc3faad0f..6fffcad37e7d5 100644 --- a/src/content/docs/en/guides/framework-components.mdx +++ b/src/content/docs/en/guides/framework-components.mdx @@ -124,11 +124,10 @@ import Counter from '../components/Counter.svelte'; Props that are passed to framework functions must be [serialized](https://developer.mozilla.org/en-US/docs/Glossary/Serialization): translated into a format suitable for transfer over a network, or storage. However, for performance and/or security reasons, Astro does not serialize every type of data structure. Therefore, there are some limitations on what can be passed as props. -Notably, you can only pass a function as a prop to a framework component during server rendering. If you try to use the function in a hydrated component (for example, as an event handler), an error will occur. Similarly, passing an object with circular reference is not supported. - The following prop types are supported: `plain object`, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity` +Props that are not serializable can still be passed to a framework components during server rendering. Framework components that are hydrated require that props are serializable. ## Passing children to framework components From c47ed90a111f8da5ada644806979658681b6957a Mon Sep 17 00:00:00 2001 From: Brandon Ly Date: Thu, 20 Feb 2025 18:57:20 -0600 Subject: [PATCH 7/8] Update src/content/docs/en/guides/framework-components.mdx Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- src/content/docs/en/guides/framework-components.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/framework-components.mdx b/src/content/docs/en/guides/framework-components.mdx index 6fffcad37e7d5..f4f087b037cb3 100644 --- a/src/content/docs/en/guides/framework-components.mdx +++ b/src/content/docs/en/guides/framework-components.mdx @@ -122,7 +122,7 @@ import Counter from '../components/Counter.svelte'; -Props that are passed to framework functions must be [serialized](https://developer.mozilla.org/en-US/docs/Glossary/Serialization): translated into a format suitable for transfer over a network, or storage. However, for performance and/or security reasons, Astro does not serialize every type of data structure. Therefore, there are some limitations on what can be passed as props. +Props that are passed to interactive framework components [using a `client:*` directive](/en/reference/directives-reference/#client-directives) must be [serialized](https://developer.mozilla.org/en-US/docs/Glossary/Serialization): translated into a format suitable for transfer over a network, or storage. However, for performance and/or security reasons, Astro does not serialize every type of data structure. Therefore, there are some limitations on what can be passed as props to hydrated components. The following prop types are supported: `plain object`, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity` From 28d28189679be7df6dc2921afdd8419f59078588 Mon Sep 17 00:00:00 2001 From: Brandon Ly Date: Thu, 20 Feb 2025 18:57:26 -0600 Subject: [PATCH 8/8] Update src/content/docs/en/guides/framework-components.mdx Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- src/content/docs/en/guides/framework-components.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/framework-components.mdx b/src/content/docs/en/guides/framework-components.mdx index f4f087b037cb3..19d14f26dd5e3 100644 --- a/src/content/docs/en/guides/framework-components.mdx +++ b/src/content/docs/en/guides/framework-components.mdx @@ -127,7 +127,7 @@ Props that are passed to interactive framework components [using a `client:*` di The following prop types are supported: `plain object`, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity` -Props that are not serializable can still be passed to a framework components during server rendering. Framework components that are hydrated require that props are serializable. +Non-supported data structures passed to components, such as functions, can only be used during the component's server rendering and cannot be used to provide interactivity. For example, passing functions to hydrated components is not supported because Astro cannot pass functions from the server in a way that make them executable on the client. ## Passing children to framework components