Blog Underlying Stack Update Log

A few days ago, in a moment of madness and boredom, I suddenly wanted to update the underlying libraries of this blog. Plus, being someone who is purely idle and loves chasing the latest versions, this is just a write-up of my own notes. (The page is written very simply, for reference only — update with caution.)

It also happens to be the blog’s first anniversary, so consider this a “birthday celebration 😂”

First, the previous situation: it was an Astro 5 + Tailwind 3 + DaisyUI 4 architecture, and after the upgrade it became Astro 7 + Tailwind 4 + DaisyUI 5, with all the Astro companion components on the latest version. But note that when I was writing this, TypeScript 7 still didn’t support Astro, so I only used the latest TypeScript 6.

Let me mention the browser compatibility issues the update causes: Tailwind v4 requires Chrome ≥111, Edge ≥111, Firefox ≥128, Safari ≥16.4; the update will break compatibility on older devices.

Update Begins

Simple Version Update

package.json

1
// Added dependencies
2
 "@astrojs/markdown-remark": "^7.2.2"     // standalone markdown processing
3
 "@iconify/tailwind4": "^1.2.3"           // Tailwind 4 version of Iconify
4
 "@tailwindcss/vite": "^4.3.3"            // Tailwind Vite plugin (replaces @astrojs/tailwind)
5

6
// Removed dependencies
7
 "@astrojs/tailwind": "^6.0.2"            // no longer needed
8
 "@iconify/tailwind": "^1.2.0"            // replaced with the tailwind4 version
9
 "@typescript-eslint/parser": "^8.48.1"   // no longer needed
10
 "sass-embedded": "^1.93.3"               // SCSS → CSS migration
11
 "medium-zoom": "^1.1.0"                  // removed
12
 "remark": "^15.0.1"                      // replaced by @astrojs/markdown-remark
13

14
 "typescript": "^5.9.3"
15
 "typescript": "^6.0.3"
16

17
// Everything else is a direct version bump

pnpm-workspace.yaml

1
allowBuilds:
2
  sharp: true
3
  swup: false
4
 unrs-resolver: true   // required by Astro 7

astro.config.mjs Astro config migration

1
 import tailwind from "@astrojs/tailwind";
2
 const playformCompress = (await import("@playform/compress")).default; // sync import
3
 import tailwindcss from "@tailwindcss/vite";   // Tailwind 4 uses the Vite plugin
4
 import { unified } from "@astrojs/markdown-remark";  // standalone markdown processor
5

6
export default defineConfig({
7
  integrations: [
8
    // ... other integrations
9
   tailwind({
10
     configFile: "./tailwind.config.mjs",
11
   }),
12
   // Tailwind 4 no longer needs an integration
13
   playformCompress(),
14
   playformCompress({
15
     Image: false,        // must disable, sharp version incompatible
16
     JavaScript: false,   // JS handled by terser
17
   }),
18
  ],
19
  markdown: {
20
   remarkPlugins: [...],
21
   rehypePlugins: [...],
22
   processor: unified({    // new markdown processor API
23
     remarkPlugins: [...],
24
     rehypePlugins: [...],
25
   }),
26
  },
27
  vite: {
28
   plugins: [tailwindcss()],  // Tailwind 4 Vite plugin
29
    build: {
30
     cssMinify: "esbuild",    // required! lightningcss doesn't support @apply
31
    },
32
   css: {
33
     preprocessorOptions: {
34
       scss: { api: "modern-compiler" },  // remove SCSS config
35
     },
36
   },
37
  },
38
 style: {
39
   scss: {
40
     includePaths: ["./src/styles"],  // remove SCSS config
41
   },
42
 },
43
});

• cssMinify: "esbuild": This is a mandatory option for the Tailwind 4 migration. Vite uses lightningcss to minify CSS by default, but it doesn’t recognize Tailwind’s @apply directive and will output about 120+ warnings. esbuild stays silent on unknown at-rules.
• @playform/compress Image disabled: The bundled sharp 0.34.5 throws a colourspace: parameter space not set error when processing PNGs without an ICC profile. It’s recommended to pre-optimize images in the project, so no second compression is needed.
• @playform/compress JavaScript disabled: JS minification is already handled by @rollup/plugin-terser, avoiding duplicate processing.

Tailwind 4 switches to a CSS-first configuration and no longer needs tailwind.config.mjs: it’s recommended to refer to the Tailwind 4 official upgrade guide↗, which includes an update plugin that can theoretically save you some of the deprecated/modified CSS style adaptations (mentioned later).

