Improve documentation about ASTRO_KEY #11751

dpuscher · 2025-05-23T10:42:19Z

Description (required)

This PR refines the "Reusing the encryption key" section in the Server Islands guide to enhance clarity and conciseness. The updated content emphasizes the necessity of setting ASTRO_KEY during the build phase.

Related issues & labels (optional)

Suggested label: docs

netlify · 2025-05-23T10:42:23Z

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`95f6d8a`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6835b79b8fa9c200083b3b90
😎 Deploy Preview	https://deploy-preview-11751--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

astrobot-houston · 2025-05-23T10:42:44Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/server-islands.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

astrobot-houston · 2025-05-23T10:42:55Z

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

Our GitHub bots will run to check your changes.
If they spot any broken links you will see some error messages on this PR.
Don’t hesitate to ask any questions if you’re not sure what these mean!
In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.
One or more of our maintainers will take a look and may ask you to make changes.
We try to be responsive, but don’t worry if this takes a few days.

ascorbic · 2025-05-23T15:08:06Z

src/content/docs/en/guides/server-islands.mdx


-To solve this, you can create a key with the Astro CLI and then reuse it for all of your deployments. This ensures that each user's frontend is talking to a backend that has the right key.
+To ensure both sides use the same key, you must supply the `ASTRO_KEY` environment variable **during the build**. This embeds always the same key into the generated bundle so that encryption and decryption remain in sync.


As this is a new paragraph it might be unclear that this only applies if you are doing rolling deployments, and that most users don't need to worry about it.

Agree, I added an additional note that setting an ASTRO_KEY is probably not needed for most users.

ascorbic · 2025-05-23T15:09:21Z

src/content/docs/en/guides/server-islands.mdx

+
+### Generating and configuring a reusable key
+
+Use the Astro CLI to generate a reusable key:


I have seen people getting confused, thinking that the required value is just a random string rather than an actual encoded key in a specific format.

True, I adjusted the last section to make clear that the output ASTRO_KEY is not just a random string but an encoded encryption key

sarah11918

Thanks, both, for contributing to this docs improvement! 🙌

Annoyingly, GitHub won't allow me to make the suggestions I'd like so I can Astro-Docs-Style this thing up, so you're gonna get one big block for the whole thing for your consideration. 😅

sarah11918 · 2025-05-27T22:36:16Z

src/content/docs/en/guides/server-islands.mdx

@@ -97,20 +97,26 @@ const productId = url.searchParams.get('product');

 ## Reusing the encryption key


Suggested change

## Reusing the encryption key

## Reusing the encryption key

Astro uses [cryptography](https://developer.mozilla.org/en-US/docs/Glossary/Cryptography) to encrypt props passed to server islands, protecting sensitive data from accidental exposure. This encryption relies on a new, random key that is generated on each build and embedded in the server bundle.

Most deploy hosts will handle keeping your front end and back end in sync automatically. However, you may need a constant encryption key if you are using rolling deployments, multi-region hosting or a CDN that caches pages containing server islands.

In environments with rolling deployments (e.g., Kubernetes) where your frontend assets (which encrypt props) and your backend functions (which decrypt props) may be temporarily using different keys, or when a CDN is still serving pages built with an old key, then encrypted props passed to your server island cannot be decrypted.

In these situations, use the Astro CLI to generate a reusable, encoded encryption key to set as an environment variable in your build environment:

```shell

astro create-key

```

Use this value to configure the `ASTRO_KEY` environment variable (e.g. in a `.env` file) and include it in your CI/CD or host's build settings. This ensures the same key is always reused in the generated bundle so that encryption and decryption remain in sync.

OK, it's a nightmare to try to make suggestions in the GitHub UI with all the line deletions etc., but here is my suggestion for presenting all this information in a way that conforms to Astro Docs style. (No overuse of notes/asides; combining info to avoid repetition; etc.)

See what you think, and of course, I'll rely on you both for correcting any nuance or facts that might have shifted during the flight. 😄

dpuscher changed the title ~~docs: improve documentation about ASTRO_KEY~~ Improve documentation about ASTRO_KEY May 23, 2025

dpuscher force-pushed the improve-astro-key-doc branch from f9fe6c7 to 6763471 Compare May 23, 2025 13:22

ascorbic reviewed May 23, 2025

View reviewed changes

dpuscher force-pushed the improve-astro-key-doc branch 3 times, most recently from 8521d5b to cd42c83 Compare May 27, 2025 11:49

docs: improve documentation about ASTRO_KEY

95f6d8a

dpuscher force-pushed the improve-astro-key-doc branch from cd42c83 to 95f6d8a Compare May 27, 2025 13:01

sarah11918 reviewed May 27, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Improve documentation about ASTRO_KEY #11751

Improve documentation about ASTRO_KEY #11751

dpuscher commented May 23, 2025

Uh oh!

netlify bot commented May 23, 2025 •

edited

Loading

Uh oh!

astrobot-houston commented May 23, 2025 •

edited

Loading

Uh oh!

astrobot-houston commented May 23, 2025

Uh oh!

ascorbic May 23, 2025

Uh oh!

dpuscher May 27, 2025

Uh oh!

ascorbic May 23, 2025

Uh oh!

dpuscher May 27, 2025

Uh oh!

sarah11918 left a comment

Uh oh!

sarah11918 May 27, 2025

Uh oh!

Uh oh!


		To solve this, you can create a key with the Astro CLI and then reuse it for all of your deployments. This ensures that each user's frontend is talking to a backend that has the right key.
		To ensure both sides use the same key, you must supply the `ASTRO_KEY` environment variable during the build. This embeds always the same key into the generated bundle so that encryption and decryption remain in sync.


		### Generating and configuring a reusable key

		Use the Astro CLI to generate a reusable key:

		@@ -97,20 +97,26 @@ const productId = url.searchParams.get('product');

		## Reusing the encryption key

-## Reusing the encryption key
+## Reusing the encryption key
+Astro uses [cryptography](https://developer.mozilla.org/en-US/docs/Glossary/Cryptography) to encrypt props passed to server islands, protecting sensitive data from accidental exposure. This encryption relies on a new, random key that is generated on each build and embedded in the server bundle.
+Most deploy hosts will handle keeping your front end and back end in sync automatically. However, you may need a constant encryption key if you are using rolling deployments, multi-region hosting or a CDN that caches pages containing server islands.
+In environments with rolling deployments (e.g., Kubernetes) where your frontend assets (which encrypt props) and your backend functions (which decrypt props) may be temporarily using different keys, or when a CDN is still serving pages built with an old key, then encrypted props passed to your server island cannot be decrypted.
+In these situations, use the Astro CLI to generate a reusable, encoded encryption key to set as an environment variable in your build environment:
+```shell
+astro create-key
+```
+Use this value to configure the `ASTRO_KEY` environment variable (e.g. in a `.env` file) and include it in your CI/CD or host's build settings. This ensures the same key is always reused in the generated bundle so that encryption and decryption remain in sync.

Uh oh!

Improve documentation about ASTRO_KEY #11751

Are you sure you want to change the base?

Improve documentation about ASTRO_KEY #11751

Conversation

dpuscher commented May 23, 2025

Description (required)

Related issues & labels (optional)

Uh oh!

netlify bot commented May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

astrobot-houston commented May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

astrobot-houston commented May 23, 2025

Uh oh!

ascorbic May 23, 2025

Choose a reason for hiding this comment

Uh oh!

dpuscher May 27, 2025

Choose a reason for hiding this comment

Uh oh!

ascorbic May 23, 2025

Choose a reason for hiding this comment

Uh oh!

dpuscher May 27, 2025

Choose a reason for hiding this comment

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

sarah11918 May 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

netlify bot commented May 23, 2025 •

edited

Loading

astrobot-houston commented May 23, 2025 •

edited

Loading