Add support for Astro v4, drop support for Astro v3 (#1238)

.changeset/little-games-develop.md

@@ -0,0 +1,13 @@
+---
+'@astrojs/starlight': minor
+---
+
+Add support for Astro v4, drop support for Astro v3
+
+⚠️ **BREAKING CHANGE** Astro v3 is no longer supported. Make sure you [update Astro](https://docs.astro.build/en/guides/upgrade-to/v4/) and any other integrations at the same time as updating Starlight.
+
+Use the new `@astrojs/upgrade` command to upgrade Astro and Starlight together:
+
+```sh
+npx @astrojs/upgrade
+```

docs/package.json

@@ -15,17 +15,18 @@
   "dependencies": {
     "@astrojs/starlight": "workspace:*",
     "@types/culori": "^2.0.0",
-    "astro": "^3.2.3",
+    "astro": "^4.0.1",
     "culori": "^3.2.0",
     "sharp": "^0.32.5"
   },
   "devDependencies": {
-    "hast-util-from-html": "^1.0.2",
-    "hast-util-to-string": "^2.0.0",
-    "hastscript": "^7.2.0",
+    "@types/hast": "^3.0.3",
+    "hast-util-from-html": "^2.0.1",
+    "hast-util-to-string": "^3.0.0",
+    "hastscript": "^8.0.0",
     "pa11y-ci": "^3.0.1",
-    "rehype": "^12.0.1",
+    "rehype": "^13.0.1",
     "start-server-and-test": "^2.0.0",
-    "unist-util-visit": "^4.1.2"
+    "unist-util-visit": "^5.0.0"
   }
 }

docs/src/components/internal/rehype-file-tree.ts

@@ -1,7 +1,7 @@
 import { fromHtml } from 'hast-util-from-html';
 import { toString } from 'hast-util-to-string';
-import { h } from 'hastscript';
-import type { Element, HChild } from 'hastscript/lib/core';
+import { h, type Child } from 'hastscript';
+import type { Element } from 'hast';
 import { rehype } from 'rehype';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
 import { getIcon } from './file-tree-icons';
@@ -35,9 +35,10 @@ const FolderIcon = makeSVGIcon(
 	'<svg viewBox="0 0 20 20"><path d="M14.77 6.45H9.8v-.47A.97.97 0 0 0 8.83 5H3.75v10H15.7V7.42a.91.91 0 0 0-.93-.97Z"/></svg>'
 );
 
-export const fileTreeProcessor = rehype().use(() => (tree, file) => {
+export const fileTreeProcessor = rehype().use(() => (tree: Element, file) => {
 	const { directoryLabel } = file.data as { directoryLabel: string };
 	visit(tree, 'element', (node) => {
+		if (node.type !== 'element') return CONTINUE;
 		// Strip nodes that only contain newlines
 		node.children = node.children.filter(
 			(child) => child.type === 'comment' || child.type !== 'text' || !/^\n+$/.test(child.value)
@@ -50,7 +51,7 @@ export const fileTreeProcessor = rehype().use(() => (tree, file) => {
 
 		const [firstChild, ...otherChildren] = node.children;
 
-		const comment: HChild[] = [];
+		const comment: Child[] = [];
 		if (firstChild?.type === 'text') {
 			const [filename, ...fragments] = firstChild.value.split(' ');
 			firstChild.value = filename || '';
@@ -64,14 +65,14 @@ export const fileTreeProcessor = rehype().use(() => (tree, file) => {
 		otherChildren.splice(0, subTreeIndex > -1 ? subTreeIndex : otherChildren.length);
 		comment.push(...commentNodes);
 
-		const firstChildTextContent = toString(firstChild);
+		const firstChildTextContent = firstChild ? toString(firstChild) : '';
 
 		// Decide a node is a directory if it ends in a `/` or contains another list.
 		const isDirectory =
 			/\/\s*$/.test(firstChildTextContent) ||
 			otherChildren.some((child) => child.type === 'element' && child.tagName === 'ul');
 		const isPlaceholder = /^\s*(\.{3}|…)\s*$/.test(firstChildTextContent);
-		const isHighlighted = firstChild.type === 'element' && firstChild.tagName === 'strong';
+		const isHighlighted = firstChild?.type === 'element' && firstChild.tagName === 'strong';
 		const hasContents = otherChildren.length > 0;
 
 		const fileExtension = isDirectory ? 'dir' : firstChildTextContent.trim().split('.').pop() || '';

examples/basics/package.json

@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@astrojs/starlight": "^0.14.0",
-    "astro": "^3.2.3",
+    "astro": "^4.0.1",
     "sharp": "^0.32.5"
   }
 }

examples/tailwind/package.json

@@ -13,8 +13,8 @@
   "dependencies": {
     "@astrojs/starlight": "^0.14.0",
     "@astrojs/starlight-tailwind": "^2.0.1",
-    "@astrojs/tailwind": "^5.0.0",
-    "astro": "^3.2.3",
+    "@astrojs/tailwind": "^5.0.3",
+    "astro": "^4.0.1",
     "sharp": "^0.32.5",
     "tailwindcss": "^3.3.3"
   }

package.json

@@ -14,7 +14,7 @@
     "@changesets/changelog-github": "^0.4.8",
     "@changesets/cli": "^2.26.1",
     "@size-limit/file": "^8.2.4",
-    "astro": "^3.2.3",
+    "astro": "^4.0.1",
     "prettier": "^3.0.0",
     "prettier-plugin-astro": "^0.11.0",
     "size-limit": "^8.2.4"

packages/starlight/index.ts

@@ -1,5 +1,5 @@
 import mdx from '@astrojs/mdx';
-import type { AstroIntegration, AstroUserConfig } from 'astro';
+import type { AstroIntegration } from 'astro';
 import { spawn } from 'node:child_process';
 import { dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -41,11 +41,11 @@ export default function StarlightIntegration({
 
 				injectRoute({
 					pattern: '404',
-					entryPoint: '@astrojs/starlight/404.astro',
+					entrypoint: '@astrojs/starlight/404.astro',
 				});
 				injectRoute({
 					pattern: '[...slug]',
-					entryPoint: '@astrojs/starlight/index.astro',
+					entrypoint: '@astrojs/starlight/index.astro',
 				});
 				// Add built-in integrations only if they are not already added by the user through the
 				// config or by a plugin.
@@ -61,7 +61,7 @@ export default function StarlightIntegration({
 				if (!allIntegrations.find(({ name }) => name === '@astrojs/mdx')) {
 					integrations.push(mdx());
 				}
-				const newConfig: AstroUserConfig = {
+				updateConfig({
 					integrations,
 					vite: {
 						plugins: [vitePluginStarlightUserConfig(starlightConfig, config)],
@@ -76,8 +76,7 @@ export default function StarlightIntegration({
 							config.markdown.shikiConfig.theme !== 'github-dark' ? {} : { theme: 'css-variables' },
 					},
 					scopedStyleStrategy: 'where',
-				};
-				updateConfig(newConfig);
+				});
 			},
 
 			'astro:build:done': ({ dir }) => {

packages/starlight/integrations/asides.ts

@@ -1,3 +1,5 @@
+/// <reference types="mdast-util-directive" />
+
 import type { AstroConfig, AstroUserConfig } from 'astro';
 import { h as _h, s as _s, type Properties } from 'hastscript';
 import type { Paragraph as P, Root } from 'mdast';
@@ -100,7 +102,7 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 		const locale = pathToLocale(file.history[0], options);
 		const t = options.useTranslations(locale);
 		visit(tree, (node, index, parent) => {
-			if (!parent || index === null || node.type !== 'containerDirective') {
+			if (!parent || index === undefined || node.type !== 'containerDirective') {
 				return;
 			}
 			const variant = node.name;
@@ -112,7 +114,7 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 			// title prop, and remove the paragraph from children.
 			let title = t(`aside.${variant}`);
 			remove(node, (child): boolean | void => {
-				if (child.data?.directiveLabel) {
+				if (child.data && 'directiveLabel' in child.data && child.data.directiveLabel) {
 					if (
 						'children' in child &&
 						Array.isArray(child.children) &&

packages/starlight/integrations/code-rtl-support.ts

@@ -1,4 +1,4 @@
-import type { Root } from 'hastscript/lib/core';
+import type { Root } from 'hast';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
 
 /**

packages/starlight/package.json

@@ -163,31 +163,33 @@
     "./style/markdown.css": "./style/markdown.css"
   },
   "peerDependencies": {
-    "astro": "^3.2.0"
+    "astro": "^4.0.0"
   },
   "devDependencies": {
-    "@astrojs/markdown-remark": "^3.2.1",
+    "@astrojs/markdown-remark": "^4.0.0",
     "@types/node": "^18.16.19",
     "@vitest/coverage-v8": "^0.33.0",
-    "astro": "^3.2.3",
+    "astro": "^4.0.1",
     "vitest": "^0.33.0"
   },
   "dependencies": {
-    "@astrojs/mdx": "^1.1.0",
+    "@astrojs/mdx": "^2.0.0",
     "@astrojs/sitemap": "^3.0.3",
     "@pagefind/default-ui": "^1.0.3",
-    "@types/mdast": "^3.0.11",
-    "astro-expressive-code": "^0.29.0",
+    "@types/hast": "^3.0.3",
+    "@types/mdast": "^4.0.3",
+    "astro-expressive-code": "^0.29.3",
     "bcp-47": "^2.1.0",
     "execa": "^8.0.1",
-    "hast-util-select": "^5.0.5",
-    "hastscript": "^7.2.0",
+    "hast-util-select": "^6.0.2",
+    "hastscript": "^8.0.0",
+    "mdast-util-directive": "^3.0.0",
     "pagefind": "^1.0.3",
-    "rehype": "^12.0.1",
-    "remark-directive": "^2.0.1",
-    "unified": "^10.1.2",
-    "unist-util-remove": "^3.1.1",
-    "unist-util-visit": "^4.1.2",
-    "vfile": "^5.3.7"
+    "rehype": "^13.0.1",
+    "remark-directive": "^3.0.0",
+    "unified": "^11.0.4",
+    "unist-util-remove": "^4.0.0",
+    "unist-util-visit": "^5.0.0",
+    "vfile": "^6.0.1"
   }
 }

packages/starlight/user-components/rehype-tabs.ts

@@ -1,3 +1,4 @@
+import type { Element } from 'hast';
 import { select } from 'hast-util-select';
 import { rehype } from 'rehype';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
@@ -50,7 +51,7 @@ const getIDs = () => {
 const tabsProcessor = rehype()
 	.data('settings', { fragment: true })
 	.use(function tabs() {
-		return (tree, file) => {
+		return (tree: Element, file) => {
 			file.data.panels = [];
 			let isFirst = true;
 			visit(tree, 'element', (node) => {