1
// delete tailwind.config.mjs
2
 /** @type {import('tailwindcss').Config} */
3
 export default {
4
   content: ["./src/**/*.{astro,html,js,md,mdx,svelte,ts,tsx,vue}"],
5
   plugins: [daisyUI, typography, addDynamicIconSelectors()],
6
   daisyui: {
7
     themes: ["winter", "night"],
8
     darkTheme: "night",
9
     logs: false,
10
   },
11
 };

Create src/styles/tailwind.css

1
@import "tailwindcss";
2
@import "./global.css";   /* import custom global styles */
3

4
@theme {
5
  --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
6
}
7

8
@plugin "@tailwindcss/typography";
9
@plugin "@iconify/tailwind4";
10
@plugin "daisyui" {
11
  themes: winter --default, night --prefersdark;
12
  logs: false;
13
}

1. @theme directive replaces theme.extend — custom theme values are defined in the @theme block
2. @plugin directive replaces plugins: [...] — Tailwind plugins are imported via @plugin
3. No content config needed — Tailwind 4 auto-detects template files
4. @import replaces @tailwind base/components/utilities

DaisyUI config changes

1
// DaisyUI v4 (tailwind.config.mjs)
2
 daisyui: {
3
   themes: ["winter", "night"],
4
   darkTheme: "night",
5
   logs: false,
6
 }
7

8
// DaisyUI v5 (tailwind.css)
9
@plugin "daisyui" {
10
  themes: winter --default, night --prefersdark;
11
  logs: false;
12
}

Some breaking changes; see the official docs↗ for more.

• Many component style behaviors changed subtly in DaisyUI 5; each component needs to be checked individually

Detailed Update Adaptations

Content Layer API changes

Astro 7’s Content Layer API is significantly different from Astro 5’s.

Create src/content.config.ts; you can directly rename the original src/content/config.ts for clarity.

1
import { defineCollection } from "astro:content";
2
import { z } from "astro/zod";
3
import { glob } from "astro/loaders";
4

5
const blog = defineCollection({
6
  loader: glob({
7
    pattern: ["**/*.{md,mdx}"],
8
    base: "./src/content/blog",
9
  }),
10
  schema: z.object({
11
    title: z.string(),
12
    description: z.string(),
13
    pubDate: z.coerce.date(),
14
    updated: z.coerce.date().optional(),
15
    // ... other fields
16
  }),
17
});
18

19
export const collections = { blog };

Code migration example

1
 import { getCollection } from "astro:content";
2
 import { getCollection, render } from "astro:content";
3

4
// slug → id
5
 <a href={`/blog/${post.slug}`}>
6
 <a href={`/blog/${post.id}`}>
7

8
// render() call
9
 const { Content } = await blog.render();
10
 const { Content } = await render(blog);
11

12
// getStaticPaths
13
 params: { slug: blog.slug },
14
 params: { slug: blog.id },

CSS System Migration: SCSS → Tailwind CSS

The project originally used SCSS (global.scss) and now migrates to plain CSS (global.css), leveraging Tailwind 4’s @apply + CSS nesting.

File structure changes

1
src/styles/global.scss   (719 lines, SCSS)
2
tailwind.config.mjs      (JS config)
3
src/styles/global.css    (1207 lines, plain CSS)
4
src/styles/tailwind.css  (Tailwind 4 entry)

1. @tailwind directive removed — global styles no longer need @tailwind base/components/utilities
2. SCSS feature replacements:
   • @mixin / @include → CSS @layer + reusable classes
   • $variable → CSS custom property --variable
   • nested selectors → native CSS Nesting (widely supported)
3. @apply stays available — you can still use @apply in global.css

astro.config.mjs remove SCSS config (partly modified above already)

1
style: {
2
  scss: {
3
    includePaths: ["./src/styles"],
4
  },
5
},
6
vite.css.preprocessorOptions.scss: {
7
  api: "modern-compiler",
8
},

The Tailwind component switching mentioned above can theoretically be done with the official plugin, but be aware that the plugin seems to do simple search-and-replace. If you used a matching variable name in some files, it will be wrongly replaced too. It’s recommended to re-build and retry before committing.

Other

js-yaml ^4 → ^5

1
import yaml from "js-yaml";
2
import * as yaml from "js-yaml";

Waline component’s define:vars syntax change (Astro 7 doesn’t support inline referencing of Astro.props.X in define:vars)

