Forem: Max Dev

Moving My Blog from Next.js to Astro

Max Dev — Tue, 27 Dec 2022 22:29:12 +0000

A few years ago I tried to set up my blog with Gatsby, but I soon got lost in its complexity. Having to define my GraphQL API was a bit of an overkill and it was difficult to navigate all the extensions that were provided by it. A few months ago I created my blog site with the Next.JS framework.

This time around I decided to give Astro a go. I heard a lot of praise about it and since it was already more than 3 months since its initial release I was convinced it should be ready for prime time.

In this blog post, I would like to go through some of the unique features that I liked in Astro and some of the pitfalls that I stumbled upon. I will be comparing it mostly with Next.JS since it is the framework I had the most experience with and I will do a side-by-side comparison of the Next.JS and Astro versions of my blog.

Initial Setup and Getting Started

I enjoyed the simplicity of Astro right from the get-go. To start building my blog with Astro all I have to do is to run:

npm create astro@latest

Astro provides a great CLI that explicitly shows what is being created and later on when you want to add any integrations all the changes are always highlighted. That puts you in the driver's seat.

Starting Astro locally is easy as well:

npm run dev

If you want to build a blog on your own with Astro I highly recommend following this guide from their docs page. Overall, whenever you struggle with something just look for it in the docs, and 99% of the time the answer is there.

Zero JS by default 🚆

The main and biggest difference between Astro and Next.JS is the way the pages are served. By default Next.JS will load the basic HTML on the first load of the website and for each route in your app will only load JS needed to hydrate the initial page. In contrast, Astro follows a more classical MPA approach. Each route is a completely separate HTML page. When you navigate the route by default you only load the HTML page with the stylesheet and any assets defined on the page. Most importantly, you get Zero JS loaded by default.

Now if we look at it from the user perspective, when transitioning from Next.JS to Astro when you are navigating from one page to another you need to load a new page. This means you are losing the SPA feeling that Next.JS gives you as you can see the navigation bar and footer flickering when loading the new page. What you gain though is an extra small bundle. My Next.JS blog loaded 327 kB (153kB gzipped) of data, and Astro fits in just 86kB (74kB gzipped). Here I must also mention that I used a trick to load Preact Compat instead of React to squeeze an even smaller bundle size. Still, the numbers speak for themselves, Astro's initial bundle is 2x smaller when comparing the transferred size over the wire.

100 Score in Performance 🚀

One of the probably most exciting outcomes that you get from using Astro is how easy it is to get a perfect 100 Performance score even on mobile. One piece of the puzzle is of course smaller bundle, but another is no JS so no logic to run on the client. Even an underpowered phone can run your page easily in the browser with Astro.

Now let's dive into some actual results for 2 pages. I will be running side by side comparison using PageSpeed Insights and concentrating on the mobile part as it is the one that reflects more challenging conditions. In fact, on the Desktop both frameworks perform well, so there is no point to compare that one.

If you want to do your own comparison Next.JS version of my blog is available at https://maxdev.blog and Astro at https://my-astro-site-flame.vercel.app.

First, let's look at the Main Page. It is a pretty simple page with a navigation header, footer, theme toggle (which we will talk a bit later about), and 2 images - bigger for the post and smaller for the logo.

Based on the results you can see that Astro was able to perform slightly better in terms of an overall performance score. If we look at the Performance details the biggest difference is in the Largest Contentful Paint (LCP) metric. This metric is one of the key metrics as it marks the point in the page timeline when the main content has loaded. LCP is 2 times faster with Astro than with Next.JS. Please, ignore the Accessibility score, I did a few changes in that regard to the Astro application, but that doesn't affect Performance.

The second page is an About Me page. Here we are using a different font that is being retrieved from the server, we also load quite a few SVG images and an image of myself. This page is a bit heavier than the previous one, but still, we can get a perfect 100 with Astro.

The performance difference is even more obvious in this one. The score with Next.JS is now down to the yellow category, while with Astro we still get a perfect 100. The difference in LCP is even bigger now, the site becomes interactive in only 1.1s and there is no blocking time with Astro.

I believe that gives you a pretty good overview of why you may want to adopt Astro. But again performance is not everything and as I mentioned before this is more of an extreme case with a slower smartphone on a slower internet, with a normal internet on a desktop both web pages load very fast.

Closer to WEB standards

Next.JS tries to hide away and abstract most of the details about how it is building your pages. For example, your classical <head> tag is defined inside the Document component provided by Next.JS and if you want to do any kind of modifications you will need to extend it. Unfortunately, it is only possible to extend it once for the whole web app. On the contrary, Astro lets you build a separate header for each page if you want. This is again related to the differences between MPA and SPA.

When writing Astro components you will be using a JSX template, but still having conventional HTML tags so you can copy any HTML part from the web and it will be a valid JSX for Astro. When compared to Next.JS since it uses React it provides abstractions that are a bit different, like the infamous className instead of the conventional class.

Another interesting thing is how each Astro component is defined. You have your front matter first - the code that will be executed on the server, <script> part, a <styles> part, and finally your actual content. This idea was borrowed from Vue. It has its drawbacks and benefits. Personally, since I use Tailwind I don't even need to specify the <styles> part, but if you want you to have the option.

Easy to write code executed on the server

Astro provides a very simple mental model on how to make code run on the server instead of on the client. All you have to do is write it in the frontmatter of your component. That's it! For example, this is how I can retrieve the list of my blog posts:

import type { MarkdownInstance } from 'astro'
import type Post from '../types/post'

// Use Astro.glob() to fetch all posts, and then sort them by date.
const posts = (
  (await Astro.glob) <
  MarkdownInstance <
  Post >> './posts/*.{md,mdx}'
)
  .sort(
    (a, b) =>
      new Date(b.frontmatter.date).valueOf() -
      new Date(a.frontmatter.date).valueOf()
  )
  .map((post) => {
    return { ...post.frontmatter, slug: post.url }
  })

You can see I am using Astro.glob to retrieve the list of my posts. All I have to do is specify where it is located and what file types I am expecting.

In Next.JS I can do the same with the following code.

import fs from 'fs'
import { join } from 'path'

const postsDirectory = join(process.cwd(), '_posts')

export function getPostSlugs() {
  return fs.readdirSync(postsDirectory)
}

export function getAllPosts(fields: string[] = []) {
  const slugs = getPostSlugs()
  return (
    slugs
      .map((slug) => getPostBySlug(slug, fields))
      // sort posts by date in descending order
      .sort((post1, post2) => (post1.date > post2.date ? -1 : 1))
  )
}

export const getStaticProps = async () => {
  const allPosts = getAllPosts([
    'title',
    'date',
    'slug',
    'coverImage',
    'excerpt'
  ])

  return {
    props: { allPosts }
  }
}

While in both cases it is not rocket science to understand what is being executed. In the first example, it is much easier as Astro.glob abstracts all the complexity of going through the file system and reading the necessary directory. Plus you don't have to put the result into a getStaticProps method, all you need to do is just write the content inside the frontmatter of your component and it will be served statically by default. Of course, the way Next.JS does it gives you a bit more flexibility, especially if writing a more complex web app, but for a blog post you anyway should serve statically generated pages to ensure the best user experience.

Markdown, RSS, Tailwind out of the box

Astro provides plenty of different official integrations. The ones I already used in my blog are RSS, Sitemap, and TailwindCSS. It allows one to quickly start using it and is impressive how big the ecosystem got in so little time. Astro even provides SSR adapters for different platforms like Vercel and Deno. However, if you would like to use SSR you would probably be better with Next.JS as the support of it is much better right now. What I am most excited to try next is the Integrations for UI frameworks available. This brings me to my next point.

No Vendor Lock-In 🏝️

Astro provides you with plenty of options using pure Astro components. But if this is not enough for you, you can bring any UI framework/library. So far Astro supports React, Preact, Svelte, Vue, Solid, AlpineJS, and Lit. That is plenty of great options, if you are fancy you can even combine different frameworks on the same page (or if you like your user to struggle and load all this JS 😆). Comparing to Next.JS or Gatsby, where you are locked to React this provides a set of options to develop your website. You have the flexibility to use different frameworks on different pages. Or you can use a lighter framework than React to make your website bundle smaller and loading times faster.

This is all possible due to Astro's island architecture. As mentioned before Astro ships with Zero JS by default, but if you need interactivity you can opt-in and only load the necessary JS when the user scrolls into the island. All the islands are isolated, which is why you can have your React component in the header, and your Solid component in the footer. And all of them will load in parallel.

Moreover, you can specify when exactly your interactive component should be loaded. This is done by Client Direcives. You can force the component to load immediately, load on idle, load when the component is visible, or even load based on the media query.

Pitfalls when using Astro

One of the issues I stumbled upon during setting up Astro is that the official @astrojs/image integration was not able to work with JPG and WEBP images. I had to use a plain <img> tag and specify the width and height manually. It is a bummer since the <Image> component provided by Next.JS works great and I don't need to compress and figure out the width and height of the images on my own.

