Astro 4.0 breaking changes tracker

[sarah11918]

📋 Explain your issue

This issue is to track 4.0 breaking changes to be part of the guide.

You know the drill, use the following template:

### [changed/removed/added/deprecated] feature/name/title/description
In Astro v3.x, [ a statement in the past tense about what Astro did/used to do. 
e.g.  bundled all assets into several different folders....]

Astro v4.0 [ a statement in the present tense about how Astro works now.
e.g. now bundles all assets into one single folder located in... ]

#### What should I do?
[Active sentences in the imperative (command) tense, with code examples showing diffs as appropriate]
e.g. Update... / Remove... / Replace... / Create..

PR: #9999 (implementation)
PR: #5555 (docs, if appropriate)

Example upgrade guide: https://docs.astro.build/en/guides/upgrade-to/v3/

EMOJI LEGEND
👍 - this has been added to our Astro 4.0 Upgrade Guide #5481
😄 - NO CORRESPONDING DOCS CHANGES NEEDED
🚀 - Docs need updating because of this change
🎉 - Docs PR for needed changes exists
👎 - Not actually a BREAKING change! Doesn't need to be listed in the guide!

[bluwy]

Updated Vite to 5.0

In Astro v3.0, it uses Vite 4 as the development server and bundler.

Astro v4.0 updates it to Vite 5.

What should I do?

Check the Vite migration guide for the breaking changes and migrate over as needed. There are no breaking changes from Astro itself.

PR: withastro/astro#9122 (implementation)
PR: n/a (docs, if appropriate)

[bluwy]

Updated all unified, remark, and rehype dependencies

In Astro v3.x, unified v10 and its related compatible remark/rehype packages were used to process markdown and MDX.

Astro v4.0 upgrades unified to v11 and the other remark/rehype packages to latest.

What should I do?

If you used custom remark/rehype packages, update all of them to latest to ensure they support unified v11. There should not be any significant breaking changes, but make sure to double-check your markdown/MDX pages before deploying.

PR: withastro/astro#9138 (implementation)
PR: n/a(docs, if appropriate)

[bluwy]

Renamed injected route entryPoint property to entrypoint

In Astro v3.x, the injectRoute() API in integrations accepts a route object with the entryPoint property to specify the route entry point.

Astro v4.0 renames it to entrypoint to be consistent with other Astro APIs. The entryPoint property is deprecated, but will continue to work and logs a warning if specified.

What should I do?

If you have integrations that use the injectRoute API, rename the entryPoint property to entrypoint. If you're a library author who wants to support both Astro 3 and 4, you can specify both entryPoint and entrypoint, which a warning will not be logged.

PR: withastro/astro#9161 (implementation)
PR: #5475 (docs)

[bluwy]

Removed support for returning simple objects from endpoints

In Astro v3.x, returning simple objects from endpoints was deprecated but still supported for compatibility with Astro v2. A ResponseWithEncoding utility was also provided to ease the migration.

Astro v4.0 removes support for it and requires endpoints to always return a Response. The ResponseWithEncoding utility is also removed in favour of a proper Response type.

What should I do?

Update your endpoints to return a Response object directly.

export async function GET() {
  return { body: { "title": "Bob's blog" }};
  return new Response(JSON.stringify({ "title": "Bob's blog" }));
}

Copied the above from https://docs.astro.build/en/guides/upgrade-to/v3/#deprecated-returning-simple-object-in-endpoints, should we do a link only instead?

To remove usage of ResponseWithEncoding, refactor your code to use an ArrayBuffer instead:

export async function GET() {
  const file = await fs.readFile('./bob.png');
- return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
+ return new Response(file.buffer);
};

PR: withastro/astro#9181 (implementation)
PR: n/a (docs, if appropriate)

[bluwy]

Removed deprecated features from Astro v3

In Astro v3.x:

• Adapters didn't have to pass the supportedAstroFeatures option
• build.split and build.excludeMiddleware were deprecated
• markdown.drafts was deprecated
• Lowercase endpoint names were deprecated
• getHeaders() exported from markdown files was deprecated

Astro v4.0 removes the deprecated features:

• Adapters need to pass the supportedAstroFeatures option
• build.split and build.excludeMiddleware are removed
• markdown.drafts is removed
• Lowercase endpoint names are not supported
• getHeaders() exported from markdown files is removed

What should I do?

• Adapter authors need to pass the supportedAstroFeatures option to specify a list of features they support. If this was not set before, you can pass supportedAstroFeatures: {}.
• For build.split and build.excludeMiddleware options, use functionPerRoute and edgeMiddleware from adapters instead. (v3 migration guide)
• For markdown.drafts, use content collections instead. (v3 migration guide)
• Use uppercase endpoint names instead. (v3 migration guide)
• For getHeaders() exported from markdown files, use the exported getHeadings() API instead

