For a project I was recently working on, the requirement was to use WordPress as the site's backend. Content management, blog posts, and media were all handled through the WordPress admin. The frontend was open: it could be a theme, a template, or something customized through Elementor.

I could've built the same result in Elementor, but the process would've been slower and harder to maintain. Drag-and-drop works until the design gets specific, and then every small tweak costs more time than it should.

As a full stack developer, writing code turned out to be faster for me and produced cleaner output. Tools like Claude Code make the iteration cycle even tighter. So I kept the requirement – WordPress as the backend – and decided to build the frontend separately in code.

I wanted to share how I did this so that, if you're facing similar requirements, you'll know the way forward.

By the end of this tutorial, you'll have:

• A WordPress install serving content through its REST API on a subdomain

• An Astro SSR frontend rendering the content on the root domain

• A Cloudflare Pages deployment triggered on every git push

• Security hardening for a headless WordPress setup

• Draft post preview working across both systems

Prerequisites: You should be comfortable with the command line, have basic familiarity with WordPress admin, and know enough JavaScript to read and write simple functions.

To follow along, you'll need a WordPress installation, a GitHub account, and a Cloudflare account.

Table of Contents

• Why Headless WordPress?

• The Architecture

• Why Astro?

• Infrastructure Setup

  • Step 1: Move DNS to Cloudflare

  • Step 2: Create the CMS Subdomain

• WordPress Configuration

  • Tell WordPress it Lives on the Subdomain

  • Must-Use Plugin: Redirect and Preview

  • Clean Up Plugins

• The Astro Frontend

  • astro.config.mjs

  • .env

  • src/lib/wordpress.js

  • src/middleware.js

  • src/layouts/Layout.astro

  • src/pages/blog/index.astro

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

  • src/pages/sitemap.xml.ts

  • src/styles/global.css

• CI/CD with Cloudflare Pages

• Final Thoughts

• Good to Know

Why Headless WordPress?

Headless WordPress separates content management from content delivery. WordPress keeps doing what it handles well: storing content and giving editors a familiar admin interface. A separate frontend handles rendering, routing, and performance.

A few situations where this split pays off:

• Your content team is trained on WordPress and moving them elsewhere would slow everyone down. Headless preserves their workflow and gives you a modern frontend.

• Your site needs a design or interaction pattern that a WordPress theme or page builder struggles to deliver. Custom dashboards, interactive tools, data-driven layouts, or integrations with non-WordPress APIs all fit here.

• You want edge delivery and modern tooling without rebuilding content management from scratch. WordPress handles content and media well. A JavaScript frontend on a CDN handles delivery well. Headless lets each side do its job.

• You need the same content across multiple surfaces. One WordPress install feeds a marketing site, a mobile app, and an internal dashboard through the same REST API.

Headless is not a fit for every site. Skip it if your site is a simple brochure, if one person does everything in the admin, or if you have no developer time to maintain a second codebase. A regular WordPress theme is the better answer there.

The Architecture

The term "headless" means you strip WordPress of its frontend responsibility. Instead of WordPress generating and serving HTML pages to visitors, it only stores and serves content through its REST API. A separate frontend framework, in this case Astro, handles what the visitor actually sees.

When a visitor loads a page, the request hits Cloudflare Pages, which runs the Astro server. Astro fetches the relevant content from WordPress via the REST API, builds the HTML, and returns it to the visitor. WordPress never touches the visitor's browser.

Content editors log into the WordPress admin at the CMS subdomain. They write, publish, and manage content as they normally would. The moment they publish, the content is live. There's no rebuild step because Astro fetches fresh data on every request.

The REST API has been built into WordPress since version 4.7. You don't need a GraphQL plugin, a paid headless CMS service, or any extra infrastructure.

Why Astro?

You could use Next.js, Nuxt, or SvelteKit here as well. But I chose Astro because its defaults fit this use case.

Astro compiles components to plain HTML and ships zero JavaScript to the browser by default. You only add client-side JavaScript where you explicitly need it.

For a CMS-driven site, most pages need none. SSR mode means every request fetches fresh data from WordPress at runtime, so content changes go live immediately without a rebuild. Cloudflare has an official adapter that handles the build output. Tailwind v4 integrates through a Vite plugin with no config file needed.

If WordPress wasn't a requirement, I would have used Next.js with Payload CMS. Payload gives you a fully typed CMS built in TypeScript that sits inside the same Next.js project, with more control over your content schema from day one. But the requirement was WordPress, and for a WordPress REST API frontend, Astro is the faster and cleaner choice.

Infrastructure Setup

Here's my setup: domain at Namecheap, WordPress on Hostinger shared hosting, and a Google Workspace email. The steps below apply to any host, whether shared hosting with cPanel or hPanel, a VPS with Apache or Nginx, or a self-managed server.

Step 1: Move DNS to Cloudflare

First, you'll need to move your domain's nameservers to Cloudflare. This gives you free DDoS protection, SSL, and the ability to attach a custom domain to Cloudflare Pages.

Before switching, verify that all DNS records transferred correctly, including your website A or CNAME records. For email, get your MX, SPF, DKIM, and DMARC values from your email provider's admin panel and add them to Cloudflare DNS first, otherwise email breaks during propagation.

Step 2: Create the CMS Subdomain

Move WordPress to cms.yourdomain.com so the root domain is free for Astro. In Cloudflare DNS, add an A record pointing cms at your server IP, or a CNAME if your host uses a CDN hostname. Then create the subdomain in your hosting panel pointing to the same WordPress directory.

One thing people miss: your server needs its own SSL certificate for the connection between Cloudflare and your origin to work. Cloudflare handles SSL at its edge, but if the origin has no certificate, you get a 525 error.

On Hostinger, this isn't automatic for new subdomains. Install it manually through hPanel. On cPanel, use Let's Encrypt. On a VPS, use Certbot.

Moving WordPress off the root domain also means /wp-admin no longer exists at your main domain, which reduces exposure. But the default login path is still /wp-admin on the subdomain. That is the first thing you should change — more on this in the Good to Know section at the end.

WordPress Configuration

Tell WordPress it Lives on the Subdomain

In wp-config.php, before the "That's all, stop editing!" comment:

define('WP_HOME',    'https://cms.yourdomain.com');
define('WP_SITEURL', 'https://cms.yourdomain.com');

WordPress admin is now at cms.yourdomain.com/wp-admin. The old path at the root domain stops working. That's intentional.

Must-Use Plugin: Redirect and Preview

WordPress has a folder called mu-plugins inside wp-content. Files placed there are treated as must-use plugins. They load automatically on every request, before regular plugins, and there is no way to activate or deactivate them through the admin UI. This makes them the right place for behaviour you never want accidentally turned off.

Create wp-content/mu-plugins/headless-redirect.php:

<?php
/*
Plugin Name: Headless Redirect
Description: Redirects frontend visitors to the Astro site and rewires the WordPress preview link.
*/