Some other issue I noticed during the development is that hot reload doesn't always work. Sometimes during hot reload I got a broken UI that I couldn't figure out how it was built. I spent a good hour trying to understand what is wrong until I just accidentally restarted the Astro script and voila everything worked. I never had this issue with Next.JS.

A few smaller issues were how to load the fonts and icons. For both of these, I found an easy solution. For fonts, I used fontsource, which works by simply installing your font as an NPM package and importing it on the page you need. For the icons I used astro-icon integration, the setup was very simple - install the NPM package and start using it by importing an Icon component.

Another thing I had to deal with was the implementation of the dark mode toggle. This is something that you got out of the box with Tailwind, but you want to provide the user with a way to turn it on/off. For the website that uses Next.JS, I first used a short code that I wrote with React, but then I had an issue with the theme flickering before the rendering and I decided to use a library that solves it called next-themes. For the Astro however, I didn't want to load a whole UI library, being React or Preact just to have a simple logic for a dark mode toggle. So I had to build it with plain JS. By the way, it was the perfect use case for using the <script> tag in the component as the logic is closely tied to the toggle itself. Here is what I came up with.

let themeToggleDarkIcon = document.getElementById('theme-toggle-dark-icon')
let themeToggleLightIcon = document.getElementById('theme-toggle-light-icon')

// Change the icons inside the button based on previous settings
if (
  localStorage.theme === 'dark' ||
  (!('theme' in localStorage) &&
    window.matchMedia('(prefers-color-scheme: dark)').matches)
) {
  themeToggleLightIcon?.classList.remove('hidden')
  document.documentElement.classList.add('dark')
} else {
  themeToggleDarkIcon?.classList.remove('hidden')
  document.documentElement.classList.remove('dark')
}

let themeToggleBtn = document.getElementById('theme-toggle-button')

themeToggleBtn?.addEventListener('click', function () {
  // toggle icons inside button
  themeToggleDarkIcon?.classList.toggle('hidden')
  themeToggleLightIcon?.classList.toggle('hidden')

  // if set via local storage previously
  if (localStorage.theme) {
    if (localStorage.theme === 'light') {
      document.documentElement.classList.add('dark')
      localStorage.setItem('theme', 'dark')
    } else {
      document.documentElement.classList.remove('dark')
      localStorage.setItem('theme', 'light')
    }

    // if NOT set via local storage previously
  } else {
    if (document.documentElement.classList.contains('dark')) {
      document.documentElement.classList.remove('dark')
      localStorage.setItem('theme', 'light')
    } else {
      document.documentElement.classList.add('dark')
      localStorage.setItem('theme', 'dark')
    }
  }
})

I must say it is not the code that I am most proud of, but it does the job for me, even if it looks uglier than what I could have achieved with a UI library like React. It loads initially either a dark or light theme based on the theme set in the local storage or color scheme of the user. By default, it will use the light theme. Next, we add an event listener to the button that changes the SVG icon if it was clicked and applies the theme to the website by adding dark to the class list. Since this JS snippet loads immediately I don't have any flickering when initially loading the page.

Final Words

In my opinion, Astro combines the pure simplicity of tools like Hugo or Jekyll, while providing the power of building well-structured component-based frameworks like Next.JS with the additional benefit of not being tied to a specific UI library like React. That is why when I decide to bring something more interactive to my website, I will for sure give Solid a try. I believe Astro has a bright future and most importantly they know their target audience and focus their efforts on it.

On the other hand, I am still not fully decided on what technology to continue using for my blog. On one side faster first load of the web page, but on the other re-renders are a bit less user-friendly as you have the header and footer reloading and the Next.JS ecosystem is definitely more mature so some things might be lacking.

Overall, I am happy that I rebuilt my blog in another framework. It taught me a lot about how web pages are being served under the hood and how can I achieve the best performance for my website.

7 Things to Consider When Working On a Personal Project

Max Dev — Mon, 26 Sep 2022 22:00:56 +0000

Starting a personal project is a cool thing to do, but there are a lot of factors that can distract you from finishing your project. I collected 7 tips from my personal experience and I hope you can learn 📘 from my mistakes.

Choose a project idea that you are passionate about

No matter what you like more 🐈 or 🐕, reading 📚 or watching 🎥 - you should choose a project based on your personal preferences. For example, I like to 🧑‍🍳 in my free time for myself and my wife. So I decided to build a recipe app, where I can upload different recipes, search for them and view a very detailed process on how to prepare them. Your tastes might be different. You may want to build your To-Do app or a URL Shortener. But usually, the best ideas will come if you find yourself in a position where you are missing particular functionality from existing tools. In this case, you could end up building a project that many people will find usable and potentially you can build your own company out of it (you never know!).

