Astro is a performance-friendly meta-framework for content-heavy websites. It ships zero JavaScript by default, but you can add it wherever you need interactivity, which is one reason Astro sites tend to have significantly better Core Web Vitals than sites built with Next.js, Nuxt.js, WordPress, and other popular frameworks.

For example, according to the HTTP Archive, 71% of the tested Astro sites have a Good score on mobile at the time of writing (on desktop, it's 84%):

Check out the PDF version of this tutorial.

What We Will Build​

Our demo site will feature:

• A homepage with:
  • a random coffee recommendation, powered by a live content collection that fetches data from an external API
  • the latest blog posts, powered by a build-time content collection
• Three blog posts, each with:
  • a Like button, built as a Preact island
  • a reading progress bar, built as a Web Component

We'll deploy the site to Cloudflare Workers.

The goal of this setup is to demonstrate that Astro supports several frontend frameworks (e.g., Preact, Svelte, Solid, Vue, React, etc.) alongside Web Components.

Technically, this means you could install several UI framework integrations side by side, with each one hydrating as a separate Astro island. On the other hand, Astro doesn't add Web Components as islands, since they just use built-in browser APIs. This lets us compare adding interactivity to an Astro site with and without using the islands architecture.

To keep the coffee blog fast, we'll use Preact instead of React because it provides a React-like API in about 3KB gzipped, compared to React's 40KB+. If you already know React, most of what you know transfers directly to Preact (e.g., components, JSX, hooks), aside from a few small differences.

Here's a screenshot of the homepage with the three blog posts and the random coffee recommendation at the top:

A single blog post shows the Like button and the reading progress bar at the top:

The finished project structure looks like this:

coffee-blog/
├── public/                                 ← static assets, served as-is
│   └── favicon.svg
├── src/
│   ├── components/
│   │   ├── CoffeeRecommendation.astro      ← uses a live content collection
│   │   ├── LikeButton.css                  ← unscoped CSS for the Preact island
│   │   ├── LikeButton.jsx                  ← Preact island
│   │   └── ReadingProgressBar.astro        ← renders a Web Component
│   ├── content/
│   │   └── blog/                           ← uses a build-time content collection
│   │       ├── grind-size-matters.md
│   │       ├── our-v60-ratio.md
│   │       └── pour-over-vs-french-press.md
│   ├── layouts/                            ← shared page layouts
│   │   └── Layout.astro
│   ├── live/                               ← live loader logic
│   │   └── coffee-loader.ts
│   ├── pages/
│   │   ├── blog/
│   │   │   └── [slug].astro                ← blog post page (file-based routing)
│   │   └── index.astro                     ← homepage
│   ├── styles/                             ← shared design tokens
│   │   └── global.css
│   ├── content.config.ts                   ← build-time content collection config
│   └── live.config.ts                      ← live content collection config
├── astro.config.mjs                        ← adapter + integrations
├── package.json                            ← dependencies
├── tsconfig.json                           ← TypeScript config
└── wrangler.jsonc                          ← Cloudflare Worker config

Prerequisites​

If you've written any HTML, CSS, and JavaScript before, you already have most of the knowledge you'll need to build an Astro site.

A few files in this tutorial use basic TypeScript to catch errors at build time. Don't worry if you haven't used it before, since TypeScript is just JavaScript with type annotations added on top. While Astro works with plain JavaScript too, it supports TypeScript out of the box, so there's nothing extra to install.

Beyond that, you'll also need:

• Node.js 22.12+
• A JavaScript package manager, such as npm, pnpm, or Yarn
• A code editor, such as VSCodium
• A GitHub or GitLab account to host the source code
• A Cloudflare account

1. Scaffold the Project​

To get started with Astro development, run the following command in your terminal:

npm create astro@latest

When prompted, pick the Use minimal (empty) template option, then go with the default options for the rest of the questions:

Once the installer finishes, you can start the dev server by running npm run dev and opening the site at localhost:4321 in your browser. Right now, it's just a bare-bones placeholder page; we'll be adding the other folders and files as we go.

For starters, let's replace Astro's default favicon files with an SVG containing the hot beverage emoji:

<!-- /public/favicon.svg -->

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <text y=".9em" font-size="75">☕</text>
</svg>

Place the favicon.svg file into the public folder, which is the home for non-code, static assets that Astro serves as-is without processing them, such as fonts, icons, or the robots.txt file.

2. Set Up the Base Layout and Global Styles​

First, we define the layout every page will share and the global styles for the site. Create the following folders and empty files in the src folder:

• /layouts/Layout.astro
• /pages/index.astro
• /styles/global.css

An .astro file is Astro's own component format. It looks similar to JSX (JavaScript XML), but the Astro syntax is a superset of HTML with support for components and JavaScript expressions. It has two main parts:

1. The component script, also known as the frontmatter, where you write server-side JavaScript or TypeScript (you place this at the top of the file between two --- code fences).
2. The template, where you define the HTML that Astro renders. You can use the {} notation to embed values or expressions from the component script into the markup.

Layout.astro is a shared wrapper every page will use. It defines the basic HTML structure of the site:

---
// /src/layouts/Layout.astro

import '../styles/global.css';

// Defines the props this layout expects
interface Props {
  title: string;
}

const { title } = Astro.props;
---

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <title>{title}</title>
  </head>
  <body>
    <header>
      <a href="/">☕ Coffee Notes from Underground</a>
    </header>
    <main>
      <!-- Renders the page content passed into this layout -->
      <slot />
    </main>
  </body>
</html>

<style>
  header {
    padding: 2rem 0 1rem;
  }
  header a {
    text-decoration: none;
    font-weight: bold;
    font-size: 1.1rem;
    color: var(--coffee-dark);
  }
</style>

The <slot /> element is Astro's own template syntax that defines where each page's content is rendered.

The file also includes styles for the header. We keep them here to colocate the styles with the markup they affect, rather than putting them in the global CSS file. Astro also scopes <style> blocks in .astro files to the component by default, so these styles apply only to this component and don't leak into others. Since the layout is the only file on the site that renders the header, keeping its styles here makes them easier to find and maintain.

To the /src/pages/index.astro file, we just add an <h1> heading for now to have something visible on the homepage:

---
// /src/pages/index.astro

import Layout from '../layouts/Layout.astro';
---

<Layout title="Coffee Notes from Underground">
  <h1>Brewing Tips from Our Baristas</h1>
</Layout>

We also add some basic CSS to global.css that includes design tokens and global styles that are shared across the entire site:

/* /src/styles/global.css */

:root {
  --coffee-dark: #3b2412;
  --coffee-medium: #6f4e37;
  --coffee-light: #b08968;
  --cream: #f3e9dd;
  --paper: #fffaf3;
  --text: #2b1d13;
  --text-muted: #7a6a5a;
  --accent: #ec6e07;
  --text-on-accent: #ffffff;
}

* {
  box-sizing: border-box;
}

body {
  font-family: 'Georgia', 'Iowan Old Style', serif;
  background: var(--paper);
  color: var(--text);
  max-width: 680px;
  margin: 0 auto;
  padding: 0 1.5rem 4rem;
  line-height: 1.7;
}

h1,
h2,
h3 {
  font-family: system-ui, sans-serif;
  line-height: 1.2;
}

a {
  color: var(--coffee-medium);
}

code {
  background: var(--cream);
  padding: 0.1em 0.4em;
  border-radius: 4px;
  font-size: 0.9em;
}

If you now open the site in your browser, this is what you should see:

The screenshot above also shows Astro's dev toolbar with the Audit menu open. The dev toolbar is enabled by default while running the site in development mode.

3. Add the Blog Posts with a Build-Time Content Collection​

To add the three blog posts, create the following empty files in the src folder (or use different slugs and content for the posts if you prefer):

• /content.config.ts
• /content/blog/grind-size-matters.md
• /content/blog/our-v60-ratio.md
• /content/blog/pour-over-vs-french-press.md

The content.config.ts file defines where to find the posts and what data each post's frontmatter must contain:

/* /src/content.config.ts */

import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { glob } from 'astro/loaders';

// Defines the blog collection and its schema
const blog = defineCollection({
  // Loads every Markdown file in src/content/blog/ as an entry
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()),
    // Catches a typo like "medum" instead of allowing invalid data
    roast: z.enum(['light', 'medium', 'dark']).optional(),
    excerpt: z.string(),
  }),
});