add_action('template_redirect', function() {
    if (is_user_logged_in()) return;
    if ($_SERVER['HTTP_HOST'] === 'cms.yourdomain.com') {
        wp_redirect('https://yourdomain.com', 302);
        exit;
    }
});

add_filter('preview_post_link', function(\(link, \)post) {
    $token = HEADLESS_PREVIEW_SECRET;
    \(type  = \)post->post_type;
    return 'https://yourdomain.com/preview?type=' . \(type . '&id=' . \)post->ID . '&token=' . $token;
}, 10, 2);

The template_redirect action fires when WordPress is about to render a page. If the visitor isn't logged in and the request is on the CMS subdomain, it redirects them to the main frontend. Logged-in editors pass through to the admin normally. REST API requests to /wp-json/... don't go through template_redirect at all, so they are unaffected.

The preview_post_link filter changes what happens when an editor clicks Preview on a draft post. By default, WordPress previews using its own theme, which in a headless setup renders blank.

This filter replaces that URL with a request to your Astro /preview page, passing the post ID, post type, and a secret token. Your Astro preview page uses those values to fetch the draft via the REST API and renders it exactly as it would appear live.

Clean Up Plugins

Now it's time to remove everything that renders the frontend: page builders, caching plugins, and hosting onboarding plugins.

But you'll want to keep Akismet, Wordfence, and Yoast SEO. Yoast adds SEO meta and Open Graph data directly to the REST API response, which your Astro pages read through post.yoast_head_json.

Then switch the active theme to a lightweight default. WordPress requires one active, but nobody sees it.

The Astro Frontend

Start with pnpm create astro@latest, then install the Cloudflare adapter and Tailwind:

pnpm add @astrojs/cloudflare
pnpm add -D @tailwindcss/vite tailwindcss

astro.config.mjs

import { defineConfig } from 'astro/config'
import cloudflare from '@astrojs/cloudflare'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  output: 'server',
  adapter: cloudflare({ imageService: 'passthrough' }),
  vite: { plugins: [tailwindcss()] },
})

output: 'server' puts Astro into full SSR mode. Without it, Astro pre-renders pages at build time, which breaks dynamic routes like /blog/[slug] that depend on WordPress content that didn't exist at build time.

imageService: 'passthrough' is required specifically for Cloudflare Workers. Astro's default image service uses Sharp, which depends on child_process and fs. Those Node.js built-ins don't exist in the Cloudflare Workers runtime. The deployment fails with a module resolution error. Setting passthrough skips image processing entirely and renders standard <img> tags instead.

.env

WORDPRESS_API_URL=https://cms.yourdomain.com

Add this same variable in Cloudflare Pages project settings under Environment Variables before deploying.

src/lib/wordpress.js

This file is the single place all WordPress API calls go through. Centralising them means if the API URL or authentication changes, you update one file.

The _embed parameter is important. By default, a post response only includes the post data. Featured images, author details, and categories are separate entities with their own IDs. Without _embed, you would need additional API requests to fetch each one. Adding it inlines all that related data into the same response.

cache: 'no-store' on every fetch call is not optional. Cloudflare Workers runs a fetch cache internally that's separate from HTTP Cache-Control headers. Without disabling it, Cloudflare caches your WordPress API responses at the edge. An editor publishes a post and sees the old version on the frontend because the cached response is being served.

const WP_URL = import.meta.env.WORDPRESS_API_URL

const fetchWP = (path) =>
  fetch(`\({WP_URL}\){path}`, { cache: 'no-store' }).then((r) => r.json())

export const getPosts = (page = 1, perPage = 10) =>
  fetchWP(`/wp-json/wp/v2/posts?_embed&per_page=\({perPage}&page=\){page}`)

export const getPostBySlug = async (slug) => {
  const posts = await fetchWP(`/wp-json/wp/v2/posts?_embed&slug=${slug}`)
  return posts[0]
}

export const getCategories = () =>
  fetchWP(`/wp-json/wp/v2/categories`)

export const getPostsByCategory = (categoryId, page = 1) =>
  fetchWP(`/wp-json/wp/v2/posts?_embed&categories=\({categoryId}&page=\){page}`)

export const getAllPostsForSitemap = () =>
  fetchWP(`/wp-json/wp/v2/posts?_fields=slug,modified&per_page=100`)

The sitemap function uses _fields instead of _embed to fetch only the fields it needs, keeping that request lightweight.

src/middleware.js

Middleware runs on every request before the page handler. This one adds Cache-Control: no-store to every SSR response so Cloudflare doesn't cache the rendered HTML pages.

export function onRequest(_context, next) {
  return next().then(response => {
    const newResponse = new Response(response.body, response)
    newResponse.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate')
    newResponse.headers.set('CDN-Cache-Control', 'no-store')
    return newResponse
  })
}

The original Response from Astro has immutable headers, so you can't call .headers.set() on it directly. The fix is to construct a new Response using the original body and response as the init argument. The new Response has mutable headers, so .set() works. CDN-Cache-Control is a Cloudflare-specific header that controls caching at the edge independently from the standard Cache-Control header.

src/layouts/Layout.astro

Every page goes through this layout. HTML structure, meta tags, and global imports live here so you don't repeat them on every page.

---
interface Props {
  title: string
  description?: string
}
const { title, description = '' } = Astro.props
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{title}</title>
    <meta name="description" content={description} />
  </head>
  <body>
    <slot name="nav" />
    <main id="main-content"><slot /></main>
    <slot name="footer" />
  </body>
</html>

Named slots let the navbar and footer sit outside <main>, keeping the HTML landmark structure correct for accessibility.

src/pages/blog/index.astro

---
import Layout from '../../layouts/Layout.astro'
import { getPosts, getCategories, getPostsByCategory } from '../../lib/wordpress'

const page = Number(Astro.url.searchParams.get('page') ?? 1)
const categoryId = Astro.url.searchParams.get('category')

const [posts, categories] = await Promise.all([
  categoryId ? getPostsByCategory(categoryId, page) : getPosts(page, 10),
  getCategories(),
])
---
<Layout title="Blog">
  <nav>
    <a href="/blog">All</a>
    {categories.map((cat) => (
      <a href={`/blog?category=${cat.id}`}>{cat.name}</a>
    ))}
  </nav>

  <ul>
    {posts.map((post) => {
      const image   = post._embedded?.['wp:featuredmedia']?.[0]?.source_url
      const imageAlt = post._embedded?.['wp:featuredmedia']?.[0]?.alt_text ?? ''
      return (
        <li>
          {image && <img src={image} alt={imageAlt} />}
          <a href={`/blog/${post.slug}`} set:html={post.title.rendered} />
          <div set:html={post.excerpt.rendered} />
        </li>
      )
    })}
  </ul>

  {page > 1 && <a href={`/blog?page=${page - 1}`}>Previous</a>}
  <a href={`/blog?page=${page + 1}`}>Next</a>
