#Contents

• What is Astro
• Components & Syntax
• Client-Side JavaScript
• Integrating Other UI Frameworks
  • Sharing state between UI frameworks
• SSR Adaptors
• Recommended Plugins
• Final Thoughts

#What is Astro

Astro is another JavaScript (JS) web framework for creating incredibly fast, sites. Astro is opinionated to optimise speed and improved SEO (Search Engine Optimisation) rating. It does this by rendering components server side, minimising client side JS required for the site as possible and improving the SEO by sending HTML before sending required JavaScript, if any. I’ve talked about the performance gains from a hybrid of client side and server side rendering before in a previous blog post The Fall & Resurgence of Server Side.

Astro allows you to plugin and use any major UI framework such as React, Vue, Preact, Svelte and SolidJs. These frameworks are an opt-in integrations, which you install and add into Astro config, this integrations will use the specific framework’s renderer to create elements. Then taking the HTML output and passing it to Astro to render, this allows any choice of frontend frameworks, which Astro has integrations built for. Lastly, any client side JS can be sent down to the client browser explicitly, this also follows an opt-in approach to prevent excessive JS being sent to the browser taking longer for the site to load, but all the JS will be deferred from being sent until the static content (HTML and CSS) has been sent and painted.

Astro has grown in popularity largely for it’s static site generation capabilities, using the latest tech with built-in batteries included from vite, markdown to HTML generation (Frontmatter support, remark & rehype), type generations using Zod, server-side support and great development experience, with the as mentioned focus on performance and isolating deferred client JavaScript in hydrated “Islands”, allowing support of having a mix of multiple UI frameworks:

(Source: Astro Islands)

These Islands can be built with any framework with the JS, including relevant framework, bundled in, if you think about that, you can inject other components even remotely, making it incredibly easy to implement Microfrontends. Here’s an example, but you can read more in this article:

1
import MicroFrontendA from 'http://localhost:7100/bundle.js';
2
import MicroFrontendB from 'http://localhost:7200/bundle.js';
3

4
const ReactComponent = () => (
5
  <>
6
    <React.Suspense fallback="Loading…">
7
      <MicroFrontendA />
8
    </React.Suspense>
9

10
    <React.Suspense fallback="Loading…">
11
      <MicroFrontendB />
12
    </React.Suspense>
13
  </>
14
);
15

16
export default ReactComponent;

These islands are isolated from eachother in the DOM through HTML Web Components, which uses shadow DOM to encapsulate the code and make it private, ensuring no code outside of the web component can modify it and prevent collisions. Checkout the ‘astro-island’ HTML web component output of one of these islands:

Note the data attributes is how you can pass data into the web component, through to the shadow DOM and the web component’s JavaScript. But you can also see how the language specific renderer is being passed in to be used.

Another notable thing about Astro is that you can also take quick advantage of what functionality you’re after with Astro pre-built themes (free or paid) and templates with either official examples:

npm create astro@latest -- --template <example-name>

Astro v1 framework was GA released June 2022 and has since made its way to v4. According to State Of JS 2023 Meta Frameworks, Astro has grown in usage (19%) to rival Gatsby (23%) and Nuxt (25%), which is is not as high as Next.js (56%) but a positive growth:

(Source: State Of JS 2023 Meta Frameworks)

Additionally, the overall positive rating of Astro (54%) has made it 2nd to Next.js (64%), and the focus on development experience with performance defaulted, has left it feeling flexible and easy to use:

(Source: State Of JS 2023 Meta Frameworks)

#Components & Syntax

Astro components are written using Markdown frontmatter to fence (---) off server side javascript, Component Script, and the HTML + JS Expressions component, Component Template:

---
// Component Script (JS)
---
<!-- Component Template (HTML + JS Expressions) -->

If you have server side rendering or hybrid output set, means you can use server side JavaScript to call external resources with secrets, then send down the rendered HTML to the client, like so:

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  output: 'hybrid'
5
})

Note the outputs are:

static - Default: Building a static site to be deployed to any static host.

server - Building an app to be deployed to a host supporting SSR (server-side rendering).

hybrid - Building a static site with a few server-side rendered pages.

1
---
2
import { connectDb } from "...";
3

4
interface Props {
5
  title: string;
6
}
7

8
const { title } = Astro.props;
9

10
export const database = connectDb(
11
  import.meta.env.DATABASE_URL,
12
  import.meta.env.DATABASE_KEY,
13
);
14

15
const data = await database.get();
16
const TitleElementTag = 'h1'
17
---
18

19
<div>
20
  <TitleElementTag class="font-bold" data-test-id="items-header">
21
    {title}
22
  </TitleElementTag>
23
  <ul>
24
    {data.map(item => (<li>{item}</li>))}
25
  </ul>
26
</div>

There’s also a bit to unpack in the above:

• Top level await
• Typescript support
• Dynamic HTML element tags
• Props passed to child component
• JSX-like support, note class instead of className and kebab-case instead of camel-case