export const collections = { blog };

The glob() loader tells Astro to treat every Markdown file in the /src/content/blog/ folder that matches the **/*.md pattern as an entry in the blog collection.

The collection schema describes the structure and rules that the data must follow. We define it in defineCollection() once, and then every post is validated against it automatically.

The blog posts themselves are Markdown files with a frontmatter block at the top (for the full content of the three posts, see the GitHub repository):

<!-- /src/content/blog/grind-size-matters.md -->

---
title: "Why Grind Size Matters More Than You Think"
pubDate: 2026-08-10
tags: ["brewing", "technique"]
roast: light
excerpt: "The single adjustment that fixes more bad cups than anything else."
---

If a cup tastes sour, it's usually under-extracted — grind finer...

Right now, the homepage still looks the same because it doesn't load any content from the blog collection yet. To give each post its own page, we need to add routing.

4. Route the Blog Posts​

To create a page for each post in the blog content collection, we'll set up a dynamic route. Add the following empty file to the src folder:

• /pages/blog/[slug].astro

The square brackets around [slug] mark a dynamic route segment (one file that generates multiple pages at build time).

By default, Astro uses file-based routing, which maps URLs to the corresponding files in the /src/pages/ folder in the following way:

• Regular files automatically become pages (e.g., /src/pages/index.astro becomes /).
• Dynamic route files, such as [slug].astro, tell Astro what shape the URL will take through their filename and placement. For example, placing [slug].astro in the /pages/blog/ folder defines a route for the blog posts, which will produce URLs such as /blog/our-v60-ratio/ or /blog/grind-size-matters/. However, [slug].astro is a template rather than a page, so Astro still needs to know through getStaticPaths() which actual pages to build from it.

The /src/pages/blog/[slug].astro file uses getStaticPaths() to generate a page for every entry in the blog collection:

---
// /src/pages/blog/[slug].astro

import Layout from '../../layouts/Layout.astro';
import { getCollection, render } from 'astro:content';

// Generates one route for each blog post
export async function getStaticPaths() {

  // Gets all blog posts so we can generate a route for each one
  const posts = await getCollection('blog');
  
  return posts.map((post) => ({
    params: { slug: post.id },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await render(post);
---

<Layout title={post.data.title}>
  <a href="/">&larr; Back</a>
  <h1>{post.data.title}</h1>
  <p class="meta">
    {post.data.pubDate.toLocaleDateString('en-US', { dateStyle: 'long' })}
    {post.data.roast && ` · ${post.data.roast} roast`}
  </p>
  <Content />
</Layout>

<style>
  .meta {
    color: var(--text-muted);
    font-family: system-ui, sans-serif;
    font-size: 0.9rem;
    margin-bottom: 2rem;
  }
</style>

With routing in place, you can now visit the individual blog posts. For example, visiting http://localhost:4321/blog/our-v60-ratio/ should show:

Now that routing is set up, we can populate the /pages/index.astro file:

---
// /src/pages/index.astro

import Layout from '../layouts/Layout.astro';
import { getCollection } from 'astro:content';

// Sorts posts by publish date, newest first
const posts = (await getCollection('blog')).sort(
  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
);
---

<Layout title="Coffee Notes from Underground">
  <h1>Brewing Tips from Our Baristas</h1>

  <ul class="posts">
    {
      posts.map((post) => (
        <li>
          <a href={`/blog/${post.id}/`}>{post.data.title}</a>
          <p>{post.data.excerpt}</p>
        </li>
      ))
    }
  </ul>
</Layout>

<style>
  .posts {
    list-style: none;
    padding: 0;
    display: grid;
    gap: 1.25rem;
  }
  .posts li {
    border: 1px solid var(--cream);
    border-radius: 12px;
    padding: 1.25rem 1.5rem;
    background: white;
  }
  .posts a {
    font-family: system-ui, sans-serif;
    font-weight: 600;
    font-size: 1.1rem;
    text-decoration: none;
  }
  .posts p {
    margin: 0.4rem 0 0;
    color: var(--text-muted);
    font-size: 1rem;
  }
</style>

The three blog posts should now appear on the homepage, ordered by date:

5. Add a Random Coffee Recommendation with a Live Content Collection​

Our live content collection will show a random recommendation fetched from Sample APIs' Coffee API at request time. Create the following empty files in the src folder:

1. /live/coffee-loader.ts
2. /live.config.ts
3. /components/CoffeeRecommendation.astro

In the coffee-loader.ts file, we define a simple live loader that fetches data from the API, filters the API results, randomly selects a recommendation, and falls back to a default recommendation if the request fails or returns no usable entries:

/* /src/live/coffee-loader.ts */