</Layout>

Promise.all fetches posts and categories in parallel. The category filter reads from the URL query string so the same page handles both /blog and /blog?category=5 without separate routes.

Featured images live inside post._embedded['wp:featuredmedia'][0] because _embed inlines the media object into the post response.

src/pages/blog/[slug].astro

---
import Layout from '../../layouts/Layout.astro'
import { getPostBySlug } from '../../lib/wordpress'

const { slug } = Astro.params
const post = await getPostBySlug(slug)
if (!post) return Astro.redirect('/404')

const image    = post._embedded?.['wp:featuredmedia']?.[0]?.source_url
const imageAlt = post._embedded?.['wp:featuredmedia']?.[0]?.alt_text ?? ''
const author   = post._embedded?.author?.[0]?.name
const seoTitle = post.yoast_head_json?.title ?? post.title.rendered
const seoDesc  = post.yoast_head_json?.og_description ?? ''
---
<Layout title={seoTitle} description={seoDesc}>
  <article>
    <h1 set:html={post.title.rendered} />
    <p>{author} · {new Date(post.date).toLocaleDateString()}</p>
    {image && <img src={image} alt={imageAlt} />}
    <div set:html={post.content.rendered} />
  </article>
</Layout>

Use set:html for WordPress content, not {post.content.rendered}. Astro treats curly brace expressions as text and escapes the HTML, so you see raw tags printed on the page instead of rendered content.

Always guard with if (!post) return Astro.redirect('/404'). If someone visits a slug that doesn't exist, the API returns an empty array. Without the guard, accessing properties on undefined throws an error that crashes the Cloudflare Worker and returns a 500.

post.yoast_head_json is available when Yoast SEO is active. It contains the computed SEO title and description that Yoast generates. Using it means the SEO work done in WordPress carries over to the Astro frontend automatically.

src/pages/sitemap.xml.ts

import type { APIRoute } from 'astro'
import { getAllPostsForSitemap } from '../lib/wordpress'

