Migrate Astro 5 to Astro 6 with AI Assistance

What you’ll get

You will successfully upgrade your Astro website from version 5 to version 6, resolving common issues like missing package errors with the help of an AI coding assistant. This approach is useful when facing complex upgrade paths or unexpected errors, leveraging AI to speed up the process.

Tools you need

• Astro (freemium): A web framework for building fast, content-focused websites.
• AI coding agent (freemium): A tool like ChatGPT or Claude to help diagnose and fix code errors.
• npm (free): The Node Package Manager, used for installing and managing project dependencies.
• npx (free): A package runner tool that comes with npm, used to execute npm package binaries.
• Tailwind CSS (freemium): A utility-first CSS framework.

Steps

1. Run the Astro upgrade command: Open your project’s terminal or command prompt and execute the following command to start the upgrade process:

   npx @astrojs/upgrade

   You should see output indicating the upgrade process is running and potentially listing packages being updated. The process might prompt you for confirmation.

2. Encounter and diagnose the Tailwind CSS error: After the upgrade, when you try to run your development server (e.g., npm run dev), you will likely encounter an error related to a missing tailwindcss package. The error message will be similar to “Cannot find package ‘tailwindcss’”.

   This is expected because the upgrade command might install a new version of the Tailwind CSS integration that relies on tailwindcss as a peer dependency, but doesn’t automatically install it if it’s not already a direct dependency.

3. Consult the AI coding agent: Copy the exact error message you received and paste it into your AI coding agent. Ask the agent to explain the error and suggest a fix. A good starting prompt is:

   I am upgrading my Astro site from v5 to v6 and encountered this error: [Paste your exact error message here]. What is causing this and how can I fix it, specifically regarding Tailwind CSS?

   The AI should identify the peer dependency issue. It might initially suggest incorrect solutions, like adding PostCSS without properly addressing Tailwind.

4. Instruct the AI to follow Astro documentation: If the AI’s first suggestion is not ideal or seems overly complex, guide it to use the official Astro documentation for Tailwind CSS upgrades. You can prompt it like this:

   Please check the official Astro documentation for upgrading Tailwind CSS and provide the recommended solution for Astro 6. I want to ensure I'm following best practices.

   The AI should then present options, typically involving either installing tailwindcss@3 or using the npx astro add tailwind command for newer versions.

5. Choose and apply the recommended solution (Option B): The recommended approach for Astro 6 is usually to use the official Vite plugin for Tailwind 4. Execute the following command in your terminal:

   npx astro add tailwind

   This command will update your astro.config.mjs to include the @tailwindcss/vite plugin and set up the necessary CSS file (src/styles/global.css) with the @import "tailwindcss"; directive.

6. Migrate custom theme (if applicable): If you had a custom theme in tailwind.config.mjs, you will need to migrate it to the new CSS-based configuration. The AI can help with this. Paste your existing tailwind.config.mjs content and ask the AI to convert it to the @theme block in src/styles/global.css.

   Here is my old tailwind.config.mjs:
   [Paste your tailwind.config.mjs content here]
   
   Please convert the theme configuration to the new @theme block format for Astro 6's global.css.

   You should see the theme variables defined within the @theme block in your src/styles/global.css file.

7. Verify the upgrade: After applying the changes, restart your development server (npm run dev). Your site should now load without the Tailwind CSS errors, and the styling should appear correctly.

   You should see your Astro site running with Astro 6.2 and Tailwind CSS v4 (via the Vite plugin), with your custom theme applied.

Original source

This workflow is based on a blog post by harshil1712, shared on DEV Community. The author details their real-world experience upgrading a personal website from Astro 5.x to Astro 6.x, highlighting the challenges encountered and how an AI coding assistant was used to navigate the process and find the correct solutions.

Notes & variations

• Free-tier alternative: If you prefer not to use a paid AI assistant, you can use free tiers of services like ChatGPT or Gemini. For command-line tools, all mentioned are free.
• Common pitfall: Do not blindly accept the AI’s first suggestion. Always verify its recommendations against official documentation, especially for critical steps like framework upgrades. The AI might suggest solutions that work but are not the most efficient or maintainable.
• Tip for better results: When asking the AI for help, provide as much context as possible. Include the exact error message, the relevant code snippets (like configuration files), and the versions of the tools you are using. This helps the AI generate more accurate and helpful responses.