import type { LiveLoader } from 'astro/loaders';

interface Coffee {
  id: number;
  title: string;
  description: string;
}

const fallbackCoffee: Coffee = {
  id: 0,
  title: 'Black Coffee',
  description:
    'Black coffee is as simple as it gets with ground coffee beans steeped in hot water, served warm.',
};

export const coffeeLoader: LiveLoader<Coffee, { id: string }> = {
  name: 'coffee',

  // This loader only supports the single 'recommendation' entry.
  // loadCollection() is still required by the LiveLoader interface.
  loadCollection: async () => ({
    entries: [],
  }),

  loadEntry: async ({ filter }) => {
    if (filter?.id !== 'recommendation') return undefined;

    try {
      const response = await fetch(
        'https://api.sampleapis.com/coffee/hot'
      );

      if (!response.ok) {
        throw new Error(`Coffee API returned ${response.status}`);
      }

      const coffees: Coffee[] = await response.json();

      // Excludes test records that were added with higher IDs
      const recommendations = coffees.filter(
        (item) => item.id >= 1 && item.id <= 20
      );

      if (recommendations.length === 0) {
        throw new Error('Coffee API returned no recommendations');
      }

      const coffee =
        recommendations[
          Math.floor(Math.random() * recommendations.length)
        ];

      return {
        id: 'recommendation',
        data: coffee,
      };
    } catch (error) {
      console.error('Coffee API request failed:', error);

      return {
        id: 'recommendation',
        data: fallbackCoffee,
      };
    }
  },
};

The live.config.ts file registers the coffeeLoader object as the live collection's loader and defines the shape of its entries with a Zod schema:

/* /src/live.config.ts */

import { defineLiveCollection } from 'astro:content';
import { z } from 'astro/zod';
import { coffeeLoader } from './live/coffee-loader';

const coffee = defineLiveCollection({
  loader: coffeeLoader,
  schema: z.object({
    title: z.string(),
    description: z.string(),
  }),
});

export const collections = { coffee };

In the CoffeeRecommendation.astro file, we query the live collection with getLiveEntry(), log any errors, show an unavailability notice if no entry is returned, and render the result on the homepage:

---
// /src/components/CoffeeRecommendation.astro

import { getLiveEntry } from 'astro:content';

const { entry, error } = await getLiveEntry('coffee', 'recommendation');

if (error) {
  console.error('Could not load coffee recommendation:', error);
}

---

<section class="coffee-recommend">
  {entry ? (
    <>
      <h2 class="coffee-recommend-title">
        We Recommend: {entry.data.title}
      </h2>
      <p class="coffee-recommend-desc">{entry.data.description}</p>
    </>
  ) : (
    <p class="coffee-recommend-desc">
      Today's recommendation is temporarily unavailable.
    </p>
  )}
