Upgrade Astro to v7 and update related dependencies by RobbieTheWagner · Pull Request #3514 · shipshapecode/shepherd

RobbieTheWagner · 2026-09-03T02:58:50Z

Summary

This PR upgrades the project from Astro v5 to v7, along with corresponding updates to related dependencies and necessary code migrations to support the new Astro API.

Key Changes

Astro Framework Upgrade

Upgraded Astro from v5.18.2 to v7.2.10 in both landing and docs-src packages
Updated related Astro integrations:
- @astrojs/mdx: v5.0.6 → v8.0.0
- @astrojs/vercel: v9.0.5 → v11.0.9
- @astrojs/starlight: v0.37.7 → v0.42.0
- starlight-typedoc: v0.21.5 → v0.23.1

Content Collections API Migration

Updated content.config.ts files to use the new Astro v7 loader pattern:
- Added glob loader for blog content in landing package
- Added docsLoader() for Starlight docs in docs-src package
- Moved schema imports to use astro/zod instead of astro:content
Migrated blog post routing from post.slug to post.id throughout the codebase
Updated render() function calls to use the new standalone render() import from astro:content

View Transitions API Update

Replaced deprecated ViewTransitions component with ClientRouter in BaseHead.astro

Starlight Component Updates

Removed Props type import from @astrojs/starlight/props in HeadWithPosthog.astro
Simplified component props passing to align with Starlight v0.42.0 API

Infrastructure & Tooling

Updated Node.js version requirement from ≥20 to ≥22.12
Updated Node.js in Dockerfile from 20.10.0 to 22.22.2
Updated pnpm from 9.2.0 to 11.21.0
Updated sharp from v0.34.5 to v0.35.0
Added @astrojs/starlight@0.42.0 to minimumReleaseAgeExclude in pnpm-workspace.yaml

Dev Server Configuration

Fixed dev server environment variable handling to prevent Vitest markers from interfering with Astro v7's background daemon detection
Added explicit ASTRO_DEV_BACKGROUND: '0' and removed VITEST from child process environment

Test Updates

Updated route pattern expectation in dist.test.ts to reflect Astro v6+ behavior where endpoints with file extensions are not served with trailing slashes

Notable Implementation Details

The content collections migration maintains backward compatibility in templates by using post.id instead of post.slug
Dev server environment isolation ensures proper test execution with Astro v7's new daemon behavior
All Astro integration versions are aligned to support v7 APIs

https://claude.ai/code/session_01KB5E2kb34UW1yqBNuEjgpF

Summary by CodeRabbit

Bug Fixes
- Fixed blog post links and RSS URLs to consistently resolve to the correct pages.
- Updated blog post rendering and route handling for the latest Astro behavior.
- Corrected endpoint URL expectations and development-server behavior during testing.
Documentation
- Improved documentation site content loading and compatibility with the latest site-generation framework.
Chores
- Updated the minimum supported Node.js version to 22.12 or later.
- Replaced the deprecated page-transition implementation with its supported successor.