PR: withastro/astro#9168 (implementation)
PR: n/a. might need to double check the docs to not use these deprecated features (docs, if appropriate)

Kevin - Docs suggested edits: (Thanks Kevin, these are all covered in the implementation PR!)

• https://docs.astro.build/en/reference/configuration-reference/#buildsplit
• https://docs.astro.build/en/reference/configuration-reference/#buildexcludemiddleware
• https://docs.astro.build/en/reference/configuration-reference/#markdowndrafts

[bluwy]

Removed Shiki language path property support

In Astro v3.x, a Shiki language passed to markdown.shikiConfig.langs will be automatically converted to a Shikiji-compatible language. Shikiji is the internal tooling used by Astro for syntax highlighting.

Astro v4.0 removes partial compatibility support for the path property of a Shiki language. This path property used to resolve from <root>/node_modules/astro which can be confusing to configure, hence its support is removed.

What should I do?

The language JSON file should be imported and passed to the option instead.

// astro.config.js
+ import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
-       { path: '../../custom.tmLanguage.json' },
+       customLang,
      ],
    },
  },
})

PR: withastro/astro#9196 (implementation)
PR: TBA (docs, if appropriate)

[lilnasy]

Integration API: Switched app.render signature

The app.render() method of the App class has been simplified.

Instead of two optional arguments, it now takes a single optional argument that is an object with two optional properties: routeData and locals.

What should I do?

If you are not maintaining an adapter, nothing.

The current signature is deprecated but will continue to function until next major version. To move to the new signature, pass routeData and locals as properties of an object instead of as multiple independent arguments.

 app.render(request)

- app.render(request, routeData)
+ app.render(request, { routeData })

- app.render(request, routeData, locals)
+ app.render(request, { routeData, locals })

- app.render(request, undefined, locals)
+ app.render(request, { locals })

• PR: Switch app.render signature astro#9199
• Docs: Adapter API reference: signature change in a function #5510

[natemoo-re]

Added astro preferences to the CLI

Astro v4.0 adds the astro preferences command to manage user preferences. User preferences are specific to individual Astro users, unlike the astro.config.mjs file which changes behavior for everyone working on a project.

What should I do?

In order to disable the new dev overlay for the current Astro project, run the following command:

astro preferences disable devOverlay

In order to disable the dev overlay for every project on your machine, run the following command:

astro preferences --global disable devOverlay

In order to re-enable the dev overlay, run the following command:

astro preferences enable devOverlay

PR: #9115 (implementation)
PR: #5512 (docs)

[natemoo-re]

View Transitions: handle submit events by default

In Astro v3.x, projects using the <ViewTransitions /> component were required to opt-in to handling submit events for form elements. This was done by passing a handleForms prop.

Astro v4.0 handles submit events for form elements by default when <ViewTransitions /> are used. The handleForms prop has been deprecated and no longer has any effect.

What should I do?

Remove the handleForms property from your ViewTransitions component.

To opt-out of submit event handling, add the data-astro-reload attribute to relevant form elements.

PR: #9225
Docs: #5540

[bluwy]

Followup additional deprecations from #5390 (comment)

NOTE: The first and second bullet points are kinda small to mention in the migration guide, but I left it here anyways in case you think we should document still.

Removed deprecated features from Astro v3

In Astro v3.x:

• The Astro preview server returned a 301 redirect when accessing the public directory assets without a base path.
• The astro/client-image type is removed but is auto-converted to astro/client if used in your env.d.ts file.
• The rss helper in getStaticPaths exists but will error if used.
• The Astro.request.params API is preserved for backwards compatibility.

Astro v4.0 removes the deprecated features:

• The Astro preview server will return a 404 status instead.
• If astro/client-image is used, it will be ignored.
• The rss helper no longer exists.
• The Astro.request.params API is removed.

What should I do?

• When using the Astro preview server, make sure you're accessing public directory assets with the base prefixed to the path. If the base path is missing, you should also see the issue when running the dev server.
• Do not use the astro/client-image type, use astro/client instead.
• Use the @astrojs/rss integration for a complete RSS setup instead.
• Use the Astro.params API instead, which works the same way as Astro.request.params.

PR: withastro/astro#9263 (implementation)
PR: n/a (docs, if appropriate)

[sarah11918]

As of this moment, everything added here is represented in the migration guide! 🥳

I will merge the guide early, but not link to it until Tuesday. After merging, it will be available directly at https://docs.astro.build/en/guides/upgrade-to/v4/ for preview and checking. It can still be changed! But I expect changes to be minor at that point, and individual PRs to update will be fine.