Update v7 upgrade guide changes by matthewp · Pull Request #13944 · withastro/docs

matthewp · 2026-05-27T16:13:53Z

Adds missing sections to the v7 upgrade guide:

Experimental Flags: Consolidated section (matching v5/v6 pattern) covering rustCompiler, advancedRouting, and routeCaching flag removal
Reserved file name: src/app.ts: Documents that src/app.ts is now reserved for advanced routing, with instructions to rename or set fetchFile: null
Removed: @astrojs/db: Documents the package removal with alternatives (Node.js built-in node:sqlite, Drizzle ORM, other database libraries)

…removal

netlify · 2026-05-27T16:13:59Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`65a635c`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a173da3702d5d0008a51fcf
😎 Deploy Preview	https://deploy-preview-13944--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

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

astrobot-houston · 2026-05-27T16:14:33Z

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/upgrade-to/v7.mdx	Localization changed, will be marked as complete.
en/reference/advanced-routing.mdx	Localization added, will be marked as complete.
en/reference/content-loader-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/modules/astro-content.mdx	Source changed, localizations will be marked as outdated.
en/reference/route-caching.mdx	Localization added, will be marked as complete.
fr/reference/advanced-routing.mdx	Localization added, will be marked as complete.
fr/reference/content-loader-reference.mdx	Localization changed, will be marked as complete.
fr/reference/modules/astro-content.mdx	Localization changed, will be marked as complete.
ko/reference/advanced-routing.mdx	Localization added, will be marked as complete.
ko/reference/content-loader-reference.mdx	Localization changed, will be marked as complete.
ko/reference/modules/astro-content.mdx	Localization changed, will be marked as complete.
zh-cn/reference/content-loader-reference.mdx	Localization changed, will be marked as complete.
zh-cn/reference/modules/astro-content.mdx	Localization changed, will be marked as complete.

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.

- Move reference/experimental-flags/advanced-routing.mdx to reference/advanced-routing.mdx - Move reference/experimental-flags/route-caching.mdx to reference/route-caching.mdx - Remove experimental references from both pages (titles, config examples, text) - Update sidebar: remove from experimental group, add to reference/other - Update EN internal links in upgrade guide, astro-content, content-loader-reference

ArmandPhilippot

The upgrade guide looks to me!

I'll just note that usually we add the breaking changes once the current release no longer supports them. That's why I still haven't merged #13886 (withastro/astro#16749 is not merged yet). Are we sure advanced routing stabilization, route caching stabilization and @astrojs/db removal will be released at the same time?

However, for the pages that are no longer experimental, I think this requires more work. Some contents sound more like a guide than a reference or belong to another page (e.g. render context). I left a few comments to illustrate my thinking.

Also, we'll need to replace the content of https://docs.astro.build/en/guides/integrations-guide/db/ (probably with something similar to https://docs.astro.build/en/guides/integrations-guide/lit/).

And regarding the translations:

We usually remove the translations for experimental flags when they are stabilized instead of renaming them because we do not accept AI translations (at least not reviewed thoroughly by a native speaker).

I know there are not many changes (yet 😄 ) but I can see a few things that are wrong with the French translation of Advanced routing (we still have a few experimental, the non breaking spaces were intentional, and at least one sentence is missing a verb now).

I suspect this might be the same for the Korean translation, and so in any case we'll need a Lunaria directive to not track them.

So, I think it's easier to just remove the translations? I mean:

it's quite easy to retrieve the deleted file content from the Git history, so translators do not have to retranslate everything.
if we dispatch the existing content, keeping the translations no longer makes sense.

I can help with the changes if you want! (probably next week, though) But, because this means more changes it might be easier to review with a separate PR for each.

ArmandPhilippot · 2026-05-28T15:34:20Z

+				'reference/container-reference',
+				'reference/programmatic-reference',
+				'reference/advanced-routing',
+				'reference/route-caching',


We usually keep the experimental API at the end:

Suggested change

'reference/container-reference',

'reference/programmatic-reference',

'reference/advanced-routing',

'reference/route-caching',

'reference/advanced-routing',

'reference/route-caching',

'reference/container-reference',

'reference/programmatic-reference',

ArmandPhilippot · 2026-05-28T16:03:33Z

+title: Route caching
 sidebar:
  label: Route caching
 i18nReady: false


Ah, that explains why there were no translations! Well, we want this to be translated now this is stable:

Suggested change

i18nReady: false

i18nReady: true

ArmandPhilippot · 2026-05-28T16:12:23Z

@@ -1,5 +1,5 @@
 ---
-title: Experimental route caching
+title: Route caching


consistency nit: the other items are all suffixed by API, so it looks a bit odd that two of them are not.

Suggested change

title: Route caching

title: Route caching API

But, maybe this should be something like:

