Skip to content

Astro 6 support#3644

Merged
delucis merged 70 commits intowithastro:mainfrom
HiDeoo:hd/astro-v6
Mar 11, 2026
Merged

Astro 6 support#3644
delucis merged 70 commits intowithastro:mainfrom
HiDeoo:hd/astro-v6

Conversation

@HiDeoo
Copy link
Copy Markdown
Member

@HiDeoo HiDeoo commented Jan 2, 2026

Description

This PR adds support for Astro 6 (currently requires at least version 6.0.0)

See #3644 (comment) for preview releases.

Known issues

Symbol Status
🟢 Fixed
🟡 Fix pending review
🔴 No fix yet, under investigation

Previews

Remaining tasks

  • Bump Netlify Node.js version to 22.12.0+.
  • Fix links validation errors once all docs changes are validated.
  • Bump size-limit CSS size limit
    • Only did a really quick check, but it seems that some previously inlined CSS is now extracted to a separate file and linked in the HTML. The CSS is similar between Astro v5 and v6, and its size is around 7.4K. Vite default assetsInlineLimit value is 4K, so it makes sense that the CSS is not inlined and the current behavior seems correct. A great idea from Chris could be that it was previously considered several chunks, each under 4K, and now bundled together, but that would need to be verified.
      • Confirmed Chris's intuition using build.assetsInlineLimit callback variant. Before, this was called individually for each inlinable CSS which were then all inlined together, ending up in a potentially inlined CSS content above the limit. Now, the content is concatenated first and then the callback is called only once for each inlinable CSS concatenated content, which correctly allows to inline the CSS content if the total size is below the limit. To follow up, I updated the size-limit threshold in c4bdad0
  • Bump Astro dependencies to latest stable versions once released.
  • Bump some peer dependencies versions once ready to release.
  • Search and address any TODO(HiDeoo) comments.
  • Add changesets.
    • Make sure changesets use the correct new Starlight version number (e.g. 0.38.0)
    • Update links to v6 migration guide in .changeset/strange-eyes-fold.md

@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Jan 2, 2026

🦋 Changeset detected

Latest commit: 290622f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages
Name Type
@astrojs/starlight Minor
@astrojs/starlight-markdoc Minor
@astrojs/starlight-tailwind Major
@astrojs/starlight-docsearch Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@netlify
Copy link
Copy Markdown

netlify bot commented Jan 2, 2026

Deploy Preview for astro-starlight ready!

Name Link
🔨 Latest commit 290622f
🔍 Latest deploy log https://app.netlify.com/projects/astro-starlight/deploys/69b052cc50547200089c5c68
😎 Deploy Preview https://deploy-preview-3644--astro-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 100 (no change from production)
Accessibility: 100 (no change from production)
Best Practices: 100 (no change from production)
SEO: 100 (no change from production)
PWA: -
View the detailed breakdown and full score reports

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

@github-actions github-actions bot added 🚨 action Changes to GitHub Action workflows 📚 docs Documentation website changes 🌟 core Changes to Starlight’s main package 🌟 tailwind Changes to Starlight’s Tailwind package 🌟 markdoc Changes to Starlight’s Markdoc package 🌟 docsearch Changes to Starlight’s DocSearch plugin labels Jan 2, 2026
@HiDeoo
Copy link
Copy Markdown
Member Author

HiDeoo commented Mar 9, 2026

@HiDeoo are the styles fixed after a refresh of the browser? That's what I saw, just want to confirm.

No, this one is different, they never get fixed even after refreshes (as opposed to the missing styles which appear after a refresh).

@matthewp
Copy link
Copy Markdown
Contributor

matthewp commented Mar 9, 2026

@HiDeoo I was able to fix all dev server optimization warnings and prevent needing a restart with this:

diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
index 8b3a782b..d052e1b8 100644
--- a/packages/starlight/index.ts
+++ b/packages/starlight/index.ts
@@ -124,11 +124,10 @@ export default function StarlightIntegration(
 					absolutePathToLang,
 				};
 