</section>

<style>
  .coffee-recommend {
    display: block;
    padding: 1rem 1.5rem;
    border-radius: 12px;
    background: var(--cream);
    color: var(--coffee-dark);
    font-family: system-ui, sans-serif;
    font-size: 0.9rem;
    margin: 0 0 2rem;
  }

  .coffee-recommend-title {
    font-size: 1.1rem;
    font-weight: 600;
  }

  .coffee-recommend-desc {
    font-size: 0.9375rem;
    font-style: italic;
    margin-top: 0.25rem;
  }
</style>

Finally, we need to change the homepage so it displays the coffee recommendation.

We first (1) add export const prerender = false to opt the homepage into on-demand rendering, allowing it to fetch the live collection data at request time. Then, we (2) import and (3) add the CoffeeRecommendation component:

---
// /src/pages/index.astro

// (1) Sets on-demand rendering because it reads from a live collection
export const prerender = false;

import Layout from '../layouts/Layout.astro';

// (2) Imports the CoffeeRecommendation component
import CoffeeRecommendation from '../components/CoffeeRecommendation.astro';

import { getCollection } from 'astro:content';

/* ... */
---

<Layout title="Coffee Notes from Underground">
  <h1>Brewing Tips from Our Baristas</h1>

  <!-- (3) Adds the CoffeeRecommendation component -->
  <CoffeeRecommendation />
  
<!-- (the rest of the file stays the same) -->

<CoffeeRecommendation server:defer />

Now, the coffee recommendation has been added to the homepage. To test it, refresh the page a few times and watch for the recommendation to change:

6. Add Interactivity with and without Astro Islands​

We'll add interactivity to our coffee blog in two different ways:

• a Like button as a framework component (Preact)
• a reading progress bar as a Web Component

Create the following empty files in the src folder:

1. /src/components/LikeButton.jsx
2. /src/components/LikeButton.css
3. /src/components/ReadingProgressBar.astro

Astro uses an islands architecture for framework components, where interactive components can become client islands that Astro hydrates in the browser.

However, you can also build interactive components as Web Components using standard browser APIs on any Astro site, without shipping a framework runtime to the browser.

Before looking at the code, here's a brief comparison of island-based and browser-native interactivity in Astro development:

i. Add a Like Button as a Preact Island​

To add the Preact Like button, run the following command to install the Preact integration for Astro:

npx astro add preact

The installer will make changes to your astro.config.mjs and tsconfig.json files. When asked, accept the changes.

The LikeButton.jsx file defines a Preact component with local state that updates the button's text and styling when clicked:

/* /src/components/LikeButton.jsx */

import { useState } from 'preact/hooks';
import './LikeButton.css';

export default function LikeButton() {
  
  // The button starts in the "not liked" state
  const [liked, setLiked] = useState(false);

  return (
    <button
      class={`like-button ${liked ? 'is-liked' : ''}`}
      aria-pressed={liked}
      onClick={() => setLiked((liked) => !liked)}
    >
      {liked ? '☕ Liked' : '🤎 Like this post'}
    </button>
  );
}

Before adding the CSS, let's update the /src/pages/blog/[slug].astro file to see what the Like button looks like without styling:

---
// /src/pages/blog/[slug].astro

/* ... */

// (1) Imports the LikeButton component
import LikeButton from '../../components/LikeButton.jsx';

/* ... */
---

<Layout title={post.data.title}>
  <!-- ... -->

  <!-- (2) Adds the Like button to the page -->
  <LikeButton client:idle />

  <Content />
</Layout>

The client:idle directive tells Astro to hydrate the Preact component in the browser when the page has finished its initial work and the browser is idle. You can use different client:* directives to control when hydration happens. For example, client:load hydrates the component as soon as the page loads, while client:visible waits until the component enters the viewport.

Now open a blog post in the browser and test the button. If it works as intended, add the styling to the /src/components/LikeButton.css file:

/* /src/components/LikeButton.css */

.like-button {
  border: none;
  border-radius: 999px;
  padding: 0.5rem 1.2rem;
  font-family: system-ui, sans-serif;
  font-size: 0.95rem;
  cursor: pointer;
  background: var(--cream);
  color: var(--text);
  transition: background 0.15s ease, color 0.15s ease;
}

.like-button.is-liked {
  background: var(--accent);
  color: var(--text-on-accent);
}

/* Applies hover styles only on devices that support hovering 
   to avoid touch-device UX issues */
@media (hover: hover) {
  .like-button:not(.is-liked):hover {
    background: var(--accent);
    color: var(--text-on-accent);
  }

  .like-button.is-liked:hover {
    background: var(--coffee-dark);
  }
}

The Like button is now done; this is what you should see in the browser:

ii. Add a Reading Progress Bar as a Web Component​

We create the reading progress bar as a Web Component. Because the component uses only browser APIs for its client-side behavior, we don't need:

• a framework runtime
• a client:* directive
• Astro frontmatter, since there is no server-side component code

The ReadingProgressBar.astro file consists of a custom <reading-progress-bar> element and a <script> that defines its behavior:

<!-- /src/components/ReadingProgressBar.astro -->

<reading-progress-bar>
  <div class="bar"></div>
</reading-progress-bar>