1
serverURL: Astro.props.serverURL,
2
lang: Astro.props.lang ?? "zh",
3
// destructure first, then pass the variable name
4
const { serverURL, lang = "zh" } = Astro.props;
5
// reference the variable directly in define:vars
6
serverURL,
7
lang,

Other than that, Astro 7’s whitespace rules changed multi-line inline elements: the old version auto-generated spaces for line breaks; the new JSX-style version does not generate spaces, so inline text is directly concatenated. The most noticeable case is probably that the license author and the license name no longer have a space between them. There are other places you can adjust yourself.

Also, regarding fonts: Tailwind seems to have updated its fonts in v4 (or system fonts were moved to the front). To keep the v3 fonts, you can add the following to tailwind.css:

1
@theme {
2
  --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
3
}

One more thing: previously it seemed that md:xx lg:xx would cause some components to display with the md screen style even on the lg screen. After the update this is fixed, so the lg screen correctly displays the component style, which can make things appear a slightly different size. To preserve the old behavior you can adjust some components (I just changed lg to 2xl and it was fixed XD).

Yet another thing: you can also add to global.css:

1
@layer base {
2
    *,
3
    ::after,
4
    ::before,
5
    ::backdrop,
6
    ::file-selector-button {
7
        border-color: var(--color-gray-200, currentColor);
8
    }
9

10
    input::placeholder,
11
    textarea::placeholder {
12
        color: var(--color-gray-400);
13
    }
14
    /* (optional) cursor style for clickable elements */
15
    button:not(:disabled),
16
    [role="button"]:not(:disabled) {
17
        cursor: pointer;
18
    }
19
    /* (recommended) force uniform top/bottom margin for hr, mainly the license area */
20
    hr {
21
        margin-block: 1rem !important;
22
    }
23
}

If you updated pagefind from 1.4.0 to 1.5.x, you may also need to update the search page, which may report “Pagefind: WASM Error (No pointer)”.

1. bundlePath resolution failure: the @pagefind/default-ui package determines the location of pagefind.js by checking document.currentScript. But when loaded via dynamic import() (and since Astro bundles via Vite), document.currentScript is always null. So bundlePath becomes undefined.
2. The build output uses a wrong baseUrl: the current dist/ build passes baseUrl: "/pagefind/", which constructs wrong links like /pagefind/blog/article-path (it should use / as the baseUrl) — but this is not the root cause; the root cause is the missing bundlePath.

So the fix is:

1
const search = new PagefindUI({
2
  element: "#pagefind-search",
3
 bundlePath: "/pagefind/",
4
  showImages: false,
5
  ...
6
});

If you want, you can also migrate the pagefind default-ui to component-ui; tinker with it if you’re bored.

Postscript

Damn, after deploying the update, no matter how I refreshed it kept erroring, yet it worked fine locally. I thought it was a component issue of mine, but it turned out to be a browser cache problem. I spent a long time deleting the cache; at first I thought it was on the Vercel/Cloudflare side, but then I found that only Edge couldn’t display it properly. I fiddled with the Service Worker for a while and still couldn’t fix it, until finally I cleared everything directly in DevTools → Application → Storage and it worked. Took me a whole day…

Summary

1. Update all dependency versions in package.json
2. Update pnpm-workspace.yaml to add unrs-resolver: true
3. Run pnpm install
4. Create src/styles/tailwind.css as the Tailwind 4 entry
5. Delete tailwind.config.mjs
6. Migrate global.scss → global.css (remove @tailwind directive)
7. Update astro.config.mjs (Tailwind Vite plugin, Markdown processor, cssMinify, etc.)
8. Create src/content.config.ts
9. Batch-replace Tailwind utility classes across all .svelte and .astro files
10. Replace blog.slug → blog.id, blog.render() → render(blog)
11. Run pnpm build to verify a successful build

In closing: I’m exhausted, this was purely thankless busywork, just out of sheer idleness. My personal feeling is that the build was just a bit faster — on Vercel the original build time of two and a half minutes is now just under two minutes. But what does that have to do with me… the range of supported devices actually got smaller.

Thanks for reading! Follow me if you'd like~

Blog Underlying Stack Update Log

Thu Jul 30 2026

1729 words · 13 minutes

MusingsEssayBlog

---

© MuxiaoWF | CC BY-NC-SA 4.0

Share

Share this article

X (Twitter)TelegramRedditFacebookEmailQQ

Close

Close