Upgrading to Astro 3.0

Table of contents

Upgrading to Astro 3.0

Recently I became aware of, if not to say I was bombarded by videos about, Astro’s latest version 3.0. There seem to be some really cool features in there, for those who want snazzy transitions et cetera. I personally wasn’t THAT bothered by trying to add them, as I’m quite content with my light/dark mode toggle, but it’s always good practice to stay up-to-date and the image optimisation seemed relatively interesting - so why not go through the pain of upgrading my project from 2.3 to 3.0.

Steps to Upgrade

The steps are actually really easy, or at least they were for me:

npm install astro@latest
npm install @astrojs/react@latest @astrojs/tailwind@latest

By simply running these commands basically everything was done. npm did complain at me for vulnerabilities, but running a few audit commands resolved that issue. I could then run npm run start as per usual and the only difference here is that Astro has changed the default local port to 4321.

Styling Changes

It seems that by updating react and tailwind the styling of the website has changed - most notably the size/space the blog posts take up, the alignment of the navigation buttons in the header and the image outline has reappeared!

The most obvious one is the header bar, as I spent a lot of time aligning those buttons and they have now vertically aligned themselves again… A quick debugging using inspect in the browser shows that they inherit a grid property from the nav ul class, so simply removing this resolves the issue.

I believe the border issue was caused by running the npm run format linting/prettier commands which modified my base.css file:

prose-img:!mt-1 prose-img:border-2
prose-img:border-skin-line;

Specifically these lines at the bottom of .prose seem to have become un-commented while other commented variables have been moved. Again re-commenting them removes the orange borders from the images on the site.

Another thing that is slightly different are the page tags at the bottom of each page. These are used as links to filter all pages with common tags, but it seems the # character styling has changed. Going into the styling for the Tag.astro property there aren’t any changed variables and to make it slightly nicer to look at a few values can be altered to put some separation in. Below is the before and after code.

@apply -mr-5 h-6 w-6 scale-95 text-skin-base opacity-80 group-hover:fill-skin-accent;
@apply -mr-4 h-5 w-5 scale-75 text-skin-base opacity-70 group-hover:fill-skin-accent;

Finally regarding the size of the site, it doesn’t seem obvious why the width of the site has expanded. I think this is probably due to react being upgraded, but if anything it makes the site easier to read and because it has been applied universally (as far as I can tell), I am going to leave it as it is.

MDX and Image tags

The one big feature I was expecting to potentially affect me was the <Image> tag and auto image optimisation. However, what I didn’t really gleam from the youtube summaries was that the new <Image> tag is only available in .mdx and .astro files. I primarily write my blog posts in .md, so when I went to trial those features I realised that I needed to change a few things. First of all I needed to install the dependency for mdx to my astro project.

npx astro add mdx

This caused several issues when I went to run my project. So I had to re-run:

npm install @astrojs/react@latest @astrojs/tailwind@latest

npm run start

> [email protected] start
> astro dev

19:33:04 [vite] Error when evaluating SSR module C:\Users\X\Documents\blog\tim-watson\astro.config.mjs: failed to import "@astrojs/mdx"
|- Error: Cannot find module '@astrojs/mdx' imported from 'C:/Users/X/Documents/blog/tim-watson/astro.config.mjs'
    at ssrImport (file:///C:/Users/X/Documents/blog/tim-watson/node_modules/vite/dist/node/chunks/dep-df561101.js:55912:30)
    at eval (C:/Users/X/Documents/blog/tim-watson/astro.config.mjs:10:37)
    at async instantiateModule (file:///C:/Users/X/Documents/blog/tim-watson/node_modules/vite/dist/node/chunks/dep-df561101.js:55974:9)

[astro] Unable to load your Astro config

 error   Cannot find module '@astrojs/mdx' imported from 'C:/Users/X/Documents/blog/tim-watson/astro.config.mjs'
  File:
    C:\Users\X\Documents\blog\tim-watson\node_modules\vite\dist\node\chunks\dep-df561101.js:56010:25
  Code:
    56009 |         if (!resolved) {
    > 56010 |             const err = new Error(`Cannot find module '${id}' imported from '${importer}'`);
            |                         ^
      56012 |             throw err;
      56013 |         }
  Stacktrace:
Error: Cannot find module '@astrojs/mdx' imported from 'C:/Users/X/Documents/blog/tim-watson/astro.config.mjs'
    at nodeImport (file:///C:/Users/X/Documents/blog/tim-watson/node_modules/vite/dist/node/chunks/dep-df561101.js:56010:25)
    at ssrImport (file:///C:/Users/X/Documents/blog/tim-watson/node_modules/vite/dist/node/chunks/dep-df561101.js:55912:30)
    at eval (C:/Users/X/Documents/blog/tim-watson/astro.config.mjs:10:37)
    at async instantiateModule (file:///C:/Users/X/Documents/blog/tim-watson/node_modules/vite/dist/node/chunks/dep-df561101.js:55974:9)

But once that issue was resolved and I created the mdx file (this blog post), I then needed to move/add some images to the src folder. Currently I have been locating my images in the public folder. Once included I can import them as below:

import { Image } from 'astro:assets';
import grid from '../../assets/images/grid.png';
import grid_site from '../../assets/images/grid_site.png';
import tags from '../../assets/images/tags.png';

and use them:

<Image src={tags} alt="The slightly modified page tags" title="The slightly modified page tags" />

Now that I am using the Astro Image tag, it converts/optimises the images. Such that they should now appear in webp format and when they are loaded by the browser will change depending on when they are visible on screen.

This all seems to work, but the image compression seems to range massively depending on the size and if the image is already compressed, etc. If the image is compressed it may not be worth going to this trouble and may look worse… Looking at the two images below: the first is using the <img> tag and the second the <Image> tag. You will notice that the New Image tag only loads when it becomes visible.

img tag

New Image tag

Summary

In summary the upgrade wasn’t that difficult, but it also didn’t give me much. It’s always good to stay up to date and I might challenge myself to add some transitions between pages. I had to do a little bit of maintenance to the styling but nothing major. And if I want to, I can upgrade my pages to mdx to get some optimisations but it doesn’t seem to be massively different to what I had, which is also nice to know so I don’t need to waste time converting pages.

Edit

By the time I got round to posting this, Astro 4 was out… I took a fair amount of time to upgrade to that by retro-fitting the updates from the github template. But by migrating to a new PC I had lost the ability to render MDX files (natively). To add support for mdx I needed to find the doc page and install mdx just for this page to work.

npx astro add mdx

The command in the docs probably works, though I opted to go with the manual install.