<script>
  class ReadingProgressBar extends HTMLElement {

    // Stores the visible bar and the pending animation-frame ID
    bar: HTMLElement | null = null;
    rafId: number | undefined;
    scrollableHeight = 0;

    // Calculates how far the document can be scrolled vertically
    updateScrollableHeight = () => {
      this.scrollableHeight =
        document.documentElement.scrollHeight - window.innerHeight;
    };

    // Converts scroll position to a 0–1 value and clamps the result
    updateProgress = () => {
      const scrollTop = window.scrollY;

      const progress =
        this.scrollableHeight > 0
          ? Math.min(Math.max(scrollTop / this.scrollableHeight, 0), 1)
          : 0;

      if (this.bar) {

        // Sets the bar's width as a percentage of scroll progress
        this.bar.style.width = `${progress * 100}%`;
      }

      // Allows the next scroll or resize event to schedule another update
      this.rafId = undefined;
    };

    // Schedules a progress update for the next animation frame
    onScroll = () => {
      if (this.rafId === undefined) {
        this.rafId = requestAnimationFrame(this.updateProgress);
      }
    };

    // Schedules a scrollable-height recalculation and progress update
    // for the next animation frame
    onResize = () => {
      if (this.rafId === undefined) {
        this.rafId = requestAnimationFrame(() => {
          this.updateScrollableHeight();
          this.updateProgress();
        });
      }
    };

    connectedCallback() {

      // Finds the visible bar that represents reading progress
      this.bar = this.querySelector<HTMLElement>('.bar');

      // Waits until the next animation frame before measuring the document
      requestAnimationFrame(() => {
        this.updateScrollableHeight();
        this.updateProgress();
      });

      window.addEventListener('scroll', this.onScroll);
      window.addEventListener('resize', this.onResize);
    }

    disconnectedCallback() {

      // Removes listeners and cancels any pending update
      window.removeEventListener('scroll', this.onScroll);
      window.removeEventListener('resize', this.onResize);

      if (this.rafId !== undefined) cancelAnimationFrame(this.rafId);

      this.rafId = undefined;
    }
  }

  customElements.define('reading-progress-bar', ReadingProgressBar);
</script>

<style>
  reading-progress-bar {
    position: fixed;
    top: 0;
    left: 0;
    display: block;
    width: 100%;
    height: 10px;
    z-index: 50;
  }

  .bar {
    height: 100%;
    width: 0%;
    background: var(--accent);
  }
</style>

The connectedCallback() and disconnectedCallback() methods above are lifecycle callbacks for Web Components:

• connectedCallback() finds the bar element, measures the page's scrollable height, sets the initial progress, and adds the scroll and resize event listeners.
• disconnectedCallback() removes both listeners and cancels any pending update when the element is removed, so the component cleans up after itself.

Both the scroll and resize listeners schedule their updates with requestAnimationFrame(), rather than running on every event. A shared rafId field makes sure only one update is ever pending at a time. If multiple scroll or resize events fire before that update runs, they're effectively batched into the same animation-frame update.

Finally, we need to add the <ReadingProgressBar> component to the /src/pages/blog/[slug].astro template:

<!-- /src/pages/blog/[slug].astro -->

<Layout title={post.data.title}>
  <ReadingProgressBar />

  <!-- ... -->
</Layout>

The reading progress bar should now appear at the top of each blog post:

7. Deploy the Coffee Blog to Cloudflare Workers​

Before deploying the coffee blog to Cloudflare Workers, we need to add the Cloudflare adapter. To do so, run the following command in the terminal:

npx astro add cloudflare

This single command installs the Cloudflare adapter, updates astro.config.mjs, and adds the wrangler.jsonc configuration file.

After installing the adapter, add a "worker" script to "scripts" in the package.json file so you can easily run the site using Cloudflare's local Workers runtime:

"worker": "wrangler dev"

Then, run the following commands:

npm run build
npm run worker

The first one builds the site with the Cloudflare adapter. As part of the build, Astro generates the Wrangler configuration that wrangler dev uses to run the site locally.

The second command starts the built site using Cloudflare's local Workers runtime. The first time you run it, Wrangler will ask you to authorize access to your Cloudflare account. After authorization, it starts the Worker locally and provides a local URL where you can test the site.

If you want to preview the production build without the Cloudflare runtime, run the following commands instead, which use Astro's preview server rather than Cloudflare's local Workers runtime:

npm run build
npm run preview

Once you've verified that the site works locally, push the repository to GitHub or GitLab, connect it from the Cloudflare dashboard, follow the steps in Cloudflare's Create an app wizard, and deploy the coffee blog. For example, here's mine:

From now on, whenever you push changes to your repository, Cloudflare will automatically redeploy your site.

8. Test the Coffee Blog for Performance​

Finally, let's see how Astro performs on the live site. You can use Lighthouse in Chrome DevTools or our free website speed test tool.

Here are the results for the homepage in a DebugBear mobile test:

While these are strong results, keep in mind that the page doesn't contain any images or other media that could meaningfully affect its performance. For example, pulling in Sample APIs' coffee images for the live content collection could be a good next performance test.

If you click the Requests menu, you'll also see the request waterfall chart. It shows that the homepage makes just two requests: one for the HTML document and one for the favicon. There is no JavaScript to download, and the CSS is inlined in the HTML:

