On May 7, 2026, the Astro team simultaneously released Astro 6.3 and Starlight 0.39. When the core Astro framework and its official documentation theme Starlight receive version bumps in the same week, teams maintaining client projects with "Astro for the corporate site and Starlight for documentation" are forced to design a parallel upgrade strategy.
Our own corporate site (gleamhub.net) is built with Astro, and multiple client sites built through our custom development services run on Astro and Starlight. "Upgrading core and Starlight on the exact same day" causes a situation where an issue in one blocks releases of the other, making it an ironclad rule to avoid this in client maintenance. In this article, we outline the steps for safely staggering the rollout of Astro 6.3 and Starlight 0.39.
Key changes in 6.3 and 0.39 (Scope relevant to custom development)
Here are excerpts from the official blog highlighting changes likely to impact implementation in custom development.
| Products | Area of change | Impact on client sites |
|---|---|---|
| Astro 6.3 | Content Collections loader API extensions | Opportunity to redesign custom loaders for large-scale content sites |
| Astro 6.3 | Default switch to AVIF / WebP in Image Service | Potential change in output format for OG images and featuredImage |
| Astro 6.3 | Session control for View Transitions | Behavioral changes in sites using SPA-style transitions |
| Astro 6.3 | Continued tightening of Type Generation | New warnings emitted at astro check |
| Starlight 0.39 | Changes to automatic sidebar generation logic | Reordering of existing documentation may occur |
| Starlight 0.39 | Default changes around i18n | Impact on URLs for multilingual documentation |
| Starlight 0.39 | Signature changes in theme extension APIs | Modifications required on custom components |
In particular, the default switch of output formats in Image Service and logic changes in Starlight's automatic sidebar generation represent updates that strictly require visual inspection across both corporate and documentation sites.
The reality that the 6.x release cycle has turned into "de facto quarterly major-equivalent releases," as discussed in Incorporating the Astro 6.2 Release into Client Maintenance, has become even clearer with 6.3.
Parallel upgrade procedure: "Do not upgrade in the same week"
Here is the staggered workflow implemented in our client maintenance for adopting core Astro and Starlight.
[Week 1] Astro 6.3 をコーポレート / メディアサイトに取り込む
└ chore/astro-6.3-upgrade ブランチで検証 → 段階リリース
└ Starlight サイトはこの週は据え置き
[Week 2] Astro 6.3 を Starlight サイトにも取り込む
└ Starlight 0.38 は据え置きのまま、本体だけ 6.3 に上げる
└ Starlight 側に互換性問題が出ないか観測
[Week 3] Starlight 0.39 を取り込む
└ chore/starlight-0.39-upgrade ブランチで検証
└ サイドバー自動生成の挙動変化を目視確認
[Week 4] バッファ週(障害対応 / ホットフィックス)
└ 何も予定を入れず、前週までの不具合に当てるThe key takeaway is the sequence: "fully roll out Astro 6.3 across all sites before upgrading Starlight 0.39." Reversing this order makes diagnosing whether breakages caused by Starlight 0.39's theme extension API changes stem from core 6.3 or from the theme far more time-consuming.
Specifying "parallel upgrades" within maintenance contract scope
Whether you can actually execute the staggered procedure above depends on whether tracking minor/major Astro releases and major Starlight updates is explicitly written into the scope of your maintenance contract.
Without explicit boundary wording, the moment 6.3 and 0.39 land in the same week, negotiations begin over "whether this is within scope or requires an additional quote," preventing verification from starting until resolved. Instead of having a buffer week, Week 1 melts away in contract talks. Conversely, if the scope is clearly specified, you can immediately reply that "this is covered by contract, so we will begin work this week," executing release-week preparations as scheduled.
When defining scope, two axes are particularly effective: "up to which version hierarchy" and "up to which packages." Because Starlight operates on a versioning scheme independent of core Astro, stating only "up to Astro minor versions" will leave Starlight 0.38 → 0.39 out of scope. The concurrent upgrade described in this article is only viable when both are explicitly included in scope.
While the typical market rates for running owned media are summarized in Cost Breakdown for Building Owned Media, regardless of the fee structure, incorporating "upgrades as routine recurring tasks rather than incident responses" into the contract reliably minimizes operational accidents.
CI/CD design to avoid breaking "parallel sites" all at once
When managing multiple Astro and Starlight sites for clients, scenarios where "a single dependency update fails CI across all sites" become more likely. Here is the CI/CD architecture to prevent this.
# 共通ワークフロー（GitHub Actions の例）
on:
pull_request:
paths:
- 'package.json'
- 'package-lock.json'
jobs:
build-matrix:
strategy:
fail-fast: false # 1 サイトの失敗で他を止めない
matrix:
site: [corporate, media, docs-starlight]
steps:
- uses: actions/checkout@v4
- run: npm ci --prefix sites/${{ matrix.site }}
- run: npx astro sync --root sites/${{ matrix.site }}
- run: npm run build --prefix sites/${{ matrix.site }}Configuring fail-fast: false is critical; forgetting this can cause situations where "a build failure on the corporate site halts verification on the Starlight site as well." Building a matrix that allows validating multiple sites in parallel within a single PR for a single dependency update is standard practice in custom development.
Five common pitfalls
Finally, here are common pitfalls encountered when incorporating Astro 6.3 and Starlight 0.39 into client projects.
Pitfall 1: Upgrading both on the same day
Bundling both updates into a single PR creates a situation where "you cannot isolate the cause of failures." Staggering them by at least one week is an ironclad rule.
Pitfall 2: Hosting environment failures caused by AVIF defaults
If AVIF is missing from Cloud Storage or CDN Content-Type mappings, "images may fail to display." Check hosting-side MIME type settings first.
Pitfall 3: Overlooking diffs in Starlight's automatic sidebar generation
Changes to sidebar ordering lower documentation completion rates; therefore, always run and verify snapshot tests under astro:assets.
Pitfall 4: Neglecting default URL changes in i18n
Starlight 0.39 alters URL handling for multilingual default locales. Because cases arise where paths previously served at / shift to /ja/, always configure redirect rules.
Pitfall 5: Not testing View Transitions session controls
Astro 6.3 expands the session control API for View Transitions. Even when you think it was not implemented, remnants may linger in Layout files, so always eliminate warnings emitted by astro check.
Conclusion — Stop aligning upgrades to the exact same week
Simultaneous releases like Astro 6.3 and Starlight 0.39 will continue to land in the "same week" going forward. Simply establishing an operational rule to "upgrade the core framework and plugins or themes on separate weeks" will reliably drive down incident rates in custom maintenance.
Because our own corporate site runs on Astro, whenever a "de facto quarterly major-equivalent release" like 6.3 arrives, we experience firsthand what requires visual inspection and where to allocate buffers. However, because the workload and sequence vary depending on how many Astro sites exist, how heavily themes and plugins have been customized, and the degree of CI automation, there is no single template for planning updates. If you are at a stage where you want to "draft an update plan including the sequence for Astro and Starlight" or "clarify what is covered under your current maintenance contract," please contact us via our contact form.