-				// TODO: refactor once there is a reliable way to detect this, rather than relying on the
-				// presence of specific integrations.
-				const isNodeCompatibleEnv = !config.integrations.some(
-					({ name }) => name === '@astrojs/cloudflare'
-				);
+				const isCloudflareEnv =
+					config.adapter?.name === '@astrojs/cloudflare' ||
+					config.integrations.some(({ name }) => name === '@astrojs/cloudflare');
+				const isNodeCompatibleEnv = !isCloudflareEnv;
 
 				updateConfig({
 					vite: {
@@ -146,15 +145,22 @@ export default function StarlightIntegration(
 							: {
 									optimizeDeps: {
 										include: [
+											'@astrojs/cloudflare/entrypoints/server',
 											// TODO: once Expressive Code is refactored/fixed, remove this workaround for
 											// Expressive Code relying on CJS dependencies like postcss not compatible
 											// with the Cloudflare adapter.
-											'@astrojs/starlight>astro-expressive-code',
-											'@astrojs/starlight>astro-expressive-code/hast',
-											'@astrojs/starlight>astro-expressive-code>css-select',
-											'@astrojs/starlight>astro-expressive-code>nth-check',
-											'@astrojs/starlight>astro-expressive-code>boolbase',
-											'@astrojs/starlight>extend',
+											'@astrojs/starlight>astro-expressive-code/components',
+											'@astrojs/starlight>astro-expressive-code>hast-util-select',
+											'@astrojs/starlight>astro-expressive-code>rehype',
+											'@astrojs/starlight>astro-expressive-code>unist-util-visit',
+											'@astrojs/starlight>astro-expressive-code>rehype-format',
+											'@astrojs/starlight>astro-expressive-code>hastscript',
+											'@astrojs/starlight>astro-expressive-code>hast-util-from-html',
+											'@astrojs/starlight>astro-expressive-code>hast-util-to-string',
+											'@astrojs/starlight>astro-expressive-code>@expressive-code/core>postcss',
+											'@astrojs/starlight>i18next',
+											'@astrojs/starlight>js-yaml',
+											'@astrojs/starlight>klona/lite',
 										],
 									},
 								},

withastro/astro#15815 is also needed. Note that this doesn't fix the CSS issues, that's separate.

Copy link
Copy Markdown
Member

@delucis delucis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes are looking good!

I can update the dependencies to stable releases now if it’s helpful.

const isCloudflareEnv =
config.adapter?.name === '@astrojs/cloudflare' ||
config.integrations.some(({ name }) => name === '@astrojs/cloudflare');
const isNodeCompatibleEnv = !isCloudflareEnv;
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you know if the plan is for this variable to become available in Astro directly?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I need to ping back Matthew in the thread we asked about this but didn't want to ping him again today. Depending on the answer, I'll update the comment.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't have such a plan but we can talk about it.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, there we go, thanks. I'll bring it up later in the thread so we can discuss it 👍

Copy link
Copy Markdown
Member

@delucis delucis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The time has come.

A star is rising in the shadow of Astro 6 to shine a light on documentation websites everywhere.

Thanks everyone and especially @HiDeoo for the amazing work getting this release ready 💖

@delucis delucis merged commit 0d2e7ed into withastro:main Mar 11, 2026
17 checks passed
@astrobot-houston astrobot-houston mentioned this pull request Mar 11, 2026
ArmandPhilippot added a commit to ArmandPhilippot/starlight that referenced this pull request Mar 23, 2026
ArmandPhilippot added a commit to ArmandPhilippot/starlight that referenced this pull request Mar 23, 2026
ArmandPhilippot added a commit to ArmandPhilippot/starlight that referenced this pull request Mar 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🚨 action Changes to GitHub Action workflows 🌟 core Changes to Starlight’s main package 📚 docs Documentation website changes 🌟 docsearch Changes to Starlight’s DocSearch plugin 🌟 markdoc Changes to Starlight’s Markdoc package 🌟 minor Change that triggers a minor release 🌟 tailwind Changes to Starlight’s Tailwind package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants