Improve documentation about ASTRO_KEY by dpuscher · Pull Request #11751 · withastro/docs

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	`449fbb2`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/68372a8c545367000803398c
😎 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

+In environments with rolling deployments (e.g., Kubernetes), your frontend assets (which encrypt props) and your backend functions (which decrypt props) may be temporarily out of sync. By default, Astro generates a new random key on each build. If the frontend and backend use different keys - or if a CDN is still serving pages built with an old key - encrypted props cannot be decrypted, causing server islands to fail.

-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

+
+### 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

@@ -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. 😄

Awesome, thanks for looking into this. Your version sounds great, will implement the changes into my branch. 👍

sarah11918

Thank you for taking the time to improve this section, @dpuscher ! We appreciate the effort, and are happy to welcome you to Team Docs! 🥳

See withastro#11751

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 4 times, most recently from cd42c83 to 95f6d8a Compare May 27, 2025 13:01

sarah11918 reviewed May 27, 2025

View reviewed changes

docs: improve documentation about ASTRO_KEY

2c22991

dpuscher force-pushed the improve-astro-key-doc branch from 95f6d8a to 2c22991 Compare May 28, 2025 09:20

Merge branch 'main' into improve-astro-key-doc

8910001

sarah11918 reviewed May 28, 2025

View reviewed changes

Comment thread src/content/docs/en/guides/server-islands.mdx Outdated

sarah11918 added 2 commits May 28, 2025 10:51

grammar fix, remove "then"

27cdb2b

Merge branch 'main' into improve-astro-key-doc

34faf79

sarah11918 added improve or update documentation Enhance / update existing documentation (e.g. add example, improve description, update for changes) Merge Queue Approved and ready to be merged (wait for feature release if also labelled M-O-R)! labels May 28, 2025

sarah11918 approved these changes May 28, 2025

View reviewed changes

Merge branch 'main' into improve-astro-key-doc

449fbb2

sarah11918 merged commit 5fc3784 into withastro:main May 28, 2025
10 checks passed

ArmandPhilippot added a commit to ArmandPhilippot/astro-docs that referenced this pull request May 28, 2025

i18n(fr): update guides/server-islands.mdx

64a1696

See withastro#11751

ArmandPhilippot mentioned this pull request May 28, 2025

i18n(fr): update guides/server-islands.mdx #11792

Merged

jsparkdev mentioned this pull request May 29, 2025

i18n(ko-KR): update server-islands.mdx #11799

Merged

Nin3lee mentioned this pull request Jun 4, 2025

i18n(zh-cn): Update server-islands.mdx #11832

Merged


		### 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!

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!

dpuscher May 28, 2025

Choose a reason for hiding this comment

Uh oh!

dpuscher May 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify Bot commented May 23, 2025 •

edited

Loading

astrobot-houston commented May 23, 2025 •

edited

Loading