export const GET: APIRoute = async () => {
  const posts = await getAllPostsForSitemap()

  const urls = [
    { loc: 'https://yourdomain.com/', lastmod: new Date().toISOString() },
    { loc: 'https://yourdomain.com/blog/', lastmod: new Date().toISOString() },
    ...posts.map((p) => ({
      loc: `https://yourdomain.com/blog/${p.slug}/`,
      lastmod: p.modified,
    })),
  ]

  const xml = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
\({urls.map((u) => `  <url>\n    <loc>\){u.loc}</loc>\n    <lastmod>${u.lastmod}</lastmod>\n  </url>`).join('\n')}
</urlset>`

  return new Response(xml, { headers: { 'Content-Type': 'application/xml' } })
}

This generates fresh XML on every request, so the sitemap always reflects currently published posts without a rebuild.

src/styles/global.css

@import "tailwindcss";

@theme {
  --color-brand: #your-color;
  --font-sans: 'Your Font', sans-serif;
}

Tailwind v4 uses CSS-first configuration through the @theme block. CSS variables defined here become Tailwind utilities automatically. --color-brand becomes bg-brand, text-brand, and so on. No tailwind.config.js needed.

CI/CD with Cloudflare Pages

With the Astro code in place, the last piece is getting it deployed. Cloudflare Pages connects directly to GitHub, so you don't have to maintain a separate pipeline.

Here are the steps:

1. Push your repo to GitHub.

2. Go to Cloudflare Pages, create a project, connect it to your GitHub repository.

3. Set the build command to pnpm build and the output directory to dist.

4. Under Environment Variables, add WORDPRESS_API_URL pointing to https://cms.yourdomain.com.

5. Deploy.

After the first deploy, every push to main triggers a new deployment automatically. Cloudflare runs the build, and within minutes the new version is live globally. Content updates in WordPress go live immediately, since Astro fetches from WordPress on every request. A developer pushing code and an editor publishing a post are completely independent operations.

Final Thoughts

This setup exists because of the specific requirement that the content team was already on WordPress and changing that was not on the table.

If you're starting fresh with no CMS in place, this is probably not the stack you want. Go with something like Next.js and Payload CMS where the backend and frontend are designed to work together from the start.

But if your situation matches where content editors are already familiar with WordPress, and you need a custom frontend that a page builder can't deliver cleanly, then this separation makes sense.

Pros:

• Content editors keep using WordPress. No retraining, no migration.

• The frontend has full control over design and behaviour. No theme or plugin constraints.

• Deployments are automatic on every push. Content changes go live immediately without a rebuild.

• No added cost for most sites. WordPress stays on its existing host. Cloudflare Pages is free within generous limits, and scales to $5 per month on the Workers Paid plan if you outgrow them.

Cons:

• Two systems to maintain instead of one. You operate the WordPress install (updates, plugins, backups) and maintain the Astro codebase separately.

• The WordPress REST API has limitations. Complex content structures or real-time features need more work to handle compared to a purpose-built headless CMS.

• Adapter and deployment target are tied together. @astrojs/cloudflare v13 drops Pages support in favor of Workers, so staying on Pages means staying on v12. Details in the Good to Know section.

• Frontend changes require a developer. With Elementor, anyone with admin access could adjust layouts directly in the browser. Here, any visual change outside of content goes through code, which means it goes through you.

The stack is WordPress on existing hosting, Astro on Cloudflare Pages, with GitHub as the bridge between development and production. It solves a specific problem cleanly. Outside of that problem, there are better options.

Good to Know

Change the default login URL immediately. Every bot targets /wp-login.php and /wp-admin. Install WPS Hide Login and move it to something custom. Anyone hitting the default paths gets a 404.

Remove the /wp-json/wp/v2/users endpoint. It returns a public list of usernames. In headless mode you get author data through _embed and have no use for this endpoint. Add to the mu-plugin:

add_filter('rest_endpoints', function($endpoints) {
    unset($endpoints['/wp/v2/users']);
    unset($endpoints['/wp/v2/users/(?P<id>[\d]+)']);
    return $endpoints;
});

Disable XML-RPC and enable 2FA. Add add_filter('xmlrpc_enabled', '__return_false') to the mu-plugin — you aren't using it in headless mode and it's a common brute force target. Enable Wordfence's Brute Force Protection and add two-factor authentication through WP 2FA for all admin accounts.

Don't upgrade @astrojs/cloudflare to v13 if you deploy via Cloudflare Pages git-push CI. v12 outputs dist/_worker.js which Pages CI expects. v13 outputs a different format for wrangler deploy — Pages CI falls back to serving the dist folder as a static site and every SSR route returns 404 with no helpful error message.

The v12 adapter throws a deprecation warning on entrypointResolution. Silence it by adding entrypointResolution: 'auto' to the adapter options. Test before committing — it changes how the build locates the Worker entry file.

Custom Post Types follow the same pattern. Register the CPT with show_in_rest: true and a rest_base, and it shows up at /wp-json/wp/v2/your-base. The same fetch helpers, _embed, and slug routing work exactly the same way.

The REST API returns pagination headers. The raw response includes X-WP-Total and X-WP-TotalPages headers before you call .json(). If you want proper previous/next pagination, read those instead of guessing whether a next page exists.

Wrap API calls in try/catch. If WordPress is unreachable, an unhandled fetch throws and returns a 500. A try/catch returns an empty page instead, which is a much better failure mode.

Preview auth uses Application Passwords. WordPress 5.6 added Application Passwords under Users → Profile. That's what WP_APP_USER and WP_APP_PASSWORD in your .env should point to — not your regular admin password. Generate one per environment. Define the preview token as a constant in wp-config.php (define('HEADLESS_PREVIEW_SECRET', '...')) and reference that constant in the mu-plugin — never hardcode secrets in version-controlled files.

By the end, you'll have a fully functional authentication system with Astro actions, magic link authentication using Supabase, bot protection via Cloudflare Turnstile, protected routes and middleware, and secure session management.

Table of Contents

• Prerequisites

• Understanding the Technologies

  • What is Astro?

  • What are Astro Actions?

  • What is Supabase?

  • What is Cloudflare Turnstile?

• Understanding SSR Authentication

  • SSR vs. SPA Authentication

• Why Protect Auth Forms?

• Part 1: How to Set Up the Backend

  • Set Up Supabase Backend

  • Set Up Cloudflare Turnstile

• Part 2: How to Set Up the Frontend

  • Create the Astro Project

  • Configure Astro for SSR

  • Install Supabase Dependencies

  • Configure Environment Variables

• Part 3: How to Set Up Supabase SSR

  • Create the Supabase Client

  • Create Middleware for Route Protection

• Part 4: How to Build the User Interface

  • Update the Layout

  • Create the Sign-In Page

  • Create the Protected Page

• Part 5: How to Set Up Astro Actions

  • Create the Authentication Actions

  • Create the Code Exchange API Route

• Part 6: How to Test Your Application

• Notes and Additional Resources

  • Useful Documentation

  • Complete Code Repository

Prerequisites

This tutorial assumes you are familiar with:

• Web development frameworks

• Basic authentication flows

• Basic Backend-as-a-Service (BaaS) concepts

Understanding the Technologies

What is Astro?

Astro is a UI-agnostic web framework that renders server-first by default. It can be used with any UI framework, including Astro client components.

What are Astro Actions?

Astro actions allow you to write server-side functions that can be called without explicitly setting up API routes. They provide many useful utilities that simplify the process of running server logic and can be called from both client and server environments.

What is Supabase?

Supabase is an open-source Backend-as-a-Service that builds upon Postgres. It provides key features such as authentication, real-time capabilities, edge functions, storage, and more. Supabase offers both a hosted version for easy scaling and a self-hostable version for full control.

What is Cloudflare Turnstile?

Turnstile is Cloudflare's replacement for CAPTCHAs, which are visual puzzles used to differentiate between genuine users and bots. Unlike traditional CAPTCHAs, which are visually clunky, annoying, and sometimes difficult to solve, Turnstile detects malicious activity without requiring users to solve puzzles, while providing a better user experience.

Understanding SSR Authentication

Server-side rendered (SSR) auth refers to handling authentication on the server using a cookie-based authentication method.

The flow works as follows:

1. The server creates a session and stores a session ID in a cookie sent to the client

2. The browser receives the cookie and automatically includes it in future requests

3. The server uses the cookie to determine if the user is authenticated

Since browsers cannot modify HTTP-only cookies and servers cannot access local storage, SSR authentication requires careful management to prevent security risks such as session hijacking and stale sessions.

SSR vs. SPA Authentication

Single-Page Applications (SPAs), like traditional React apps, handle authentication on the client side because they don't have direct access to a server. SPAs typically use JWTs stored in local storage, cookies, or session storage, sending these tokens in HTTP headers when communicating with servers.

Why Protect Auth Forms?

Authentication protects sensitive resources from unauthorized access, making auth forms primary targets for bots and malicious actors. Taking extra precautions is important for maintaining security.

Part 1: How to Set Up the Backend

Set Up Supabase Backend

First, you'll need a Supabase account. Create a project, then:

1. Go to the Authentication tab in the sidebar

2. Click the Sign In / Up tab under Configuration

3. Enable user sign-ups

4. Scroll down to Auth Providers and enable email (disable email confirmation for this tutorial)

Set Up Cloudflare Turnstile

1. Log in or register for a Cloudflare account

2. Click the Turnstile tab in the sidebar

3. Click the "Add widget" button

4. Name your widget and add "localhost" as the hostname

5. Leave all other settings as default, and create the widget

After creating the widget, copy the secret key and add it to your Supabase dashboard:

1. Go back to Supabase Authentication settings

2. Navigate to the Auth Protection tab under Configuration

3. Turn on Captcha protection

4. Choose Cloudflare as the provider

5. Paste your secret key

Part 2: How to Set Up the Frontend

Create the Astro Project

Next, you will need to create an Astro project. Open your preferred IDE or Text editor’s integrated terminal and run the following command to scaffold an Astro project in a folder named “ssr-auth.” Feel free to use any name you like.

npm create astro@latest ssr-auth

Follow the provided prompts and choose a basic template to start with. When it’s done, change into the folder, then run npm install to install dependencies, followed by npm run dev to start the server, and your site will be available at localhost:4321.

Configure Astro for SSR

Set Astro to run in SSR mode by adding output: "server", to the defineConfig function found in the astro.config.mjs file at the root of the folder.

Next, add an adapter to create a server runtime. For this, use the Node.js adapter by running this command in a terminal: npx astro add node. This will add it and automatically make all relevant changes.

Finally, add Tailwind for styling. Run this command in a terminal window: npx astro add tailwind. Follow the prompts, and it will make any changes necessary.

At this stage, your astro.config.mjs should look like this:

// @ts-check
import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import tailwindcss from "@tailwindcss/vite";

// https://astro.build/config
export default defineConfig({
  output: "server",
  adapter: node({
    mode: "standalone",
  }),
  vite: {
    plugins: [tailwindcss()],
  },
});

Install Supabase Dependencies

You can do this by running the following command:

npm install @supabase/supabase-js @supabase/ssr

Configure Environment Variables

Create a .env file in the project root and add the following. Remember to replace with your actual credentials:

SUPABASE_URL=<YOUR_URL>
SUPABASE_ANON_KEY=<YOUR_ANON_KEY>
TURNSTILE_SITE_KEY=<YOUR_TURNSTILE_SITE_KEY>

You can get the Supabase values from the dashboard:

💡Note: In Astro, environment variables accessed on the client side must be prefixed with 'PUBLIC'. But since we're using Astro actions that run on the server, the prefix is not required.

Part 3: How to Set Up Supabase SSR

Create the Supabase Client

Create src/lib/supabase.ts:

import { createServerClient, parseCookieHeader } from "@supabase/ssr";
import type { AstroCookies } from "astro";

export function createClient({
    request,
    cookies,
}: {
    request: Request;
    cookies: AstroCookies;
}) {
    const cookieHeader = request.headers.get("Cookie") || "";

    return createServerClient(
        import.meta.env.SUPABASE_URL,
        import.meta.env.SUPABASE_ANON_KEY,
        {
            cookies: {
                getAll() {
                    const cookies = parseCookieHeader(cookieHeader);
                    return cookies.map(({ name, value }) => ({
                        name,
                        value: value ?? "",
                    }));
                },
                setAll(cookiesToSet) {
                    cookiesToSet.forEach(({ name, value, options }) =>
                        cookies.set(name, value, options)
                    );
                },
            },
        }
    );
}

This sets up Supabase to handle cookies in a server-rendered application and exports a function that takes the request and cookies object as input. The function is set up like this because Astro has three ways to access request and cookie information:

• Through Astro’s global object, which is only available on Astro pages.

• Through AstroAPIContext object, which is only available in Astro actions.

• Through APIContext which is a subset of the global object and is available through API routes and middleware.

So the createClient function accepts the request and cookies objects separately to make it flexible and applicable in the various contexts in which it may be used.

Create Middleware for Route Protection

Next, create a middleware.ts file in the src folder and paste this into it:

import { defineMiddleware } from "astro:middleware";
import { createClient } from "./lib/supabase";

export const onRequest = defineMiddleware(async (context, next) => {
    const { pathname } = context.url;

    console.log("Middleware executing for path:", pathname);

    const supabase = createClient({
        request: context.request,
        cookies: context.cookies,
    });

    if (pathname === "/protected") {
        console.log("Checking auth for protected route");

        const { data } = await supabase.auth.getUser();

        // If no user, redirect to index
        if (!data.user) {
            return context.redirect("/");
        }
    }

    return next();
});

This middleware checks for an active user when accessing the protected route and redirects unauthenticated users to the index page.

Part 4: How to Build the User Interface

Update the Layout

First, update src/layouts/Layout.astro to include the Turnstile script. Add this just above the closing </head> tag:

<script
    src="https://challenges.cloudflare.com/turnstile/v0/api.js"
    async
    defer>
</script>

Create the Sign-In Page

Replace the contents of src/pages/index.astro:

---
import Layout from "../layouts/Layout.astro";
import { createClient } from "../lib/supabase";
import "../styles/global.css";

const supabase = createClient({
    request: Astro.request,
    cookies: Astro.cookies,
});

const { data } = await supabase.auth.getUser();

if (data.user) {
    return Astro.redirect("/protected");
}

const apiKey = import.meta.env.TURNSTILE_SITE_KEY;
---

<Layout>
    <section class="flex flex-col items-center justify-center m-30">
        <h1 class="text-4xl text-left font-bold mb-12">Sign In to Your Account</h1>
        <form id="signin-form" class="flex flex-col gap-2 w-1/2">
            <label for="email" class="">Enter your email</label>
            <input
                type="email"
                name="email"
                id="email"
                placeholder="youremail@example.com"
                class="border border-gray-500 rounded-md p-2"
                required
            />
            <div class="cf-turnstile" data-sitekey={apiKey}></div>
            <button
                type="submit"
                id="sign-in"
                class="bg-gray-600 hover:bg-gray-700 p-2 rounded-md text-white font-bold w-full cursor-pointer disabled:bg-gray-500 disabled:hover:bg-gray-500 disabled:cursor-not-allowed"
                >Sign In</button
            >
        </form>
    </section>
</Layout>

Here, the frontmatter creates a Supabase server client and then uses it to check if we have an active user. It redirects based on this information. This works because the front matter runs on the server side, and the project is set to server output.

The template displays a simple form with an email input. To complete it, add this below the closing </Layout> tag:

<script>
    import { actions } from "astro:actions";

    declare global {
        interface Window {
            turnstile?: {
                reset: () => void;
            };
        }
    }

    const signInForm = document.querySelector("#signin-form") as HTMLFormElement;
    const formSubmitBtn = document.getElementById("sign-in") as HTMLButtonElement;

    signInForm?.addEventListener("submit", async (e) => {
        e.preventDefault();
        formSubmitBtn.disabled = true;
        formSubmitBtn.textContent = "Signing in...";

        try {
            const turnstileToken = (
                document.querySelector(
                    "[name='cf-turnstile-response']"
                ) as HTMLInputElement
            )?.value;

            if (!turnstileToken) {
                throw new Error("verification_missing");
            }

            const formData = new FormData(signInForm);
            formData.append("captchaToken", turnstileToken);

            const results = await actions.signIn(formData);

            if (!results.data?.success) {
                if (results.data?.message?.includes("captcha protection")) {
                    alert("Verification failed. Please try again.");
                    if (window.turnstile) {
                        window.turnstile.reset();
                    }
                    formSubmitBtn.disabled = false;
                    formSubmitBtn.textContent = "Sign In";
                    return;
                } else {
                    alert("Oops! Could not sign in. Please try again");
                    formSubmitBtn.disabled = false;
                    formSubmitBtn.textContent = "Sign In";
                    return;
                }
            }

            formSubmitBtn.textContent = "Sign In";
            alert("Please check your email to sign in");
        } catch (error) {
            if (window.turnstile) {
                window.turnstile.reset();
            }
            formSubmitBtn.disabled = false;
            formSubmitBtn.textContent = "Sign In";
            console.log(error);
            alert("Something went wrong. Please try again");
        }
    });
</script>

This adds some vanilla JavaScript that calls the SignIn Upon form submission. This action provides user feedback through alerts and manages the button’s text and disabled state. This effectively adds client-side interactivity to the page.

Create the Protected Page

Create src/pages/protected.astro:

---
import Layout from "../layouts/Layout.astro";
import { createClient } from "../lib/supabase";
import "../styles/global.css";

const supabase = createClient({
    request: Astro.request,
    cookies: Astro.cookies,
});

const { data } = await supabase.auth.getUser();
---

<Layout>
    <section class="flex flex-col items-center justify-center m-30">
        <h1 class="text-4xl text-left font-bold mb-12">You are logged in!</h1>
        <p class="mb-6">Your user Id: {data.user?.id}</p>
        <button
            id="sign-out"
            class="bg-gray-600 hover:bg-gray-700 px-4 py-2 rounded-md text-white font-bold cursor-pointer disabled:bg-gray-500 disabled:hover:bg-gray-500 disabled:cursor-not-allowed"
            >Sign Out</button
        >
    </section>
</Layout>

<script>
    import { actions } from "astro:actions";
    const signOutBtn = document.getElementById("sign-out") as HTMLButtonElement;

    signOutBtn?.addEventListener("click", async (e) => {
        e.preventDefault();
        signOutBtn!.disabled = true;
        signOutBtn!.textContent = "Signing out...";

        try {
            const results = await actions.signOut();

            if (!results.data?.success) {
                signOutBtn!.disabled = false;
                signOutBtn!.textContent = "Sign Out";
                return alert("Oops! Could not sign Out. Please try again");
            }
            return window.location.reload();
        } catch (error) {
            signOutBtn.disabled = false;
            signOutBtn.textContent = "Sign Out";
            console.log(error);
            return alert("Something went wrong. Please try again");
        }
    });
</script>

This page retrieves the user data server-side in the front matter and displays it in the template, along with a sign-out button.

The JavaScript in the script tags handle calling the sign-out action, user feedback, and button state, as in the index.astro page.

Part 5: How to Set Up Astro Actions

Create the Authentication Actions

Finally, add an actions folder in the src folder and create an index.ts file to hold our logic. Paste the following into it:

import { defineAction, type ActionAPIContext } from "astro:actions";
import { z } from "astro:schema";
import { createClient } from "../lib/supabase";

const emailSignUp = async (
    {
        email,
        captchaToken,
    }: {
        email: string;
        captchaToken: string;
    },
    context: ActionAPIContext
) => {
    console.log("Sign up action");
    try {
        const supabase = createClient({
            request: context.request,
            cookies: context.cookies,
        });

        const { data, error } = await supabase.auth.signInWithOtp({
            email,
            options: {
                captchaToken,
                emailRedirectTo: "http://localhost:4321/api/exchange",
            },
        });

        if (error) {
            console.error("Sign up error", error);
            return {
                success: false,
                message: error.message,
            };
        } else {
            console.log("Sign up success", data);
            return {
                success: true,
                message: "Successfully logged in",
            };
        }
    } catch (err) {
        console.error("SignUp action other error", err);
        return {
            success: false,
            message: "Unexpected error",
        };
    }
};

export const server = {
    signIn: defineAction({
        accept: "form",
        input: z.object({
            email: z.string().email(),
            captchaToken: z.string(),
        }),
        handler: async (input, context) => {
            return emailSignUp(input, context);
        },
    }),
    signOut: defineAction({
        handler: async (_, context) => {
            const supabase = createClient({
                request: context.request,
                cookies: context.cookies,
            });
            const { error } = await supabase.auth.signOut();
            if (error) {
                console.error("Sign out error", error);
                return {
                    success: false,
                    message: error.message,
                };
            }
            return {
                success: true,
                message: "Successfully signed out",
            };
        },
    }),
};

This action handles both sign-in and sign-out methods. A Supabase server instance is created during the sign-in method, and the magic link method is used for sign-in. It passes a redirect URL, which we have yet to create, and handles any errors that may occur.

It also passes the token verification, allowing Supabase to perform verification on our behalf, eliminating the need to call Cloudflare’s verify APIs directly.

The sign-out method calls Supabase’s sign-out method and handles any potential errors.

The redirect URL refers to an API route that exchanges the code from the email Supabase sends for a session that Supabase handles.

Create the Code Exchange API Route

Create src/pages/api/exchange.ts:

import type { APIRoute } from "astro";
import { createClient } from "../../lib/supabase";

export const GET: APIRoute = async ({ request, cookies, redirect }) => {
    const url = new URL(request.url);
    const code = url.searchParams.get("code");

    if (!code) {
        return redirect("/");
    }

    const supabase = createClient({ request, cookies });
    const { error } = await supabase.auth.exchangeCodeForSession(code);

    if (error) {
        console.error("Error exchanging code for session:", error);
        return redirect("/404");
    }

    return redirect("/protected");
};

This grabs the code from the URL in the magic link sent, creates a server client, and calls the exchangeCodeForSession method with the code. It handles any error by redirecting to Astro’s built-in not-found page.

Otherwise, it will redirect to the protected page as Supabase handles the session implementation details.

Part 6: How to Test Your Application

Start your development server: npm run dev

Visit the provided localhost URL. You should see the sign-in page with the Turnstile widget:

If you try to access the /protected page, it will redirect you back to this view until you sign in. Now, sign in, and you should get an email with a link that will redirect you to the /protected page. This is what you should see:

And with that, you've successfully built a comprehensive auth system that leverages Astro actions, Supabase auth, and Cloudflare Turnstile's bot protection. This setup provides a secure, user-friendly authentication experience while protecting your application from malicious actors.

Notes and Additional Resources

Useful Documentation

• Supabase's advanced guide to SSR

• Supabase SSR package

• Astro Cookies documentation

• Supabase PKCE flow documentation

• Astro Actions documentation

• Get started with Turnstile

Complete Code Repository

The complete code for this project is available on GitHub:

• Base authentication setup

• With Cloudflare Turnstile

Astro is incredible for content-driven websites – so much so that since then, I've been cracking a joke: it should be a crime to build a blog and documentation site with any frontend framework other than Astro.

Another notable thing I was able to do on my blog was build a callout component. This is the little tangential boxes you see on documentation sites and some advanced developer blogs.

This is an example of one in the freeCodeCamp docs:

And here’s one in the Astro docs:

A bit unique, this is one on Josh Comeau's blog:

Keep reading, so I can show you how to build a callout component for your Astro blog.

You can also use the same technique to create one for a blog built with any other frontend framework.

Prerequisites

To get the most out of this article, you need the following:

• basic knowledge of Astro

• a knowledge of Astro slots and fragments

• familiarity with JSX and prop-drilling

• understanding of component-based architecture

Astro slots and fragments might sound a bit strange. If that's the case, don't worry, I’l do my best to make things as clear as possible for you.

How to Build a Callout Component for your Blog

The approach we are going to use is to have a parent component that will handle all the rendering for the callout box: the type, icon, text, and the styling.

What will follow are respective components that indicate a note, tip, caution, error callout boxes, and more.

Here's a diagram that simplifies the approach:

Each of the child components is what you'll bring in any time you want to display a callout related to them.

To get started, create a folder, name it what you want (I call it astro-callout on my end), and install Astro.

What follows is a series of prompts. Here are the choices I made during the prompts:

Here's what the project folder structure looks like after installing Astro and choosing the blog template:

How to Build the Parent Callout Component.

Head over to the src/component directory and create a folder named callout. Then inside the folder, create a Callout.astro file.

The callout component is an aside element that will take in the following props:

• type: the callout type (note, caution, error, tip, and others)

• icon: the icon that will signify the callout type. This could be an emoji or an icon from an icon library.

• backgroundColor: the different background color of each callout type

• borderLeftColor: the border-left color of each callout type

Destructure those props from Astro.props in the code fence of the Callout.astro component:

const { icon, type, backgroundColor, borderLeftColor } = Astro.props

Don't forget the aside element has to have some text content, too. Astro has a way to handle this using the <slot /> element.

<slot /> lets you insert child content written between opening and closing tags into any component.

Here's how I filled everything into the aside element:

<aside
 class="callout-box"
 style={{backgroundColor, borderLeftColor}}
 >
 <div class="callout-icon-and-type">
   {icon}
   {type}
 </div>
 <div class="callout-content">
  <slot />
 </div>
</aside>

The icon prop fills in for any icon you would like to use, be it an emoji or an icon library like Ionicons or Font Awesome.

The problem is that not all emojis will be rendered in a presentable way, as different operating systems render emojis their own ways. So, you must find a way to accept both emojis and an icon library.

The icon library I chose for this project is ionicons. Go into the layout file (in this case layouts/BlogPost.astro) and insert the following scripts just before the closing body tag:

<script type="module" src="https://unpkg.com/ionicons@7.1.0/dist/ionicons/ionicons.esm.js"></script>
<script nomodule src="https://unpkg.com/ionicons@7.1.0/dist/ionicons/ionicons.js"></script>

Here's the function that will let you render an icon, whether it’s an emoji or an ionicons icon:

function renderIcon(icon:any) {
 if (typeof icon === 'string') {
   return icon;
 } else if (typeof icon === 'object' && icon.name) {
   return `<ion-icon name="${icon.name}"></ion-icon>`;
 }
 return '';
}

This function checks if the icon you pass in is an emoji or an icon from the Ionicons library.

An emoji corresponds to a string. So if you pass in an emoji, the icon is returned. If you pass in an icon from the Ionicons library, the function will look out for the icon name and display that icon.

You need to modify the content of the aside element a bit so the icon will be rendered the correct way:

<aside
 class="callout-box"
 style={{backgroundColor, borderLeftColor}}
 >
 <div class="callout-icon-and-type">
   <!-- New icon renderer -->
   <Fragment set:html={renderIcon(icon)} />
   {type}
 </div>
 <div class="callout-content">
  <slot />
 </div>
</aside>

If you're wondering what set:html is, it's an Astro template directory similar to the JavaScript element.innerHTML.

The Fragment component itself is a component you can use with the set:* directives to render HTML content.

Here's the CSS for the Callout component:

<style>
 .callout-box {
   color: #fff;
   flex-direction: column;
   padding: 1rem;
   border-left-width: 4px;
   border-left-style: solid;
   margin: 1.5rem 0;
   border-top-right-radius: 4px;
   border-bottom-right-radius: 4px;
 }

 .callout-icon-and-type {
   font-size: 1.5rem;
   display: flex;
   gap: 0.4rem;
 }

 .icon {
   margin-right: 4rem;
 }

 .callout-content {
   font-size: 1.2rem;
 }
</style>

This will make more sense when we start using the parent Callout component in the child callout components.

How to Build the Child Callout Components

Let's demonstrate how to do this with a sample note callout box.

Create a NoteCallout.astro file inside the components/callout directory.

Import the parent Callout component inside the code fence of the NoteCallout.astro file:

import CallOutBox from "./Callout.astro";

To make things less confusing, you can rename CalloutBox to NoteCalloutBox:

import NoteCallOutBox from "./Callout.astro";

After that, use the NoteCalloutBox as a tag and pass ion all the props the parent Callout component accepts:

<NoteCallOutBox
 icon='<ion-icon style="color: #3347ff;" size="large" name="information-circle"></ion-icon>'
 type="Note"
 backgroundColor="#171d4f"
 borderLeftColor="#3347ff"
>

</NoteCallOutBox>

To account for the content of the NoteCalloutBox to be passed in when it's finally used, pass in <slot /> as the content of the NoteCallOutBox:

<NoteCallOutBox
 icon='<ion-icon style="color: #3347ff;" size="large" name="information-circle"></ion-icon>'
 type="Note"
 backgroundColor="#171d4f"
 borderLeftColor="#3347ff"
>
 <slot />
</NoteCallOutBox>

You can follow this process to create an error, caution, warning, and tip callout child components. All you need to do is to fill in the appropriate prop values.

How to Use the Callout Child Components

To use the child callout components in an MDX file for example, import the NoteCallout:

import NoteCallout from '../../components/callout/NoteCallout.astro';

Then use it as a tag and pass in the note you want to communicate to the user:

<NoteCallout>
 You can only use this component in an MDX file, not a regular Markddown file
 with a .md extension.
</NoteCallout>

Here's the result in the browser:

Here are other child components I created using the same approach:

Conclusion

I hope this article showed you everything you need to build a callout component for your blog.

Don’t forget that you can use the same technique to build a callout for a blog built with any other frontend framework.

If you find the article helpful, you can read more articles like it on my blog. I also have articles on PHP, JavaScript, React, Python, and more.

Keep coding…

Google Analytics is an effective tool for tracking and analyzing traffic and events on your websites and mobile apps. In this article, you'll learn how to add Google Analytics to your Astro website.

To follow along, you'll need the following:

• A Google account.
• A deployed Astro project.

Let's get started!

How to Add Google Analytics to an Astro Website

Before adding Google analytics, make sure you've already deployed your project. Here's one that I've deployed using Netlify: https://astro-article.netlify.app/. This is an Astro blog template created with the npm create astro@latest -- --template blog command.

This section will be divided into two sub-sections. In the first sub-section, you'll learn how to create an Analytics account and how to set up your account for tracking and monitoring your website.

In the second sub-section, you'll learn how to configure your code to sync with Google Analytics.

How to Set Up Google Analytics

You can follow these steps to set up Google Analytics:

Step #1 – Account Creation Page

The first step is to create a Google Analytics account. You can do that by visiting the Google Analytics website.

When the page loads, you should see something similar to this:

Google Analytics home page

Click on the "Start measuring" button. This will take you to the account creation page where you'll fill in some info about your website/app. That is:

"Create an Account" page on Google Analytics

After inputting an account name, scroll down the page and click on the "Next" button.

Step #2 – Property Creation Page

On the property creation page, you can create a property name, time zone, and currency.

A property acts as a unique identifier for your websites and apps. So it is like a container for all the data related to a specified website or app.

"Create a Property" page on Google Analytics

Step #3 – Business Details Page

On the business details page, you can specify your industry category and the business size.

"Describe your business" page on Google Analytics

Step #4 – Business Objectives Page

The business objectives helps Analytics generate personalized reports for your business. You can select the options that are important to your website, app, or product category.

"Business objectives" page on Google Analytics

After selecting the options, click on the "Create" button.

Step #5 – Data Collection Page

On the data collection page, you can choose between different platforms to collect data from. Since we're working with a website, we'll go with the Web option.

"Start collecting data" page on Google Analytics

Next, you'll have to create a data stream by inputting your website URL and your stream name (this can be whatever you want, but I'll recommend using a name related to your website).

Page to setup a data stream on Google Analytics

In my data stream information, I used https://astro-article.netlify.app/ as the URL and "Astro Blog Template" as the stream name.

Make sure you remove the "https://" part of the link in the input box so you don't get the "Valid website URL is required" error.

So instead of https://astro-article.netlify.app/, it should be astro-article.netlify.app/.

This is what mine looks like:

Example of information entered properly in data stream setup page

Go ahead and click on the "Create stream" button.

On the next page/prompt, you'll see your stream name, URL, ID, and measurement ID values.

The measurement ID will be important in our code integration so you can copy and paste it somewhere.

Here's what the page looks like:

"Web stream details" page on Google Analytics

If you click on "View tag instructions", you'll see a code snippet for manual integration with code. Copy the code and paste somewhere because we'll make use of it soon.

Installation instructions

Here's the code snippet if you missed it:

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'MEASUREMENT_ID');
</script>

If you're copying the code above, make sure you replace the two MEASUREMENT_ID values with the actual value of your measurement ID.

How to Integrate Google Analytics and Astro

At this point, we've created a Google Analytics account and generated our project's measurement ID. The next thing to do is to sync our code to Google Analytics.

But first, we have to install a library called Partytown. When using third party integrations, you may run into performance issues because you're making use of third-party code.

Partytown allows these integrations to run as expected without reducing your site's performance. You can read more about that here.

Step #1 – Install Partytown

Head to your Astro project terminal and run this command to install Partytown:

npm install @astrojs/partytown

Step #2 – Configure Partytown

After the installation is complete, you'll need to add the integration to your astro.config.mjs file:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import partytown from '@astrojs/partytown'

import sitemap from '@astrojs/sitemap';

// https://astro.build/config
export default defineConfig({
    site: 'https://astro-article.netlify.app/',
    integrations: [
        mdx(), 
        sitemap(),
        partytown({
            config: {
              forward: ["dataLayer.push"],
            },
        }),
    ],
});

In the code above, we imported the Partytown library: import partytown from '@astrojs/partytown'.

We then added this piece of code to the integrations object:

partytown({
      config: {
        forward: ["dataLayer.push"],
      },
})

Everything else in the code came with the Astro project.

Step #3 – Add Google Tag to your Pages

Remember the code snippet from Google Analytics? This is where we'll use it.

<!-- Google tag (gtag.js) -->
<script type="text/partytown" async src="https://www.googletagmanager.com/gtag/js?id=MEASUREMENT_ID"></script>
<script type="text/partytown">
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'MEASUREMENT_ID');
</script>

Note that we added the type="text/partytown" attribute to both <script> tags.

Remember to change the MEASUREMENT_ID values to the value of your measurement ID. Mine looks like this:

<!-- Google tag (gtag.js) -->
<script type="text/partytown" async src="https://www.googletagmanager.com/gtag/js?id=G-KM36S70L8Y"></script>
<script type="text/partytown">
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());

    gtag('config', 'G-KM36S70L8Y');
</script>

Do not use the snippet above as it has my measurement ID so it's already associated with my website (not my actual website :)). Copy the first code snippet and change the MEASUREMENT_ID values to the value of your measurement ID.

To track and monitor a page, you need to paste the code snippet in that page. Copy the code and paste it in the <head> section of every page file (index.astro, BlogPost.astro, and so on) you want to track and analyze using Google Analytics.

Here's an example using the index.astro file in the pages directory:

---
import BaseHead from '../components/BaseHead.astro';
import Header from '../components/Header.astro';
import Footer from '../components/Footer.astro';
import { SITE_TITLE, SITE_DESCRIPTION } from '../consts';
---

<!doctype html>
<html lang="en">
    <head>
        <!-- Google tag (gtag.js) -->
        <script type="text/partytown" async src="https://www.googletagmanager.com/gtag/js?id=MEASUREMENT_ID"></script>
        <script type="text/partytown">
            window.dataLayer = window.dataLayer || [];
            function gtag(){dataLayer.push(arguments);}
            gtag('js', new Date());

            gtag('config', 'MEASUREMENT_ID');
        </script>
        <BaseHead title={SITE_TITLE} description={SITE_DESCRIPTION} />
    </head>
... <!-- The rest of the HTML code -->

In the code above, we put the code from Google Analytics in the <head> tag. You can do this for all the pages you want to track and monitor.

Remember to add the type="text/partytown" attribute to the <script> tags, and to change MEASUREMENT_ID (used in two places in the snippet) to the value of your measurement ID.

Step #4 – Build and Deploy your Project

Deploy your project using your preferred process.

In my case, I use npm run build to build into the dist folder, and then push the code to GitHub. This automatically triggers a Netlify deployment.

You don't have to use my method, but make sure your project builds before deployment.

Once your website has been deployed, you may have to wait up to 48 hours to start seeing your analytics in the Google Analytics dashboard.

Pending page

You'll see this page when you click on the "Continue to Home" button:

Analytics dashboard

This is your Analytics dashboard. You can view and analyze your data here when there's data available.

And there you have it! You've successfully integrated your project with Google Analytics.

Summary

In this article, we saw how to add Google Analytics to an Astro project. This can be used to track and analyze traffic and events on websites and apps.

We saw how to create and set up an Analytics account.

We then saw how to integrate Google Analytics to an Astro project using code.

Happy coding! You can read more Astro tutorials on my blog.

We just posted an Astro crash course on the freeCodeCamp.org YouTube channel, presented by none other than James Q Quick.

James Q Quick is a popular instructor and keynote conference speaker. In this course, he combines his vast experience with his unique teaching style, making him the ideal guide to introduce you to the wonders of Astro.

In this crash course, James teaches the core concepts of Astro. Here are some of the topics that you will learn about:

• File-Based Routing: Navigate the straightforward routing system that Astro uses.
• Markdown and MDX Content: Create and manage your content with ease.
• Dynamic Routes: Understand how to set up routes that adapt based on your content.
• Deployment: Get your Astro site up and running on platforms like Netlify and Vercel.
• Server-Side Capabilities: Transition from a statically generated site to a server-side rendered one, and discover how to integrate server endpoints.

In the modern web landscape, website performance can make or break user engagement. With Astro's focus on optimized performance, mastering this framework equips developers with the skills to create websites that not only look good but also function seamlessly. This course isn't just about learning a new tool; it's about staying ahead in the competitive world of web development.

Here are the sections in this course:

• What We'll Cover
• Creating an Astro Project
• Astro Overview (components, file based routing, css, and more)
• Astro Setup in VS Code
• Setting Up Tailwind
• Updating the Site Layout
• Working with Markdown and Content Collections
• Querying and Displaying Blog Posts Using Content Collections
• Creating Dynamic Routes For Individual Blog Posts
• Tailwind Typography Plugin
• Optimizing Images
• Using the ViewTransitions API
• Adding Support for MDX
• Deploy to Netlify and Vercel
• Enabling SSR in Astro
• Astro Server Endpoints
• Deploying SSR to Netlify and Vercel

You can watch the full course on the freeCodeCamp.org YouTube channel (1-hour watch).