Suggested change

title: Route caching

title: Cache provider API

Because some contents require a reorganization: some sections belongs to Render context reference and maybe to the Routing guide. And this page could end up talking only about cache providers.

ArmandPhilippot · 2026-05-28T16:12:34Z

@@ -1,5 +1,5 @@
 ---
-title: Experimental advanced routing
+title: Advanced routing


consistency nit: the other items are all suffixed by API, so it looks a bit odd that two of them are not.

Suggested change

title: Advanced routing

title: Advanced routing API

But, I wonder if this shouldn't be a guide (maybe in Routing) rather than a reference? Except "astro/fetch handler reference" which I think makes sense to have next to the other Runtime APIs (astro/app, astro/zod, etc.)

ArmandPhilippot · 2026-05-28T16:21:33Z

 });
 ```

 ## Using route caching


I wonder if this section shouldn't be moved to the Routing guide with maybe a link in the Endpoints guide.

ArmandPhilippot · 2026-05-28T16:31:44Z


 Per-route `cache.set()` calls merge with config-level route rules. Route code can override or extend the defaults set in config.

 ## Cache providers


I think it's the true reference for route caching, in the same way as Font Provider and Session Driver.

ArmandPhilippot · 2026-05-28T16:33:36Z

 ## Error handling

 ### `CacheNotEnabled`

 Thrown when `cache.invalidate()` is called without a configured cache provider. Other cache methods (`set()`, `tags`, `options`) no-op when caching is not configured, logging a one-time warning on the first `set()` call.

 ### `CacheProviderNotFound`

 Thrown at build time when the configured cache provider cannot be resolved. This typically means the package is not installed or the import path is incorrect.


I'm not sure this is relevant to keep that since we already have Cache errors reference.

ArmandPhilippot · 2026-05-28T16:33:52Z

 ## Further reading

 For full details and to give feedback on this experimental API, see the [Route Caching RFC](https://github.com/withastro/roadmap/pull/1245).


We no longer need this.

ArmandPhilippot · 2026-05-28T16:42:57Z

+
+#### What should I do?
+
+If you have an existing `src/fetch.ts` file that is not related to advanced routing, you have two options:


nit: it seems there are three options (rename the existing file, disable, or choose another name for Astro fetch file)

Suggested change

If you have an existing `src/fetch.ts` file that is not related to advanced routing, you have two options:

If you have an existing `src/fetch.ts` file that is not related to advanced routing, you have three options:

ArmandPhilippot · 2026-05-28T16:44:25Z

+});
+```
+
+You can also point `fetchFile` to a different file name if you want to use advanced routing but need to keep `src/fetch.ts` for another purpose:


And because we use bold for the first two options, maybe this should be also be in bold:

Suggested change

You can also point `fetchFile` to a different file name if you want to use advanced routing but need to keep `src/fetch.ts` for another purpose:

**Configure `fetchFile` with a different file name** if you want to use advanced routing but need to keep `src/fetch.ts` for another purpose:

Update v7 upgrade guide: experimental flags, src/app.ts, @astrojs/db …

7ac3b4b

…removal

matthewp marked this pull request as draft May 27, 2026 16:19

matthewp changed the title ~~Update v7 upgrade guide: experimental flags, src/app.ts, @astrojs/db removal~~ Update v7 upgrade guide changes May 27, 2026

matthewp added 2 commits May 27, 2026 12:33

Move translated advanced-routing.mdx out of experimental-flags (fr, ko)

da64684

github-actions Bot added the i18n Anything to do with internationalization & translation efforts - ask @YanThomas for help! label May 27, 2026

Fix broken route-caching links in translated files (fr, ko, zh-cn)

5098e61

matthewp marked this pull request as ready for review May 27, 2026 17:58

rename src/app.ts to src/fetch.ts

65a635c

ArmandPhilippot reviewed May 28, 2026

View reviewed changes


		Per-route `cache.set()` calls merge with config-level route rules. Route code can override or extend the defaults set in config.

		## Cache providers

		## Further reading

		For full details and to give feedback on this experimental API, see the [Route Caching RFC](https://github.com/withastro/roadmap/pull/1245).


		#### What should I do?

		If you have an existing `src/fetch.ts` file that is not related to advanced routing, you have two options:

	You can also point `fetchFile` to a different file name if you want to use advanced routing but need to keep `src/fetch.ts` for another purpose:
	Configure `fetchFile` with a different file name if you want to use advanced routing but need to keep `src/fetch.ts` for another purpose:

Uh oh!

Conversation

matthewp commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented May 27, 2026 • 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 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

matthewp commented May 27, 2026 •

edited

Loading

netlify Bot commented May 27, 2026 •

edited

Loading

astrobot-houston commented May 27, 2026 •

edited

Loading