Don't follow blindly tutorials on the Internet

The worst thing you can do when working on a personal project is to copy things blindly from the 🌐. There are tons of different tutorials for all different kinds of apps that you can build. While I am not saying they are useless, not at all you can learn a lot from how people approach different projects and use different strategies to build them. You can borrow ideas from those projects and I don't find a bit of copy/pasting evil, but you should never just write down the same code as the project author and call it a day. Instead, you should take your time and architect your project. In this process, you can pick a few pieces from different sources, but you should always understand what you are doing. In this way, you learn the most as you will tackle different challenging issues, that you will have to find the solution for. And overcoming those challenges is exactly what programming is about🚀

Set small reachable goals

Setting small goals is the best way to let you enjoy the process constantly. When you set goals for yourself and can reach them in a couple of hours ⏲️, you have a very rewarding experience. For example, you want to build a blog. You start by doing your research and deciding what set of tools you will use and that is your very first goal accomplished. Next, you look into how other people design their websites and you sketch a draft either on paper or a tool like Figma and this is already your second deliverable. When you work on the page each separate page and functionality like a button is a separate deliverable. In this way, you always have these small things that you can add and improve your website. Ideally, you should set up a light tracking tool like Trello or even a simple notebook. Just assigning a task to yourself and moving it to done feels very satisfying (trust me on that!). And if you want to get to the project after some time you can rewind the decisions you did and understand your motivation at that time. You will forget all the details about your project in just a few weeks.

Best practices are good, but you probably won't need them

It is always nice to learn and follow the best practices from the community like proper folder structure for your project, following all the naming conventions and extracting the interface for the class. But most of them are useful only, when you are working on a big team or you have a huge project. So instead of immediately going to a popular repository and copying their structure, you should aim for starting things simple and improving/changing the structure naturally as your project grows.

In my experience, in my recipe book Angular app I used a Redux-like state management library called NgRX. While it is a cool library and brings benefits for bigger projects, in my small project it only complicated things as after just a few weeks I couldn't remember how exactly everything was wired up and what I have to do to add some extra data to the state. If I would go with a simpler approach first (like using built-in services in my Angular app) I wouldn't have had those issues. And if I would later observe that this doesn't fit my use case anymore, it would be easier for me to switch to a more sophisticated solution than doing it in a reverse direction.

Stick to the tools you chose in the beginning

This is true for any programming language, but especially, if you are a JS developer as you can see a new framework/library being born 👶 every day. But before you jump on the hype train, ask yourself some of the following questions:

Why did you start doing your project with the current tools?
Were you trying to get some experience in them before you can apply for work 💼? If the answer is yes, then will this new shiny tool help you to achieve that? The answer here is usually no. As ✨ new tools are rarely used in the industry, they need to pass the test of time and be polished so they don't have any surprises, which you might also encounter and get stuck.
Is there any real functionality that you are missing with the current tools and there is no way to easily replicate it or is it just the new tool is looking nicer or advertised as faster?

After you answered all the above-listed questions and you still feel the need to switch then fair enough - just do it! But, likely, that this won't be the case for you. Anyways, it is a cool idea to later re-write your project with a new tech stack or new programming language, but only after you have achieved at least your Minimal Viable Product state.

Decide what would be your Minimal Viable Product

Put the most necessary things and deliver your project as an MVP 🚀. MVP will ensure you stay laser focused and have a small deliverable that is usable and that you can even showcase. It should contain only a minimal set of functionality that you need to implement. Say you want to build a To-Do app. Functionality that can go in your To-Do app is creating new notes 📓, editing/deleting current notes and maybe moving the notes around. But then things like including a fully featured rich text editor, marking favourite notes or even creating folders are all extra things that go on top. They are not necessary for the MVP. Creating an MVP is all about building this solid foundation, making quickly something that is not very sophisticated, but supports the very core functionality that users would expect from your app.

Share your project with others

Once you build an MVP, it is time to share 📤 your project with the world. Nowadays it is super easy to do. First of all, make your project repository open on platforms like GitHub or GitLab. Next, you can create a small blog post about your project and post it on one of the awesome websites like Medium, Hashnode
or Dev.to. Last, but not least share it on any social media like Twitter, LinkedIn or even YouTube with your friends and followers.

You should not fear sharing your work, nobody will punish you for not providing the best solution possible, instead sharing your project helps you to get feedback from other developers like yourself. They can give you 💎 advices on your project structure, provide fresh ideas to work on or even find a bug that you didn't notice.

Thanks for reading my very first blog post! I hope you learned something new 😊 Feel free to drop links to your projects under this post. I will happy to take a look and give my feedback.