#Client-Side JavaScript

Out of the box, Astro focuses on static or server side rendering rather than client side, in turn this reduces the amount of JavaScript sent to the client whilst reducing browser paint times, you may even notice that all content is transformed into HTML on build, event markdown and MDX files. However, you’ll of course need client side JavaScript for interactive of buttons, search bars, drop downs and more, but this needs to be explicitly set or Astro will not send the required JavaScript.

There are a few options to optimise it as well, let’s see what this looks like if had a banner message which we want to have a close button:

1
---
2
// This is staticly built into the HTML output or server side rendered
3
// this uses a argument passed in or uses the default, e.g.
4
// `<Index bannerMessage={Override the banner message} />`
5
const {
6
  bannerMessage = 'This message is brought to you by jbrlloyd.dev'
7
} = Astro.props;
8
---
9

10
<!doctype html>
11
<html lang="en">
12
  <head>...</head>
13
  <header>...</header>
14
  <body>
15

16
    {bannerMessage && (
17
      <div id="content-banner">
18
        <p>{bannerMessage}</p>
19
        <button id="close-content-banner-btn">
20
        <b>X</b>
21
        </button>
22
      </div>
23
    )}
24

25
  </body>
26
  <footer>...</footer>
27
</html>
28

29
<!--
30
  Astro will compile this into your `<head>` with type="module", preventing
31
  rendering blocking of HTML and will be deferred + lazy loaded with async.
32
  We can use `is:inline `directives to opt-out of this optimizations and
33
  render it in the HTML: `<script is:inline>` or `<script is:global>` to
34
  not just scope it to this component
35
-->
36
<script>
37
  const closeBtn = document.getElementById('close-content-banner-btn');
38

39
  if (closeBtn) {
40
    closeBtn.addEventListener('click', onClick)
41
  }
42

43
  function onClick() {
44
    closeContentBanner()
45
    closeBtn?.removeEventListener('click', onClick)
46
  }
47

48
  function closeContentBanner() {
49
    const contentBanner = document.getElementById('content-banner');
50

51
    if (contentBanner)
52
      contentBanner.style.display = 'none'
53
  }
54
</script>

#Integrating Other UI Frameworks

Astro offers the ability to plugin integrations to add functionality such as mdx, sitemaps, tailwind and other UI frameworks such as React, Vue, Svelte, Preact, SolidJS, lit and others. An example of how we’d setup SolidJs with client side JavaScript is as such:

1
import { defineConfig } from 'astro/config';
2
import solidJs from '@astrojs/solid-js';
3
import react from '@astrojs/react';
4
import mdx from '@astrojs/mdx';
5

6
export default defineConfig({
7
  site: 'https://example.com',
8
  integrations: [ solidJs(), react(), mdx() ] // <-- Note you can have multiple UI frameworks
9
});

1
import { type Component, createSignal } from 'solid-js';
2

3
export default const SolidJsCounter : Component = () => {
4
  const [count, setCount] = createSignal(0);
5

6
  return (
7
    <>
8
      <p>Count: {count}</p>
9
      <button onClick={() => setCount(count => count - 1)}>Decrement</button>
10
      &nbsp;
11
      <button onClick={() => setCount(count => count + 1)}>Increment</button>
12
    </>
13
  )
14
}

We can now import the SolidJS component, however, because we’re making use of client side JavaScript, we need to explicitly provide a client directive, or else the client side JS will not be sent by Astro framework:

---
// Server side JavaScript
import SolidJsCounter from '../components/solid/SolidJsCounter.tsx';
---
// Without client directive `client:load` no javascript will be sent to the browser
// and therefore the on click will not do anything.
<SolidJsCounter client:load />

#Sharing state between UI frameworks

One problem with having the ability of multiple UI frameworks, is sharing state across them, as usually the state managers are language specific. Hence, the Astro recommendation is using Nano Stores, which is lightweight (> 1 KB) and framework agnostic. Let’s see how we can create 2 counters in different frameworks which increment and decrement the same state:

1
import { atom, map } from 'nanostores';
2

3
export const count = atom(0);
4

5
export const incrementCount = () => count = count.get() + 1;
6
export const decrementCount = () => count = count.get() - 1;

1
import { type Component } from 'solid-js';
2
import { useStore } from '@nanostores/solid';
3

4
import { count, incrementCount, decrementCount } from '../../sores/countStore';
5

6
export default const SolidJsCounter : Component = () => {
7
  const $count = useStore(count);
8

9
  return (
10
    <>
11
      <p>Count: {$count}</p>
12
      <button onClick={() => decrementCount()}>Decrement</button>
13
      &nbsp;
14
      <button onClick={() => incrementCount()}>Increment</button>
15
    </>
16
  )
17
}

1
import { type FunctionComponent } from 'react';
2
import { useStore } from '@nanostores/react';
3

4
import { count, incrementCount, decrementCount } from '../../sores/countStore';
5