Consolidates the open dependabot Astro PRs (#3458, #3509, #3510, #3511, #3513) into a single coordinated upgrade from Astro 5 to Astro 7: - astro 5.18.2 -> 7.2.10 (both apps) - @astrojs/mdx 5.0.6 -> 8.0.0 - @astrojs/vercel 9.0.5 -> 11.0.9 - @astrojs/starlight 0.37.7 -> 0.42.0 - @astrojs/sitemap 3.7.3 -> 3.7.4 - starlight-typedoc 0.21.5 -> 0.23.1 - sharp 0.34.5 -> 0.35.x (matches existing workspace override) Code changes for the Astro 6/7 breaking changes: - Migrate legacy content collections (removed in Astro 6) to the Content Layer API: src/content/config.ts moves to src/content.config.ts with the glob() loader in landing and Starlight's docsLoader() in docs, and entry.slug / entry.render() become entry.id / render(entry). - Replace the removed <ViewTransitions /> component with <ClientRouter />. - Drop the deprecated @astrojs/starlight/props Props import from the Starlight Head override. - Accept the Astro 6 endpoint trailing-slash change in the Vercel route assertions (/index.md route no longer matches a trailing slash). - Keep the landing e2e dev server in the foreground: Astro 7 detaches `astro dev` into a background daemon when it detects an AI coding agent (opted out via ASTRO_DEV_BACKGROUND), and strip Vitest's VITEST env marker, which makes the Vite 8 dev server 404 every route. - Raise Node to >= 22.12 (Astro 7 minimum) in the workspace engines and the docs Dockerfile, and align the Dockerfile's pnpm with the workspace's packageManager version. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KB5E2kb34UW1yqBNuEjgpF

vercel · 2026-09-03T02:58:56Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
shepherd-docs	Ready	Preview	Sep 3, 2026 3:02am UTC
shepherd-landing	Ready	Preview	Sep 3, 2026 3:02am UTC

coderabbitai · 2026-09-03T02:59:08Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 199b16d3-57bb-4774-8d66-dae38213b948

📥 Commits

Reviewing files that changed from the base of the PR and between 5d4173d and 9b5d38c.

⛔ Files ignored due to path filters (1)

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (14)

docs-src/Dockerfile
docs-src/package.json
docs-src/src/components/HeadWithPosthog.astro
docs-src/src/content.config.ts
landing/package.json
landing/src/components/BaseHead.astro
landing/src/content.config.ts
landing/src/pages/blog/[...slug].astro
landing/src/pages/blog/index.astro
landing/src/pages/rss.xml.js
landing/test/dist.test.ts
landing/test/setup/dev-server.ts
package.json
pnpm-workspace.yaml

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

Walkthrough

The PR upgrades Node.js, pnpm, Astro packages, and content loading APIs. It updates documentation and landing-site integrations, changes blog routes to use post.id, and adjusts landing-site test server behavior.

Changes

Astro platform migration

Layer / File(s)	Summary
Runtime and tooling updates `docs-src/Dockerfile`, `docs-src/package.json`, `landing/package.json`, `package.json`, `pnpm-workspace.yaml`	Node.js, pnpm, Astro-related packages, the minimum Node.js version, and the Starlight release-age exclusion are updated.
Documentation content migration `docs-src/src/content.config.ts`, `docs-src/src/components/HeadWithPosthog.astro`	The docs collection uses `docsLoader()`. The custom head component stops forwarding `Astro.props` to `Default`.
Landing content and navigation migration `landing/src/content.config.ts`, `landing/src/components/BaseHead.astro`, `landing/src/pages/blog/[...slug].astro`, `landing/src/pages/blog/index.astro`, `landing/src/pages/rss.xml.js`	The blog collection uses `glob`. `ClientRouter` replaces `ViewTransitions`. Blog links and RSS links use `post.id`, and blog content uses `render(post)`.
Test server compatibility `landing/test/dist.test.ts`, `landing/test/setup/dev-server.ts`	The `/index.md` route assertion removes the optional trailing slash. The Astro test server disables backgrounding and removes `VITEST` from its environment.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🟡 Moderate · up to 9b5d3

This update migrates the sites to Astro 7 and updates their runtime tooling. The content, routing, and test migrations are internally consistent in the supplied changes, but the Starlight release-age exemption should be confirmed against the effective CI configuration before merging to ensure dependency-install policy remains intentional.

Sequence Diagram(s)

sequenceDiagram
  participant BlogContentCollection
  participant getStaticPaths
  participant BlogPostPage
  BlogContentCollection->>getStaticPaths: Load blog entries with glob
  getStaticPaths->>BlogPostPage: Pass post.id as slug
  BlogPostPage->>BlogPostPage: Render post with render(post)

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 5 files. (9 skipped: 9 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: upgrading Astro to version 7 and updating related dependencies.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 5 files. (9 skipped: 9 unsupported.)

Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

🛠️ Fix failing CI checks 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch claude/astro-package-updates-rgzdyq

Warning

Some tools did not complete. Review the errors below.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

landing/src/pages/rss.xml.js

(node:2) ESLintIgnoreWarning: The ".eslintignore" file is no longer supported. Switch to using the "ignores" property in "eslint.config.js": https://eslint.org/docs/latest/use/configure/migration-guide#ignore-files
(Use node --trace-warnings ... to show where the warning was created)

Oops! Something went wrong! :(

ESLint: 10.9.1

A config object is using the "root" key, which is not supported in flat config system.

Flat configs always act as if they are the root config file, so this key can be safely removed.

landing/test/dist.test.ts

ESLint skipped: the matched ESLint configuration already failed (config-incompatibility).

landing/test/setup/dev-server.ts

ESLint skipped: the matched ESLint configuration already failed (config-incompatibility).

1 others

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

`astro check` (and the Vercel landing deploy) failed with ts(2339) because the spread-literal type has no VITEST property to delete. Annotate the env as NodeJS.ProcessEnv. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KB5E2kb34UW1yqBNuEjgpF

qltysh · 2026-09-03T03:01:40Z

Coverage Impact

This PR will not change total coverage.

🚦 See full report on Qlty Cloud »

🛟 Help

Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.
Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.
File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)
- Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

vercel Bot deployed to Preview – shepherd-docs September 3, 2026 03:02 View deployment

vercel Bot deployed to Preview – shepherd-landing September 3, 2026 03:02 View deployment

RobbieTheWagner merged commit 7dc5ef2 into main Sep 3, 2026
7 checks passed

RobbieTheWagner deleted the claude/astro-package-updates-rgzdyq branch September 3, 2026 03:04

github-actions Bot mentioned this pull request Sep 3, 2026

Prepare Release #3498

Open

RobbieTheWagner added the internal label Sep 3, 2026

Navigation Menu

Uh oh!

Uh oh!

Upgrade Astro to v7 and update related dependencies - #3514

Upgrade Astro to v7 and update related dependencies#3514
RobbieTheWagner merged 2 commits into
mainfrom
claude/astro-package-updates-rgzdyq

RobbieTheWagner commented Sep 3, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

vercel Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 3, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

qltysh Bot commented Sep 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

RobbieTheWagner commented Sep 3, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

Astro Framework Upgrade

Content Collections API Migration

View Transitions API Update

Starlight Component Updates

Infrastructure & Tooling

Dev Server Configuration

Test Updates

Notable Implementation Details

Summary by CodeRabbit

Uh oh!

vercel Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

qltysh Bot commented Sep 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

RobbieTheWagner commented Sep 3, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented Sep 3, 2026 •

edited

Loading

coderabbitai Bot commented Sep 3, 2026 •

edited

Loading