Let's run another mobile test for one of the blog posts:

The scores are a little better compared to the homepage, even though the page also loads JavaScript here. Don't read too much into small differences in these lab measurements, however, as performance tests can slightly vary between runs.

A more useful comparison is the number and type of resources the browser has to load. If we navigate to the Requests menu, we can see that the blog post makes six requests in total, compared to just two for the homepage:

Three of the four JavaScript requests come from Preact. And while the files are not large, the question still arises: do we really need to ship the Preact runtime just to add a Like button?

Not necessarily. We could easily implement the Like button as a Web Component instead, using the browser's built-in APIs. That would let us remove Preact from this component and avoid the framework runtime and its associated JavaScript requests. This is the approach I'd use on a real-world Astro site.

Create Your Own Astro Site​

Use this tutorial as a starting point for your own Astro site, or keep improving the coffee blog.

For example, you could make the Like button persistent or rebuild it as a Web Component. You could also use the tags already in the frontmatter of the blog posts to add tag archive pages, or take the blog in a completely different direction (e.g., Sample APIs provide many other APIs as well).

You could also refurbish your own old blog with some brand-new features, such as a live RSS feed, a dynamic portfolio, a /now page with live content, or anything else you think could move the web forward.

If you make something worth sharing, send us the link by email to matt [at] debugbear dot com with the subject line "PerfTuts example"; we'll add selected examples to this article and let the tutorial grow with the community.

See How Your Astro Site Performs for Real Users​

You can also see how your Astro site performs from your visitors' perspective using DebugBear's real user monitoring (RUM) feature.

Sign up for our 14-day free trial (no credit card required) and add the RUM script you can find at the bottom of the RUM > Settings page to the <head> section of the /src/layouts/Layout.astro file:

In addition to real user monitoring, you can also run lab tests under different scenarios from various test locations around the world.

Get started with our 14-day free trial so you can test your Astro site both proactively and in real time.

While the overall messaging of the page has been consistent over time, the visual appearance has received several major overhauls.

In this article, we take a look at the recent changes as well as the evolution of example.com over the last 20+ years.

What changed on 28 September 2026?​

Until 28 September 2026, example.com was a static English-language page. The redesign introduces multi-language support using JavaScript, showing the content in a new language every 5 seconds.

Example.com shows an explanation of the site's purpose in English, Arabic, Chinese, French, Russian and Spanish. This is the English-language message:

This domain is for use in documentation examples without needing permission. This is not a service, avoid relying on it for testing and monitoring purposes.

Along with introducing multi-language support, the JavaScript code also inserts an SVG book icon.

How does the language transition animation work?​

The new site doesn't just replace the content when showing the next language. Instead, there's a gradual opacity transition.

The opacity animation itself just uses transition: opacity .4s;. But how is the character-by-character transition implemented?

Each character is wrapped in its own span element, and each span gets a slightly larger CSS transition-delay than the one before it. That means each character's opacity animation happens at a slightly different time.

More changes on 3 October 2026​

Example.com has now removed the animation and shows all languages right from the start:

Statement from IANA​

IANA provided the following statement explaining the reasoning behind the recent changes:

The changes we make to the site from time-to-time are usually informed by a desire to either reduce the overall bandwidth demands of serving the site, or improve its utility. At its heart it is a placeholder for a site no-one should be accessing, but we have historically showed a message there to inform visitors about why the domain is registered and how they may use it.

As it tends to be heavily trafficked, the overall bandwidth is a key consideration, and to that end one of the changes we made this week was to split the page content into a more basic page, augmented by a separate Javascript file with additional content beyond that. Since most of the traffic to the site is automated it tends not to fetch the Javascript file, reducing overall data requirements.

The fundamental purpose of the domain is for use in documentation, such as illustrative examples you may find in instructions. We know that people may, for example, cut-and-paste a sample configuration file and forget to customize entries that contain an example domain, and we expect we get some incidental traffic from that. However, the domain isn't intended to be a general purpose endpoint for things like availability testing so we do not encourage that kind of usage. There is no requirement there is a HTTP service present on the host in order to fulfill its purpose, we just operate it as a courtesy.

January 20, 2002: What did the earliest version look like?​

According to Wikipedia, the example.com website launched on January 1, 1999. The earliest version available to view in the Wayback Machine is from January 20, 2002.

The earliest version of the website only featured a list of domain names reserved by the Internet Corporation for Assigned Names and Numbers (ICANN) and IANA.

In the .com, .net, and .org top-level domains (TLDs), various domain names are reserved. These names are reserved from initial registration, but to the extent they are already registered the existing registrant may renew them.

Structurally, the HTML used a table layout, with the ICANN logo positioned in the top left corner of the page.

The server headers show that the site used Apache 1.3.22 at this point.

March 28, 2002: simplified messaging​

The first version of the example.com wording we recognize today came 67 days after the first available screenshot:

You have reached this web page by typing "example.com", "example.net", or "example.org" into your web browser.

These domain names are reserved for use in documentation and are not available for registration.

February 7, 2003: RFC 2606 citation added​

In February 2003, the content was amended to include a link to RFC 2606, the official document for reserved top-level and second-level domains, so visitors could find more information on the website's purpose.

There was also a small technical change around this time: the server was upgraded to Apache 1.3.27 on Red Hat Linux.

July 30, 2010: .edu added to domain list​

The website then went unchanged for seven years. On July 30, 2010, a slight change was made: example.edu was now pointed to the landing page, alongside the three previous domains.

July 29, 2013: migration and landing page redesign​

From January 2011, example.com didn't serve its own page. Instead, it redirected visitors to a page on IANA's website.

That changed on July 29, 2013, when the redirect was removed and example.com began serving its own page from the EdgeCast Content Delivery Network (CDN) instead of Apache, alongside a major redesign of the landing page. The new design used a rounded card with an <h1> reading 'Example Domain' and a new description of the website's purpose.

The viewable domain list was now gone, with a link to IANA's website for more information.

October 17, 2019: font and copy changes​

A new update came six years after the biggest change in the website's history. The layout remained the same, but the font stack was modernized to include more fallback fonts for devices such as Macs, iPhones, and Windows PCs.

The copy was tweaked slightly, with 'is for use in illustrative examples' replacing 'established to be used' and 'in literature' replacing 'in examples'.

January 15, 2025: infrastructure switch​

Almost twelve years after the switch from Apache to the EdgeCast CDN, another infrastructure change took place: the Server header disappeared entirely. The response headers alone don't reveal which platform was serving the page at this point.

A change of provider around this time isn't surprising. EdgeCast had been acquired from Yahoo by Limelight Networks in 2022 and rebranded as Edgio. Edgio then filed for Chapter 11 bankruptcy in late 2024, with Akamai acquiring select Edgio customer contracts.

October 9, 2025: redesign​

Later in 2025, the page was redesigned. The card design was dropped, and the HTML was minified. The copy was changed to a more direct message, again linking to IANA's website, with the link text changed from 'More information...' to 'Learn more'.

December 17, 2025: Cloudflare migration​

Less than a year after the previous switch, the infrastructure changed again: the site now serves from Cloudflare, as indicated by the cloudflare server header and CF-RAY header in the response. Whatever platform served the page after the January 2025 change, it has now been replaced with a Cloudflare-fronted setup.

June 9, 2026: favicon and HTML tweaks​

The next update, on June 9, 2026, brought no visual changes. The only HTML changes on the page itself were a favicon tag being added and the <p> tags being closed. The page now includes an empty favicon:

<link rel="icon" href="data:," />

This avoids a lot of unnecessary requests, as otherwise browsers look for a favicon at /favicon.ico.

Avoid relying on it for testing and monitoring purposes​

Example.com first introduced an "Avoid use in operations" message in 2025.

For developers, it's tempting to use example.com to check if the network is working or test HTTP requests. The example server likely receives a lot of traffic through this.

However, as the page now clarifies, it's not a service you can rely on. When we look at our uptime monitoring data, we can see that every now and then the example.com server doesn't respond correctly.

Using infrastructure that your organization controls can be more reliable.

Conclusion​

Looking at the visual timeline, we can see that changes to example.com happen sporadically. Sometimes a couple of small tweaks happen in back-to-back months. Other times the website remains untouched for periods of up to seven years.

We have been monitoring the page for several years in our public demo project. The Chrome UX Report (CrUX) data shows how page speed has changed over time.

To learn more about how your website is performing, sign up for a free 14-day DebugBear trial.

Monitor Page Speed & Core Web Vitals

DebugBear monitoring includes:

• In-depth Page Speed Reports
• Automated Recommendations
• Real User Analytics Data

Start Free TrialGo To App

I’ve been in this game long enough to recognize tooling improvements from software companies at the bleeding edge of technique and application and it usually goes something like this: “If we make it easier for developers to create software, they will have more bandwidth to produce higher quality software!”

I’m always left wondering (suspecting the answer with hopeful optimism that my hunch is wrong this time): do these workflow improvements actually improve how people (technical or otherwise) experience software? Certainly we have more software. But is it better? I don’t know.

Front-end web developers have lived through a few cycles of this (seven or eight years of client rendering, fifteen years of the single-page-application-era smokescreen are a few that come to mind), sold as though improvements to developer experience would cause the reanimated corpse of Ronald Reagan himself to ask you for commit access to ship trickle-down improvements to user experience.

Is this cycle repeating the same playbook (on a more accelerated pace)? Certainly we’ve seen numerous recent anecdotal examples of software becoming less reliable over time (GitHub is the most recent scapegoat I’ve seen, but on my read they seem to be a second-order victim more than anything).

(Seems like a great time to be in the Monitoring/Status Page business)

With these seismic changes, I will continue to make the argument that craft defined as caring about the quality of output (independent of the tools used to generate the output) is more important than ever. Caring about what you ship will always have real-world value to visitors/consumers/users real people.

Prefers-reduced-motion respecting web performance filmstrips from the AI category on Speedlify, a category boasting a failing median Core Web Vitals score with 12 out of 13 sites failing Lighthouse performance and Axe accessibility checks.

Presenting: <icon-fall>:

• Demo
• Source code on GitHub

It’s in use on this page (if you are on my web site and not in a feed reader). You can also install it with npm install @zachleat/icon-fall.

It has options for count (attribute, number of icons) and a comma separated list of colors (via --icon-fall-colors custom property).