6
export default const ReactCounter : FunctionComponent = () => {
7
  const $count = useStore(count);
8

9
  return (
10
    <>
11
      <p>Count: {$count}</p>
12
      <button onClick={() => decrementCount()}>Decrement</button>
13
      &nbsp;
14
      <button onClick={() => incrementCount()}>Increment</button>
15
    </>
16
  )
17
}

1
---
2
import SolidJsCounter from '../components/solid/SolidJsCounter.tsx';
3
import ReactCounter from '../components/react/ReactCounter.tsx';
4
---
5
<div id="wrapper">
6
  <SolidJsCounter client:only="solid-js" />
7
  <ReactCounter client:only="react" />
8
</div>
9

10
<script>
11
  import { count } from '../stores/countStore';
12

13
  const wrapper = document.getElementById('wrapper');
14

15
  count.subscribe((countVal: number) => {
16
    if (!wrapper)
17
      return;
18

19
    if (countVal % 2 === 0) {
20
      wrapper.style.backgroundColor = 'blue';
21
    } else {
22
      wrapper.style.backgroundColor = 'green';
23
    }
24
  })
25
</script>

#SSR Adaptors

Astro is largely designed for static sites, where it the entire site gets compiled to HTML and CSS, served from a file storage with a web server like nginx or apache serving the files. However, we make use of server-side rendering (SSR) through one of the following official adaptors:

• CloudFlare
• Netlify
• Vercel
• Node
• And others such as: Deno Deploy, GitHub Pages, AWS, Firebase, Azure, Google Cloud, Heroku + more

Note that node will allow us to host our site with SSR ourselves through most self-hosting mechanisms such as using containers. Each adaptor has different configuration and setup, but all require setting the Astro configuration to output a server side capability. Let’s hone in on CloudFlare adapter, first we have to install the adapter into our Astro project:

pnpm astro add cloudflare
pnpm add @astrojs/cloudflare

1
import { defineConfig } from 'astro/config';
2
import cloudflare from '@astrojs/cloudflare';
3

4
export default defineConfig({
5
  output: 'hybrid', // or full server side with 'server'
6
  adapter: cloudflare(),
7
});

After enabling CloudFlare (CF) adaptor functionality, we can create a CF pages site and connect it to our repository for automatic deployment. Some functionality between CloudFlare and Astro may not be compatible, allowing the site to work locally when using: astro check && astro build && astro build but not working when deploying to CF Pages. So the best way to ensure your site will work in CF locally is to use CF Pages emulator via the CF CLI wrangler. Install this and preview:

npm install -g wrangler
wrangler login
pnpm add wrangler --save-dev

We can also wire this up in our project’s CLI, note that Astro will compile files into dist/ directory as it’s build output:

1
{
2
  // ...,
3
  "scripts": {
4
    "build": "wrangler types && astro check && astro build",
5
    "preview:cf": "pnpm run build && wrangler pages dev ./dist",
6
    //...
7
  },
8
  //...
9
}

wrangler pages dev ./dist will emulate a CF page worker using the Astro build output as the root.

If you do want to setup using CloudFlare pages, you can simply create a page, connect it to a git repository and then select Astro Framework preset, this’ll take the main branch and deploy it as well as hook into any new commits on the branch and rebuild & deploy (pnpm, yarn + others package managers are support if you wish to change the build command to the corresponding manager):

If you do go down this route, out of the box you’ll get preview builds and hosting on non-main branches and I also recommend you turn on build caching to take your build time down from 2-3 mins to >1 min! 🚀

#Recommended Plugins

Out of the box markdown (and MDX integration is added) files are processed by remark, which processes markdown into an AST and allows plugins to modify outputs, then outputs it through rehype. Find more in the list of remark plugins or rehype plugins.

Here are some of my recommendations:

• @astrojs/mdx - adds MDX support for content.
• @playform/compress - compress css, images, html, js and images (through minification and other mechanisms).
• remark-toc - Automatically generates a Table of Content based on headers.
• astro-expressive-code - Adds great looking styles around code blocks, including file names, line numbers, diff highlighting and more.
• rehypeAccessibleEmojis - Add accessibility to emojis without needing to do anything more.
• rehype-slug + rehype-autolink-headings - Adds ID attributes to headers and links to attach to them.
• If you have the desire to tailwindcss, you should use tailwindcss typography to break out of the cascading styles and add specific styling around the areas requiring styling.

#Final Thoughts

I had initially built a Wordpress blog to get more into Wordpress development, but then realised that most of the things I wanted to do was incredibly difficult to implement due to how the framework restricts you. So I tried converting it to React Gatsby.js, this led to a different level of frustrations in dealing with plugins and more often then not, breaking things and other plugins which, overall it felt like a very complicated trying to make minor changes.

Astro has been a very pleasant experience with a well architected solution which is highly flexible and developer first experience, adding Obsidian note taking for writing MD or MDX makes for an additional pleasantry. I won’t say it’s perfect because it does have downfalls, here’s some of them from my experience: