Upgrading My 'hybrid' Website to Astro v5: The Ins and Outs

#Intro

In the early Dec 2024, Astro announced that its newer major version 5.0.0 was finally released, which has been a year since the last major upgrade.
For most people, that might sound like something happened on the other side of the earth and therefore not interesting...But I'm not one of them. As a matter of fact, this website is built using Astro.

I read through some release notes and the likes, and then started working on the migration fully prepared.
Here's the ins and outs of the whole experience.

#Reader personas

• Thinking about migrating to the v5 for one's Astro project
• Want to refer to as one example of Astro projects with partial SSR
• Not sure what you're talking about but will see your efforts throught to the end

#My proficiency level

As of the day I'm writing this article, my proficiency level in this field is as follows:

• Have been around Astro for about two years
• Have been using Astro since the v3

#Main

As to my old astro.config.{js,mjs,ts}, here are some notable points:

• The Cloudflare adapter is added because I partially use SSR in my website
• The rendering mode is output: "hybrid"

Along the way, I consulted the official doc below.

Upgrade to Astro v5 How to upgrade your project to Astro v5.0.

docs.astro.build

#Where do "hybrid" citizens go?

First off, changes made to the aforementioned astro.config.{js,mjs,ts} file.

Since the v5, output: "hybrid" has been removed. The hybrid option enabled people to get the best of both worlds: SSR and SSG. By doing so, it bailed someone like me out, who's incessantly going back and forth between "dynamic" and "static".
Now you have only two options to choose from, "static" or "server"; the "hybrid" option was sort of absorbed into "static".

This means we the "hybrid" citizens will have to migrate to "static" but be able to continue life as usual.

Incidentally, it'll automatically be set to output: "static" if you don't specify explicitly.

So I tweaked the config like this:

1
import cloudflare from '@astrojs/cloudflare';
2
/* ... */
3

4
export default defineConfig({
5
  output: 'hybrid',
6
  adapter: cloudflare({
7
    platformProxy: {
8
      enabled: true,
9
      persist: true,
10
    },
11
  }),
12
  /* ... */
13
})

#Anecdote: "server" mode in the build log

That's all for fixing around rendering mode, but here's one particular thing I encountered.

One day, I was leaning back in the chair and absent-mindedly looking at a waterfall of build log traversing on the monitor. At that moment, I spotted something unbelievable──output: "server". ¹ I was taken aback for a moment, but after a while, the build of prerendered pages started as if nothing happened. "What was that..?"

Consulting the source code of the Cloudflare adapter, that seems to be working properly.
Come to think of it, the log I witnessed was merely the output of what the adapter specified as an Astro integration; given that adapters play a role in bridging between Astro projects that need SSR and hosting services, it's quite plausible that it reads out loud, "We are working in...'server' mode!!!" And then the whole build process is "static" in and of itself once it passes through the server tunnel.

Long story short, you don't have to worry about the output: "server" log. Reducing the modes down to two sounds refreshing but I can't help feeling like "Is it, in some parts, even more confusing..?"

#Content Collections change to Content Layer

In the upgrade, this is the toughest part.
It's not some "tried to make it sound a bit cooler!" sort of half-hearted change whatsoever. Here perfected the destroyer. ²

#config changes to content.config

First thing first, the name and the location of the content's definition file have changed.

• Before v5: src/content/config.ts (in the same directory as content)
• After v5: src/content.config.ts (under the src directory)

#IN: loader, OUT: type

Secondly, the way you define content collections has been breaking-changed; the properties of the object passed onto the defineCollection function must be as follows now:

1
import { defineCollection, reference, z } from 'astro:content';
2
import { glob } from 'astro/loaders';
3

4
const blog = defineCollection({
5
  type: 'content',
6
  loader: glob({ pattern: '**/*.mdx', base: './src/content/blog' }),
7
  schema: z.object({
8
    title: z.string(),
9
    description: z.string().optional(),
10
    publishedAt: z.coerce.date(),
11
    updatedAt: z.coerce.date().optional(),
12
    category: z.object({
13
      metadata: reference('categories'),
14
      slug: z.string(),
15
    }),
16
    tags: z.object({
17
      metadata: reference('tags'),
18
      slugList: z.array(z.string()).optional(),
19
    }),
20
    draft: z.enum(['draft', 'in progress', 'published']),
21
    level: z
22
      .union([
23
        z.literal(1),
24
        z.literal(2),
25
        z.literal(3),
26
        z.literal(4),
27
        z.literal(5),
28
      ])
29
      .optional(),
30
    thumbnail: z.string().optional(),
31
  }),
32
});
33

34
const taxonomySchema = z.object({
35
  title: z.string(),
36
  slug: z.string(),
37
  ruby: z.string(),
38
});
39

40
const categories = defineCollection({
41
  type: 'data',
42
  loader: glob({
43
    pattern: '**/*.{yml,yaml}',
44
    base: './src/content/categories',
45
  }),
46
  schema: z.array(taxonomySchema),
47
});
48

49
const tags = defineCollection({
50
  type: 'data',
51
  loader: glob({ pattern: '**/*.{yml,yaml}', base: './src/content/tags' }),
52
  schema: z.array(taxonomySchema),
53
});
54

55
/* ... */
56

57
export const collections = { blog, categories, tags, /* ... */ };

The conventional type: 'content' | 'data' property becomes deprecated and you're now supposed to specify content's paths by using functions called glob & file.

#slug changes to id

Lastly, the content's property to access its slug has changed; it's changed from slug to id.

Let's say you want to display the above-mentioned blog content on each page using the dynamic routing. To do so, you need to set page paths like src/pages/blog/[id].astro instead of src/pages/blog/[slug].astro with the v5. Coupled with the modification, I fixed my pages like this:

1
---
2
import { render } from 'astro:content';
3
import BlogLayout from '@/layouts/BlogLayout.astro';
4
import { getSortedContentEntries } from '@/lib/collections/contents';
5
import { mdxComponents } from '@/lib/mdx-components';
6
import { getSlugWithoutLocale } from '@/utils/get-slug-without-locale';
7
import { getIdWithoutLocale } from '@/utils/get-id-without-locale';
8
import { defaultLocale } from '@/utils/i18n/data';
9
import type { GetStaticPaths } from 'astro';
10

11
export const getStaticPaths = (async () => {
12
  const entries = await getSortedContentEntries('blog', defaultLocale);
13

14
  return entries.map((entry) => {
15
    const slug = getSlugWithoutLocale(entry.slug);
16
    const id = getIdWithoutLocale(entry.id);
17

18
    return { params: { slug }, props: { entry } };
19
    return { params: { id }, props: { entry } };
20
  });
21
}) satisfies GetStaticPaths;
22

23
const { entry } = Astro.props;
24
const { Content, headings } = await render(entry);
25
---
26

27
<BlogLayout entry={{ ...entry }} {headings}>
28
  <Content components={mdxComponents} />
29
</BlogLayout>

However, in terms of naming, "slug" is better than "id" in some cases. Blog, for instance, is a case in point where many people might think src/pages/blog/[slug].astro makes more sense.
In that case, you can handle it like this:

1
---
2
import { getSortedContentEntries } from '@/lib/collections/contents';
3
import { getIdWithoutLocale } from '@/utils/get-id-without-locale';
4
import { defaultLocale } from '@/utils/i18n/data';
5
import type { GetStaticPaths } from 'astro';
6
/* ... */
7

8
export const getStaticPaths = (async () => {
9
  const entries = await getSortedContentEntries('blog', defaultLocale);
10

11
  return entries.map((entry) => {
12
    const id = getIdWithoutLocale(entry.id);
13

14
    return { params: { slug: id }, props: { entry } };
15
  });
16
}) satisfies GetStaticPaths;
17

18
/* ... */
19
---
20

21
{/* ... */}

#render is independent of content

The render method's become a function independent of content.

1
---
2
import { render } from 'astro:content';
3
import BlogLayout from '@/layouts/BlogLayout.astro';
4
import { getSortedContentEntries } from '@/lib/collections/contents';
5
import { mdxComponents } from '@/lib/mdx-components';
6
import { getIdWithoutLocale } from '@/utils/get-id-without-locale';
7
import { defaultLocale } from '@/utils/i18n/data';
8
import type { GetStaticPaths } from 'astro';
9

10
export const getStaticPaths = (async () => {
11
  const entries = await getSortedContentEntries('blog', defaultLocale);
12

13
  return entries.map((entry) => {
14
    const id = getIdWithoutLocale(entry.id);
15

16
    return { params: { id }, props: { entry } };
17
  });
18
}) satisfies GetStaticPaths;
19

20
const { entry } = Astro.props;
21
const { Content, headings } = await entry.render();
22
const { Content, headings } = await render(entry);
23
---
24

25
<BlogLayout entry={{ ...entry }} {headings}>
26
  <Content components={mdxComponents} />
27
</BlogLayout>

#Changes in how to handle env.d.ts

Before the v5, src/env.d.ts was required for type inferencing and module definitions of automatically generated types. But now, from the v5, it's not necessarily required.

The conventional src/env.d.ts file requires the following lines but from the v5, Astro seems to use .astro/types.d.ts for type inferencing directly.

1
/// <reference path="../.astro/types.d.ts" />
2
/// <reference types="astro/client" />
3

4
// Hereafter, add your custom type definitions if you have.

Accordingly, I added the following change to benefit from type inference in dev mode.

1
{
2
  "$schema": "https://json.schemastore.org/tsconfig",
3
  "extends": "astro/tsconfigs/strictest",
4
  "compilerOptions": {
5
    /* ... */
6
  },
7
  "include": [
8
    ".astro/types.d.ts",
9
    "**/*"
10
  ],
11
  "exclude": [
12
    "./dist",
13
    "./node_modules",
14
  ],
15
}

That said, src/env.d.ts is still necessary in my case because custom type definitions of Cloudflare Turnstile and D1 database are added to it. In such a case and for a project without tsconfig.json, it's still required.
That's the reason why I said earlier "it's not necessarily required" in a roundabout way.

#Outro

It took me longer than I expected.
I didn't mention this above but spent the better part of the time working on introducing "the Server Islands" feature that's another signature one officially added from the v5. It didn't work well and I gave up in the end though. (That's why I didn't mention)

Honestly, I haven't seen any outstanding benefits from the upgrade so far. Hoping to catch a glimpse of Astro v5 the destroyer working in its element someday along my dev journey.