Yesterday, Google introduced new performance metrics to surface how ads impact user experience. You can find real-user data for these metrics in the Chrome User Experience Report, or check them yourself in Chrome DevTools.

New ad metrics in Google's CrUX report​

The Chrome User Experience Report provides real-world performance data for millions of websites, based on aggregated Chrome user data. Most prominently, CrUX reports the three Core Web Vitals metrics that tell you how fast your website loads, how quickly it responds to user interactions, and whether the page layout is stable.

Google has now introduced four additional metrics focusing on ad performance:

1. Ad Count: How many ads are displayed at once?
2. Ad Density: On average, how much of the page is covered by ads?
3. Ad CPU Weight: How much CPU processing time is caused by ad frames?
4. Ad Network Weight: How much data is loaded by ad frames?

You can use tools like our website speed test or Google's CrUX Vis tool to access this data.

These new metrics provide insights into the impact of ads that previously weren't available. Publishers and ad networks can use this data to assess and reduce web performance issues caused by online adverts.

We can also use these metrics to create rankings showing how much the performance cost of ads varies across websites. For example, this dashboard shows a ranking of news websites based on how much extra CPU processing ads are causing.

What are the new metrics?​

Let's take a closer look at the new metrics and what each one measures.

Ad Count​

This metric tells you how many ad elements are visible on the page. An ad element could be an iframe, an image, or a video. Chrome checks this count every second and reports the average.

For example, we can see 4 ads in this screenshot:

So if a user sees 1 ad for 10 seconds and then 2 ads for 30 seconds, the ad count for that visit would be (1 * 10 + 2 * 30) / (10 + 30) = 1.75.

Ad Density​

While the number of ads on a page is interesting, for the user it's more important how much of the page consists of ads and how much consists of the content they are interested in.

Ad Density measures what percentage of the page is covered by ad frames. For example, here 27% of the viewport is covered in ads.

Like ad count, this information is sampled every second and Chrome then reports an average.

Ad Weight: CPU​

Ads don't just take up space but also require CPU processing to load and update. The CPU weight metric reports how much time the page spends running JavaScript code in ad frames. JavaScript execution of ad scripts in the main frame is not counted.

If we collect a CPU profile on a news website, we can see that the page consists of a large number of iframes. Most of them load and execute a meaningful amount of JavaScript code.

Ad Weight: Network​

Finally, the network ad weight metric reports how much data ads are loading. You can see how many kilobytes or megabytes need to be transferred.

Like CPU weight, network weight is aggregated throughout the lifetime of the page.

This screenshot of the Chrome DevTools Network tab shows which ad-related resources are downloaded on the page.

How do the ad performance metrics work?​

Google's CrUX report is based on data from logged-in Chrome users who have opted in to analytics reporting. Chrome measures these ad performance metrics and reports them back to Google servers.

If a website receives enough data reports to preserve user privacy, Google then makes aggregate metric data for the website publicly available.

There are three important factors to keep in mind when interpreting the final reported value:

1. Google reports the 75th percentile value. Most visitors have a better experience, but 25% of visitors experience a worse impact than shown by the metric.
2. Only visits with ads are considered. A user with an ad blocker would be excluded from aggregated scores.
3. CrUX data is aggregated over a 28-day period. Any changes you make will take some time to show up in the metrics.

What websites are included?​

CrUX only reports ad metrics for websites that show third-party ads and have an ads.txt (Authorized Digital Sellers) file.

In general, websites need to be indexable and somewhat popular before they are included in the CrUX dataset.

How does Google detect ad frames and resources?​

Chrome detects whether an iframe is an ad by looking at the document URL. It uses a subset of EasyList to decide if the URL belongs to an ad network.

Individual resources outside of an ad frame can also be detected as ad-related. They will then contribute to the ad network weight metric.

In addition to checking the URL of requests, Chrome also looks at the JavaScript stack to decide if an ad script is requesting an additional ad-related resource.

Ad performance reporting in Chrome DevTools​

In addition to the CrUX metrics, Google is also introducing a new Ads reporting panel in Chrome DevTools.

You can try it in Chrome Canary right now. Just open DevTools, select the Application tab and then open the Ads UI from the sidebar.

Here you can see the values of the four ad performance metrics as well as a list of iframes and scripts that impact the page.

I've also ticked the Highlight ads checkbox to add the red highlight for each ad frame.

What makes this new CrUX data especially interesting?​

Publishers can use real user monitoring tools to get insight into the performance of content that's hosted on their own domain. But for security and privacy reasons, these tools can't access performance data from within iframes, which is how ads are most commonly embedded on websites.

Google's new data changes that: it's now possible to view real user data on how ads impact user experience. Lab tests with tools like Lighthouse can provide some insights on this, but they don't correctly reflect real-world usage and interaction patterns or the types of devices visitors are using.

How do ads impact Core Web Vitals?​

Google's ad performance metrics show whether ads are using CPU and network resources. But does this extra activity actually take resources away from the main page content and cause worse Core Web Vitals scores?

We can set up a custom dashboard in DebugBear and add a scatter plot to find out.

This screenshot shows that websites with more ad activity tend to have worse Interaction to Next Paint scores.

Monitor Page Speed & Core Web Vitals

DebugBear monitoring includes:

• In-depth Page Speed Reports
• Automated Recommendations
• Real User Analytics Data

Start Free TrialGo To App