Mastro

How to easily add Standard.site support to your website

2026-06-05T12:00:00.000Z

(Updated on June 15, 2026)

Since Bluesky added support for Standard.site, everyone with a blog seems to be racing to roll out an implementation. That’s awesome, and yet another example of how ATproto feels like one of the more exciting things happening in tech right now.

What ATmosphere?

For a bit of background, see e.g. Steve Klabnik’s How Does BlueSky Work? The TL;DR is that you can think of the ATmosphere as a big distributed database, which is partially mirrored a few times via relays. Anybody with an account on a PDS (Personal Data Server – Bluesky being the biggest example) can make HTTP requests to it and read and write records in the database. A set of evolving, shared lexicons make sure your data remains portable and you’re not being locked in. The latest such lexicon to reach critical mass is Standard.site – it’s a standardized way to express metadata about publications and documents (e.g. blogs and their posts).

One interesting way that some people use this is to use the ATmosphere as the backend database for their website.

Uploading blog posts

But most people already have their posts in a traditional database (e.g. via a CMS), or have a static site with Markdown files. How can you ensure that whenever you create a new blog post (or change an existing one), the corresponding records in the Atmosphere are created (or updated)?

An ATproto record in the site.standard.document collection has a URI like this:

"at://" DID "/site.standard.document/" rkey

The DID (Decentralized Identifier) uniquely identifies your user, and the rkey (record key) uniquely identifies the specific document in the collection.

When creating a new document, the obvious approach (that most people currently seem to be following) is to push the data and let the PDS server auto-generate an rkey.

But in order for things to be verified, you need to add your record’s AT-URI to the HTML of your blog post’s web page with:

<link rel="site.standard.document"
  href={`at://${did}/site.standard.document/${rkey}`}>

Which means that if your rkey was generated by the PDS, you need to store it somewhere after it’s generated – e.g. in your CMS’s database, or in the YAML frontmatter of your markdown files.

While this is fine, it can be a bit annoying. Especially for a website without a database, it makes things a bit hard to automate. If you set up your CI/CD pipeline to push to the ATmosphere, do you then have it create a new commit with the modified markdown frontmatter?

Deriving the rkey from the URL path

An alternative approach, which I first saw proposed by Kuba Suder, is to derive the rkey from the URL path of the web page. This is what I just implemented in the new @mastrojs/atproto package.

It exports a rkeyFromUrl function that deterministically derives an rkey from the path of a URL. Then, in the code generating the HTML, we simply use it like:

<link rel="site.standard.document"
  href={`at://${agent.did}/site.standard.document/${rkeyFromUrl(doc.url)}`}>

This does mean however, that you cannot change the URL of your post after you’ve published it. But I suppose you shouldn’t be doing that anyway.

Running the script

Finally, we package everything up in a nice declarative way. You simply add a script to your codebase with something like the following:

import { createOrUpdateStandardSite, type Publication } from "@mastrojs/atproto";
import { readMarkdownFiles } from "@mastrojs/markdown";

const identifier = "your.bsky.social";
const password = process.env.ATPROTO_PASSWORD;
const pubUrl = new URL("https://example.com/news/");

const publication: Publication = {
  url: pubUrl,
  name: "Peter's News",
};

const posts = await readMarkdownFiles("data/posts/*.md");
const docs = posts.map((p) => ({
  title: p.meta.title,
  publishedAt: new Date(p.meta.date),
  url: new URL(p.slug, pubUrl),
}));

await createOrUpdateStandardSite({ identifier, password }, publication, docs);

Whenever you run your script, it will fetch the existing records from your PDS, diff them against your current input, update the existing ones, and upload any new records. Regardless of whether your run it manually, or in your CI/CD pipeline.

Does it work?

Try posting a link to this blog post on Bluesky, and you should see the shiny “View publication” button appear!

If you want the same for your blog, go ahead and use the @mastrojs/atproto package. Bug reports and contributions welcome. Happy publishing to the ATmosphere!

Version 0.2

The first version of this blog post (and first version of the @mastrojs/atproto library) used the simplest approach possible to derive an rkey from a URL path: strip all characters that may not appear in any rkey (e.g. slashes and other special characters).

While this approach works on Bluesky (and the validator didn't complain about it at the time), I was made aware that the Standard.site schema doesn't specify an rkey of type any, but requires one of type TID (Timestamp Identifier). There is an ongoing discussion whether this requirement can be relaxed, as it would simplify things a bit. But there is no discernible sign that the schema might be changed anytime soon.

That's why in version 0.2 of @mastrojs/atproto, you can specify whether you want the rkey of type TID (which is now the default), any, or supply your own rkey. If a date in format YYYY-MM-DD or YYYY/MM/DD is detected anywhere in the URL path, that will be used as the timestamp of the TID. The rest of the path is used for the remaining bits of the TID. Either way, the rkey is derived deterministically from the document's URL path – which is what this library set out to solve.

I already put a lot of thought and care into version 0.1. The idea that you declaratively provide all information as part of a function call instead of a pure CLI like Sequoia was novel AFAIK. (In v0.2, this API is even safer since it's using URLs instead of string paths.) Then there is the flow that when you run the script for the first time, it will show you the URLs and rkeys, and once confirmed, create a .well-known/site.standard.publication file. And only on subsequent runs, it will publish and/or update documents in the Atmosphere. You can even do that in your CI/CD pipeline, which I find pretty neat.

That's why I had mixed feelings when I discovered somebody had copied the source code of @mastrojs/atproto, removed the types and tests, and made a few relatively minor changes (source -> copy). Yet it proved I was onto something. I approached them and asked whether they were interested in a collaboration, even offering to switch to their project name and repo, but the replies were evasive. Yet the next day, they published an announcement blog post that doesn't even mention the original project (the README now says "Credit to @mastrojs/atproto for the inspiration"). Oh well, community building is hard.

Sadly, this also means they and their users are losing out on all the improvements of v0.2 outlined above. (Their version derives the rkey from the document's publishedAt instead of the URL path, which has the potential for clashes if your granularity is dates, and the timestamp calculation is off by a factor of 1000.)

It seems that integrating existing websites with the Atmosphere is a problem worth solving once, and worth solving well. If you're working on this as well, I would be more than happy to collaborate! Do you have better ideas? Is there anything that doesn't work for you yet? Should we export more functions for you to integrate it in your existing stack? Just open a GitHub issue or talk to us on Stoat or Bluesky.

Four ways to do component-scoped CSS without a complex build step

2026-05-26T12:00:00.000Z

People have been exploring different ways to organize their CSS for almost as long as CSS has been around. In the beginning with methodologies like BEM, later with tooling like CSS modules, CSS-in-JS, and now with Tailwind.

But with browsers now natively supporting CSS nesting, variables and @scope rules, let's look at four approaches to do things without resorting to complex tooling.

1. One big CSS file

Still a great way to get started. Don't overcomplicate things for a small website! And you always need a file with some globals to set up CSS variables, fonts, etc. anyway. If you're following Heydon Pickering's way of applying a thorough base style to all your HTML elements (which I highly recommend), a single file can carry you a long way.

2. A plain CSS file for each component

But maybe you've started organizing your template files into components. In that case, you may want to colocate your CSS for each component in the same folder (e.g. components/Header.css). But if you have more than a dozen components, serving each CSS file separately starts negatively affecting performance.

We'll be using Mastro server components in the following examples, but you probably can adapt the approach to whatever setup you're using. A Mastro component for your website's header might look as follows. (Note that the Header component in turn uses the Navigation component.)

import { html } from "@mastrojs/mastro";
import { Navigation } from "./Navigation.js";

export const Header = () =>
  html`
    <header>
      <p>My awesome website</p>
      ${Navigation()}
    </header>
  `;

The simplest way to bundle all your CSS is to just read out all your CSS files, and concatenate them. In Mastro, everything is a route. And a route to do that would look like:

import { findFiles, readTextFile } from "@mastrojs/mastro";

export const GET = async () => {
  const files = await findFiles("components/**/*.css");
  const contents = await Promise.all(files.map(readTextFile));
  return new Response(
    contents.join("\n\n"),
    { headers: { "Content-Type": "text/css" } },
  );
}

The route can be consumed by putting the following in your HTML:

<link rel="stylesheet" href="/styles.css">

If you're using Mastro for static site generation, the resulting styles.css file will be generated along with all the other static pages. If you're using Mastro as a server, you should mark the route for pregeneration. (Note that this approach is not yet supported when running Mastro in-browser with the VSCode extension.)

It's true that this doesn't minimize or otherwise transform your CSS. But your CDN or server most likely supports gzip compression out of the box, so there is no big performance hit. And you control exactly what gets shipped to the browser – no magic transforms or outdated prefixes are ever applied.

3. Inlining the styles into the component

CSS @scope rules are now supported in every browser (including Safari >= 17.4). They are a browser-native solution to what BEM, CSS modules, etc. have been trying to do: scoping the styles to only apply to specific DOM subtrees.

One way to use them is by putting them directly in the HTML where they're used:

import { html } from "@mastrojs/mastro";
import { Navigation } from "./Navigation.js";

export const Header = () =>
  html`
    <header>
      <p>My awesome website</p>
      ${Navigation()}

      <style>
        @scope {
          :scope {
            background-color: cyan;
          }
          p {
            font-size: 3rem;
          }
        }
      </style>
    </header>
  `;

The :scope selector will apply to the parent element of the <style> tag in the DOM, which is known as the scope root. In this example, it's the <header> element. Usually, that would be the root element of your component.

But the real win is that the selectors inside the @scope only apply to elements inside the scope root. In this example, only paragraphs inside this <header> element will get a font-size of 3rem. All the other paragraphs on your website will remain untouched!

But at this point, the styles would also apply to whatever is rendered by the Navigation component, because it's inside the <header>. For the styles to only apply from the <header> but stop at the <nav> element (excluding it), you could use "donut scoping":

<style>
  @scope to (nav) {
    :scope {
      background-color: cyan;
    }
    p {
      font-size: 3rem;
    }
  }
</style>

Inlining the styles directly into the HTML like that, without making an additional HTTP request to a CSS route, is actually great for first page load performance – as long as you have the component only once or twice on the page. But for subsequent page loads, it would be better if we go back to putting the CSS in an external route that can be cached by the browser. What is faster depends a lot on how many times you use your components on any given page, how much CSS you have, and on how many pages your users typically visit.

4. Server-side CSS-in-JS

The other way to use @scope rules is to put them in an external stylesheet, and identify the scope root with a selector. With a bit of server-side JavaScript, we can still colocate the styles with the component's HTML.

Still using the donut scoping technique, but introducing the convention that every component root has a data-scope attribute (hat tip to Julia Evans who dug out that example from the CSS spec), this could look as follows:

import { css, html } from "@mastrojs/mastro";
import { Navigation } from "./Navigation.js";

const root = "header";

export const Header = () =>
  html`
    <header data-scope=${root}>
      <p>My awesome website</p>
      ${Navigation()}
    </header>
  `;

export const styles = css`
  @scope ([data-scope=${root}]) to ([data-scope]) {
    :scope {
      background-color: cyan;
    }
    p {
      font-size: ${2 * 3}rem;
    }
  }
`;

Instead of data-scope, you could also use a different convention to uniquely identify component roots. For example using classes, with the convention that they need to contain a dash, like @scope (.my-header) to ([class*="-"]). Or using unregistered custom elements with e.g. @scope (my-header) to (:not(:defined)).

The above uses Mastro's css tag literal (new in Mastro v0.8.5, feel free to copy its one-line-implementation). Just like the html tag literal, it enables syntax highlighting and embedding server-side JavaScript expressions (not client-side, like many other CSS-in-JS solutions). This allows you to calculate things in server-side JavaScript that you might previously have used SCSS for. Heck, you could insert randomly generated class names and roll your own CSS Modules implemention with a few lines of code:

import { css, html } from "@mastrojs/mastro";
const name = (prefix) => `${prefix}-${Math.random().toString(36).substring(2, 7)}`;

const root = name("header");

export const Header = () =>
  html`
    <header class=${root}>
      <p>My awesome website</p>
    </header>
  `;

export const styles = css`
  .${root} {
    background-color: cyan;
    > p {
      font-size: ${2 * 3}rem;
    }
  }
`;

Either way, to collect all the exported styles under a /styles.css route, use for example:

import { findFiles, readTextFile } from "@mastrojs/mastro";

export const GET = async () => {
  const base = await readTextFile("base.css").catch(() => "");
  const files = await findFiles("components/**/*.{js,ts}");
  const styles = await Promise.all(
    files.map(f => import("../" + f).then(m => m.styles))
  );
  return new Response(
    base + styles.join(""),
    { headers: { "Content-Type": "text/css" } },
  );
}

Conclusion

By leaning into CSS features built into every modern browser, and leveraging Mastro's flexible routes system, we're getting most of the functionality of common build tools – but none of the complexity. We don't require any additional dependencies, and we're in full control of what gets sent to the browser.

Is AI causing a repeat of Frontend’s Lost Decade?

2026-05-23T12:00:00.000Z

What AI is doing to the jobs of programmers feels very familiar to a lot of us frontend developers – because it has happened to us before.

Let’s first look at the transformation of the frontend and agentic coding through the lens of deskilling, and then look at both changes through the lens of a higher level of abstraction. Finally, we’ll look at previous changes, like the advent of copy-pasta from Stack Overflow, and how the Bauhaus movement reacted to rising industrialization.

Deskilling

Just like AI is deskilling programming now, JavaScript frameworks have deskilled frontend development in the last decade. As someone who started with HTML/CSS and a bit of PHP, later did Ruby on Rails, and then was frontend team lead of a major Swiss newspaper (Next.js at the time), I've seen the transformation first-hand. And no need to take my word for it! I’m not the first to say so. Alex Russell called it Frontend's Lost Decade.

What is deskilling? From Wikipedia:

Deskilling is the process by which skilled labor within an industry or economy is eliminated by the introduction of technologies operated by semi- or unskilled workers. This results in cost savings [...] and reduces barriers to entry, weakening the bargaining power of [workers].

Let’s see how this applies to the frontend, and then to agentic coding.

The deskilling of the frontend

A lot of programmers may not know this, but frontend used to be a highly specialized skill, requiring knowledge of semantic HTML, CSS, the differences of various browsers, accessibility, progressive enhancement, network performance, interface design and user testing – to just name a few. To distinguish what they’re doing from what “frontend” has become, practitioners of this arcane art nowadays often refer to it as the “front of the frontend”.

The deskilling of the frontend was the introduction of frameworks and other tooling that treats the browser as a mere compilation target – just like any other app runtime (e.g. JVM or iOS). Then you can just load in the monstrosity that is a Shadcn radio button, and don’t need to understand the underlying HTML, any subtleties involving different browsers, page load performance, and accessibility.

As the Wikipedia quote above points out, this “results in cost savings” for businesses, since they then can easily put any general programmer to work on the frontend. Often, a “full-stack developer” is unfortunately not somebody who deeply understands the frontend and the backend, but a generalist who just knows enough to wrangle a JavaScript framework to do both. This allows businesses to easily switch programmers around between different projects. The same generalist can even also do native apps with React Native and Electron! To finish the Wikipedia quote: this “reduces barriers to entry” (which is something I’ve always cherished), but it also “weakens the bargaining power of workers”.

AI is deskilling programming

What’s currently happening to programmers more generally seems very similar to what web developers in particular have been going through already. The skilled job of writing code manually is being “eliminated by the introduction of technologies, operated by semi- or unskilled workers.”

We still don’t know exactly what skillset the workers wrangling agentic AI will need to have at the end of this transformation, and at what price point we’ll arrive at – for both labour, and for local and remote LLMs. But it is already clear now, that businesses absolutely will use this technology for cost savings and weakening of the bargaining power of workers.

A profound sense of loss

Just like artisans and craftsmen that were replaced by assembly line workers more than a century ago, we feel a profound sense of loss. We grieve that a skill, that we spent half a lifetime honing, is not being valued by the market anymore. And we’re saddened that the new process results in lower quality work, and that a lot of people just don’t seem to care.

Operating at a higher level of abstraction

An alternative way to look at “deskilling” is of course to argue that this is just increasing efficiency using automation. And what engineer doesn’t like automating things? It’s a big part of our job after all!

In this framing, the new technology introduced simply works on a higher level of abstraction, allowing the person operating it to focus on the bigger picture, without having to bother about unimportant details. But exactly which details are deemed “unimportant” is a very consequential and sometimes subjective decision. And eventually, the details always leak through.

“Modern” frontend: a tower of leaky abstractions

It’s common for an abstraction to come at a cost of performance. But since computers are very fast nowadays, we were often willing to trade some runtime performance for increased developer productivity (garbage collection is one example). And for high-powered servers under moderate load, this is a very sensible tradeoff. But mobile phones on slow networks are a different beast.

By using a heavy client-side JavaScript framework like React, and a lot of packages from that ecosystem, you’re abstracting over things like accessibility, and performance on lower-end phones, or on slow networks. In effect, you’re choosing not to think about those things, and you’re choosing not to care about them.

Agentic coding: an undeterministic abstraction

By using agentic AI to code a feature or fix a bug, you’re describing the change at a higher level of abstraction, writing fewer words than writing all code by hand. The AI will fill in the details you omitted by looking at its training data and surrounding context – sometimes guessing well, other times not. Whether you find this useful or not depends to a large degree on your opinions on what’s important when coding.

But compared to previous abstractions in programming, agentic coding is a very leaky abstraction. It’s not deterministic like a compiler, and slight variations in input or model can give very different results. That has led people to compare AI to “junior engineers”, since those are also not deterministic. But one difference is of course that people are capable of learning, without you having to endlessly tweak their AGENTS.md or SKILL.md files.

LLMs as an extension of copy-pasta from Stack Overflow

As such, the best analogy for using LLMs I’ve found so far is how a Google search used to behave. It was a skill all of us had to learn at some point: choosing just the right keywords, so that the right forum post (and later Stack Overflow post) would surface on the first Google results page. Just like prompting an LLM, in order to return the right assemblage of its training data, a fuzzy web search is a lookup in a very high-dimensional space. And just like with LLMs, the lookup used to be very sensitive to slight variations of wording, and changes to Google’s search index.

In recent years, among other things, Google has changed the search to normalize entered terms much more aggressively. For people who were not versed in the dark art of Google-fu, this made the search much easier to use. But for those of us that had acquired that skill, it made Google search much less powerful. Specialized keywords used to bring us directly to an answer. Now they get normalized to a synonym, or to a closely associated word, and we land on a more generic page.

But the advent of Google, and later Stack Overflow, irreversibly changed programming. Instead of reading the f***ing manual, programmers could now just blindly copy & paste answers from Stack Overflow, and surprisingly often got something that kind of worked. Seen through this lens, LLMs are just a continuation of the same trend: tools and abstractions that make people that know what they’re doing slightly faster, and enable people who don’t really know what they’re doing to arrive at something that often kind of works. And you know what? That’s great!

But we shouldn’t fool ourselves: at some point the abstraction will leak. And then somebody has to invest the time to actually deeply understand what’s going on – and fix it. Just like we taught junior programmers to read and understand the Stack Overflow answer before using it, now we need to teach people to read and understand the stuff the LLM spits out, and to understand how it fits into the existing codebase.

Does quality matter?

Unfortunately, some programmers never progressed to the stage of trying to really understand the Stack Overflow answer. Why bother if it works? And while not publicly acknowledged, a lot of companies were actually happy with this approach. What’s different now is that companies go out of their way to publicly proclaim how much AI they’re using, without even pretending to look at the output.

While there are definitely valid use-cases for LLMs, there are also lots of new ways to mess up your code, and to mess up your organization’s communication and processes. This seems especially challenging to figure out as a team. Just like with code review, there are widely differing views on how to use and integrate LLMs into our workflows (if at all). And if the team is not aligned on what things they value, this can really throw a wrench in the works.

It’s also a sad fact of life that a lot of companies are doing very well, even though they’re churning out abysmal software. Despite what we programmers would like to believe, business success and software quality are very rarely correlated. Usually, other factors simply dominate. Often, software projects are treated as black boxes, known to fail about as often as they succeed, and are derisked in various ways (in the worst case, a different team will have another go at it).

And it’s been the same for frontend development. Unfortunately, a terrible website has a relatively small impact on the bottom line. Does a slow website and lots of cookie banners hurt conversion? Sure, but that effect is relatively small compared to other factors like brand loyalty and pricing. And all the competitors have slow websites as well! Besides, nobody was ever fired for choosing React.

Does that mean we should stop caring about our users and about our craft? No. But it does mean that it’s become even harder to find a job where you’re allowed to do so. Hopefully, the pendulum will swing back a bit, once the hype has blown over, and we’ve a better understanding what tasks LLMs are actually a good fit for and what not. But it’s safe to say that our profession will not be the same as before.

The Bauhaus movement

What did previous generations of craftspeople do when everyday goods and buildings suddenly could be mass-produced by industrial processes? One reaction was to copy the style of old, and make the industry crank out widgets and buildings that at least looked like they were handcrafted.

Countering this trend of historicism, an alternative approach was developed by the Bauhaus movement of the early 20th century. Instead of pitting factory workers against craftspeople, their stated goal was to have them work together, and redevelop the arts and crafts with industrial manufacturing processes in mind. The Bauhaus urged designers to go back into the workshops, and work with the materials themselves. Still with the goal of arriving at designs that would then be mass produced. But always keeping the end user and mind, and deeply caring about them. Modern industrial design, as exemplified by Dieter Rams and Johnathan Ive, can trace its roots straight back to the Bauhaus.

Caring about quality and the user

How can we translate this line of thinking to software?

Software sits somewhere in-between craft on one hand (the program we write gets shipped “as is” to our users, without first going through a manufacturing step), and industrial design on the other hand (we ship the same thing to potentially thousands of users, who we never get to see interacting with our product).

The need for being able to write code by hand is clear. Just like industrial designers need to know the materials their products will be made of, a web designer needs to be intimately familiar with HTML and CSS.

While it’s great that tools like Google, Stack Overflow, ready-to-use libraries, and now LLMs are making things easier for beginners, this also means that the natural barrier to get anything working at all is continuously being lowered.

While there is a high barrier to entry to a field, it’s difficult to find absolutely terrible pieces of work. Once a craftsman was taught how to build a wooden chair, they invariably were also taught how to not do a terrible job at it.

The industrialization enabled lots of cheap plastic products, designed by people who didn’t take the time to think how they would be used and by whom – yet good industrial design is still a thing. The invention of the word processor enabled lots of terribly formatted documents – yet typography and graphic design still exist. And software like Wix and Next.js enabled the creation of lots of websites that load terribly slow and are not accessible – yet there are still practitioners of the front of the frontend out there. Likewise, AI is enabling lots of AI slop – but this doesn’t mean we don’t still need people who know what they’re doing, and who care about what they’re doing.

How will it shake out?

But like in other industries, doing things properly will become an ever smaller slice of the pie. But because it’s now easier and cheaper to do so, the size of the pie will continue to grow. It’s very hard to say at this point in time whether the absolute number of people, being payed to do things well, will increase or decrease. If you ask me, there are way too many poorly designed plastic products out there. And it’s a sad fact that designing new type faces is not a sustainable full-time job anymore. But at the same time, there is still so much great work being done in all those domains.

And you know what? Sometimes churning out a quick prototype or MVP is the right thing to do. If you don’t have product-market-fit yet, quick iteration and learning is more important than future-proofing everything. But you need to know what you’re trying to learn, and how you validate those learnings. And when the time has come, it’s usually better to take a step back and do things right from the start. For example, good performance is very hard to achieve in a badly architected frontend later. And it's easier to start with a simple stack and add functionality later on than the reverse. Both of these, Mastro explicitly encourages.

For any part of the system, you need to know what tradeoffs you’re making, and then decide whether you should buy a service, use an open source library, have an LLM churn it out, or write it yourself. When the hype has died down, the industry will realize it’s just one more tool in the toolbox. But until then, we’re going to see a lot of ugly things: ugly code, broken communications, and awful layoffs under the guise of AI.

TypeScript full-stack web framework for agents and humans

2026-04-16T12:00:00.000Z

I would be lying if I said the Mastro web framework was designed from the ground up for AI agents. It was designed for humans, and to be as simple and minimal as possible, while still offering a great DX (developer experience). But it turns out, these properties make it exceptionally well-suited for AI agents as well.

The whole source code of Mastro is just ~800 lines of TypeScript, which easily fits into an LLM’s context (or a human’s). And just like types prevent humans from making stupid mistakes, they do the same for LLMs.

To say that AI in general, and agentic coding in particular, are controversial topics may be an understatement. I’m not here to tell you what to think about AI. Personally, I see a number of downsides, but also some potential. LLMs can produce a lot of slop and terrible code. But when used properly, they can also be a big help, especially when learning. I have hopes for local models, but as of today, they’re not quite where Claude Code and Codex seem to be.

Agentic coding a website

The best way to get to know something new is usually to just try it out. Always wanted to create or overhaul your personal website or blog? Now is the time! Or just create a silly dummy website!

Create a new Mastro project with:

pnpm create @mastrojs/mastro

The following AGENTS.md file worked quite well for me:

We're using the Mastro web framework to build a statically generated site.

- To look up Mastro docs, use web search on
  `https://api.github.com/repos/mastrojs/mastrojs.github.io/contents/data/docs`
- Use web search with `site:developer.mozilla.org` to look up web platform
  features. Use the APIs if they're "Baseline Widely available".
- Write semantic HTML.
- CSS
  - Never add inline CSS
  - Avoid adding classes if you can use HTML element selectors
  - Use a [two-layer approach](https://theadminbar.com/semantics-and-primitives-color-system/)
    for CSS variables (primitives like `--blue: #0000ff`,
    and semantics like `--link-color: var(--blue)`).
  - Ask the user whether they want to only have a single global
    [styles.css](routes/styles.css) file (good for smaller projects),
    or whether they want to colocate CSS files with their HTML
    in [components](components/) and [bundle the CSS](https://mastrojs.github.io/guide/bundling-assets/#bundling-css).
- Only use [client-side JavaScript](https://mastrojs.github.io/guide/interactivity-with-javascript-in-the-browser/)
  if absolutely necessary. If so, use `<script type="module">`.

Note: if you’re using Claude, make sure you also have a file:

@AGENTS.md

And if you're not using Chrome for anything important (that you wouldn't be comfortable sharing with Anthropic), you can install the Claude Chrome extension. Then you can tell it for example:

@browser go to localhost:8000 and check for discrepancies

How did it go?

Does that setup work for you? What did you change in your AGENTS.md file? Let us know on Bluesky or GitHub!

Whatever happened to JavaScript Service Workers?

2026-03-09T12:00:00.000Z

What's the right way to think about Service Workers in 2026? Are they HTTP proxies, offline-capable web apps, or free frontend servers?

Not to be confused with Web Workers, which are relatively simple background threads for a website, Service Workers are a special kind of Web Worker. They have been available in all major browsers since 2017, but after a couple of years of hype, they largely disappeared from the web discourse again. Let’s fix that!

It’s sometimes a bit hard to grasp what Service Workers exactly are and what use-cases they enable. First, let’s look at three different views.

Service Workers as network request proxies

This may be technically the most correct view (which is the best kind of correct).

After visiting a website with a service worker, it’s automagically installed in the user’s browser. From then on, it can intercept network requests from that website and handle them, e.g. acting as an HTTP proxy that caches network requests.

There are various caching strategies to choose from, like downloading everything upfront, only using the cache when there is no network connection, stale-while-revalidate, and many more.

Service Workers as offline-capable apps

Yet service workers are not limited to caching resources as they are. Since they are implemented in JavaScript, they can also generate HTML pages on-the-fly – either by reading data from an on-device cache (like the CacheStorage or IndexedDB), or by reading from a JSON API server.

In this architecture, the service worker code is often called the “app shell”. It can be updated independently from, and less often than the content of the app – which is typically text and images.

If that sounds a lot like a native mobile app that periodically pulls in content, or like a Single-Page-App (SPA), you’re not wrong. All three kinds of apps run code on-device in order to render some kind of GUI.

Like mobile apps – but unlike SPAs – Service Worker apps work even when the device is offline – but only once they’re installed and have downloaded all the data they need to work offline.

Finally, if you add a manifest file with the app’s home-screen icon, you have a PWA – a Progressive Web App.

Service Workers as running a free frontend server on the client

Making a request to a JSON API and rendering the response to HTML can equally be seen as basically what a stateless frontend server does. But while you’ve got to pay someone to keep your server running, a service worker is free forever!

While an edge network (e.g. Cloudflare Workers) is closer to your users than a traditional server, nothing beats already being installed in your user’s browser. But yes, the service worker first needs to be installed. This can be as easy as having a static loading page, or having the user install the PWA first.

But sometimes you just need that first page load to be already server-side rendered and up-to-date. The good news is that this is totally doable. The bad news is that it does add a bunch of complexity. It’s a problem anyone who’s been trying to server-side render SPAs (e.g. with Next.js) is familiar with – although a service worker is much more similar to a server environment than a browser window with its DOM and state.

Of course, there are things you can do in a browser window that you cannot do in a service worker. For example triggering animations, playing audio, or displaying popups. While a lot can be done with modern CSS alone, you may sometimes still need client-side JavaScript inside the browser window for that kind of interactivity. But intercepting a page navigation and rendering the HTML in the client – the quintessential SPA – is much better done off the main thread and inside a service worker. That even lets you stream in the HTML, so that users can start interacting with the top of your page, while the bottom is still loading. And those interactions will be buttery smooth, since no JavaScript is blocking the main thread.

What’s the catch?

That all sounds great. And the 2025 Web Almanac says that of the top 1000 pages by page rank, roughly 30% are managed by a service worker – which is more than I expected. There is definitely value here for developers of established websites. But why isn't every website running a service worker?

The whole thing comes at the cost of having to figure out an installation, updating and content caching strategy. This is probably the primary reason service workers are not in such widespread use as originally imagined. Because cache invalidation is just really hard to reason about.

A cache does speed things up and enable offline use-cases. But it can also serve outdated data – potentially forever. Most web developers are used to their changes taking effect immediately. Without getting deep into HTTP caching headers, the default on the web is for things to update within a few minutes or hours.

The default with service workers is that they may update only after 24 hours – and unless you call skipWaiting(), only after all existing tabs are closed and a new tab is opened. The reason for this is the cache that may be shared by different versions of the service worker. But I'd argue it's still a bad default. While there are ready-made solutions like Workbox, not everyone wants to install a library that may be somewhat of a black box.

I'm thinking of putting some effort into one or two Mastro starter templates with service workers with good defaults. Perhaps one for the "offline-capable app" use-case, and one for the "frontend server on the client" use-case. What do you think, would that be useful? Or do you have experience implementing a sort of service worker kill-switch? Let us know on GitHub or @ us on Bluesky.

What does Mastro bring to the table for Service Workers?

Mastro is primarily a server-side web framework and static site generator. But since it’s so lightweight, it’s also well suited to do routing and HTML-rendering inside a service worker.

Mastro works well for either of the two architectures outlined above: an “app shell” that always renders everything in the service worker, or an “isomorphic” app that renders the initial page on the server (or Cloudflare Worker), and subsequent page navigations in the Service Worker – sharing all the code.

To get started, use this simple Mastro Service Worker example project.

Everything is a route: how to use one interface for servers, static-site- and asset-generation

2026-01-29T12:00:00.000Z

In Unix, everything is a file. In Mastro, everything is a route. You use the same standards-based Request/Response-API not only for writing your server, but also for static site and asset generation. Let me show you how.

The Request/Response-API is the modern way to write JavaScript servers. For example to return text/plain:

const myHandler = async (req: Request) => {
  return new Response("Hello world!");
};

It’s such a great interface that Mastro decided to go all-in on it, and use it for all of the following:

on-demand server-side rendering (SSR) of HTML pages, JSON REST APIs, RSS feeds, etc.
static site generation (SSG)
asset generation of resized images, CSS/JS bundles etc.

1. Server-side rendering

Server-side rendering is the obvious part. After all, that’s the use-case that popularized the Request/Response-API (e.g. when writing Cloudflare Workers). In Mastro, this looks as follows:

import { html, htmlToResponse } from "@mastrojs/mastro";
import { Layout } from "../components/Layout.ts";

export const GET = () =>
  htmlToResponse(
    Layout({
      title: "Hi",
      children: html`<p>Hello world!</p>`,
    })
  );

But even then, a lot of frameworks only use this Request/Response-API for JSON REST APIs, 404s and redirects, but not for normal HTML pages. For the 200-OK HTML case, this gets rid of the htmlToResponse function call – but it makes the other cases awkward.

2. Static site generation

During static site generation, all the HTML of the website is generated upfront before being deployed to a static file server or CDN. In a way, it’s the inverse of on-demand server-side rendering.

But if you forget in what order things happen, it is in fact a strict subset of the cases you encounter when on-demand rendering: the url-path of a GET request will fully determine what static file is served – query parameters and HTTP headers are ignored. As such, using a full Request object may be overkill.

But as a web developer, having one unified interface is nice. You don't have to switch back and forth between different ways of doing things. And it allows you to effortlessly change a route from being server-side rendered to being statically pregenerated. To do so, the only thing you need to add to the file above is:

export const pregenerate = true;

If your whole site it statically generated, you don’t even need to add that line.

When you execute the Mastro generate script, it will call all your route handlers with synthetic requests and create files from the output. (Tangent: to write side-effect-free unit tests for these route handlers, you can do the same: simply call the handler with a new Request(url). This requires no mocking, or spinning up a whole browser like with Playwright.)

Regardless of whether you have a server or a static site in production, for development you need a local server. As a bonus, this way of defining pages lets us use the production server also for local development. This ensures there are no differences between your development setup and production. The only difference is that for local development, Node.js/Deno/Bun are called with the --watch flag to leverage their built-in file watcher.

3. Asset generation

Most web frameworks have some sort of functionality to pregenerate static assets that are expensive to compute, like for example resized images, or bundled CSS or JavaScript. In Ruby on Rails for example, this is called the asset pipeline. In Vite-based frameworks it's usually a series of Vite plugins.

But what are assets if not simply pregenerated static files? Indeed, from Mastro’s point of view, it doesn’t matter at all whether you want to pregenerate an HTML file (i.e. static site generation), or a CSS or JavaScript file (i.e. asset generation) – or even a binary file like a transformed image. Just slap that pregenerate = true line from above on your asset route, and you can use Mastro to precompute it before starting your server. And again, if your complete website is static, you don’t even need that line.

For example, to generate a styles.css file containing the bundled CSS of all your components, create a route file named styles.css.server.js:

import { findFiles, readTextFile } from "@mastrojs/mastro";

export const GET = async () => {
  const files = await findFiles("components/**/*.css");
  const contents = await Promise.all(files.map(readTextFile));
  return new Response(
    contents.join("\n\n"),
    { headers: { "Content-Type": "text/css" } },
  );
}

And since the interface is the same as for any other HTTP route, if you know web standard HTML, you already know how to load this into your HTML:

<link rel="stylesheet" href="/styles.css">

Isn’t that beautiful? You can also extend this approach to do component-scoped CSS.

And again, we get the snappy development server for free, which computes the bundle on the fly and lazily. If you don't load /styles.css, it isn't computed either.

The same approach works for any other kind of content, e.g. for images. Using the @mastrojs/images package:

import { createImagesRoute } from "@mastrojs/images";

export const { GET, getStaticPaths } = createImagesRoute({
  hero: {
    transform: (image) => image.resize(300, 300),
  },
  hero2x: {
    transform: (image) => image.resize(600, 600),
  }
});

This declares two image presets: hero and hero2x. Assuming you have a file images/blue-marble.jpg, you would request resized versions in WebP format as follows:

<img alt="Planet Earth"
  src="/_images/hero/blue-marble.jpg.webp"
  srcset="/_images/hero2x/blue-marble.jpg.webp 2x"
  >

The beautiful thing here is that we didn't have to build image transformations into Mastro itself, nor does Mastro have a complex plugin API that we'd need to keep compatible. @mastrojs/images is an independent package, that simply exports the GET function that adheres to the standard Request/Response-API. (It also exports the getStaticPaths function, which is Mastro-specific, but that just returns the paths used for static site generation as strings – hardly a complex API.)

Similarly, to bundle JavaScript, we could call e.g. esbuild in the route handler. For an example of that, have a look at the bundling and assets chapter in the Mastro Guide.

Conclusion

By inverting the flow of a classic asset pipeline, and leveraging the standards-based Request/Response-API, we managed to unify the development server, production server, static site generation, and asset generation mechanisms. That's how Mastro gets by with just ~800 lines of implementation code.

Improve Time to First Byte by streaming your HTML

2026-01-13T12:00:00.000Z

If you have a statically generated website hosted on a CDN, it’s probably very fast (unless you add too much client-side JavaScript).

However, for dynamically generated pages that load content from a database, one of the most overlooked ways to speed up the perceived page load speed is HTTP streaming.

Unless you do streaming on your server, when you load rows from your database, it’s usually loaded into an array (or a similar structure), and only when the whole database query is done, the server continues assembling the HTML. And only when the whole page’s HTML is completely assembled, the server starts sending it over the wire to the browser. In JavaScript, this usually has the await keyword in front of the db.query() call. This is especially slow if you have a slow database, or a database call returning many rows.

Streaming

Enter HTTP streaming. In HTTP/1.1, this was known as chunked transfer encoding (some of you may remember it from PHP’s flush() function). But in HTTP/2 and HTTP/3, streaming is built in at the lower levels of the protocol.

The idea is simple: if for example the header of our page doesn’t depend on a database call, we can immediately send it over the wire to the browser. This dramatically improves time to first byte, and users can start reading the top of our page, while our server is still waiting for the database.

But there is more: if we have a page displaying hundreds or even thousands of rows from our database (perhaps a table, dashboard, or just your blog’s index page), we can also stream the database’s response, and display the HTML that was generated form the first result row, while the last row hasn't even left the database yet. All we have to do is not block the streaming anywhere in the whole chain from the database driver, to the HTML templates, all the way to your web hosting provider and CDN proxy. If there’s an await or similar anywhere in that chain, which blocks until the whole page is loaded, then it cannot be streamed.

JavaScript/TypeScript example

Let’s look at a simple example using the Mastro server framework to generate the HTML, and Kysely to query the database. Here’s the page handler for an HTTP GET to our page:

import { html, htmlToResponse } from "@mastrojs/mastro";
import { Layout } from "../components/Layout.ts";
import { db } from "../db/db.ts";
import { mapIterable } from "../db/iterable.ts";

export const GET = (req: Request) => {
  const rows = db
    .selectFrom("person")
    .select(["first_name"])
    .where("gender", "=", "woman")
    .stream();
  return htmlToResponse(
    Layout({
      title: "Hello World",
      children: html`
        <p>Welcome!</p>
        <ul>
          ${mapIterable(rows, (row) =>
            html`<li>${row.first_name}</li>`)}
        </ul>
      `,
    }),
  );
};

Note that we’re doing rows = db.stream() instead of rows = await db.execute(). While the latter would return an array, the former returns a JavaScript Iterable. More specifically, an AsyncIterable containing Promises.

While JavaScript already has standard Iterator helpers, Async Iterator Helpers are unfortunately still a work in progress. Thus we had to roll our own mapIterable functions, which loops the Iterable just like you would map over an array. But importantly, it streams results through as they come in: the result of the mapIterable is again an AsyncIterable, which can be passed to the html template. Finally, the htmlToResponse function constructs a standard JavaScript Response.

Feel free to check out and play around with the whole example project. Finally, to stream JSON data as server-sent events, see HTTP Streaming in the guide.

This article was originally published on the Web Performance Calendar. Read the original article.

Why not just use inline styles Tailwind?

2025-11-27T12:00:00.000Z

Are WYSIWYG word processors, inline styles, and Tailwind conceptually the same? How to make the best use of modern CSS and HTML elements? And what do we actually gain by adding abstractions like style names and components, and what do we lose?

There are many different ways to render text to pixels using a computer. Let’s go through some! We'll start with the lower level ones (closer to the hardware, or at least to the characters), and then subsequently add more and more abstractions, also known as adding levels of indirection.

Direct control

If you’ve ever changed the font-size and font-family of individual words or paragraphs of text in a WYSIWYG word processor like Microsoft Word, you’re familiar with this approach to layouting.

In web development, we’ve also had several iterations of this same basic and direct interface:

the deprecated HTML font element <font size="7">Hi</font>
CSS inline styles <span style="font-size: 20px">Hi</span>,
Tailwind: <span class="text-xl">Hi</span>

The nice thing about it is that it gives you direct and immediate control over the text you’re looking at right now. The not so nice thing about it is that if you’re not careful, it quickly leads to an inconsistent mess of different styles.

Reusable styles

To solve these inconsistencies, we add our first abstraction; our first level on indirection: we give names to different styles that we then reuse in different places. This ensures all those places look the same. If we change the style, all places that use will automatically change.

In desktop publishing software like Adobe Indesign, you set up character- and paragraph-styles. In LaTeX you add a bunch of macros. For the web, CSS was invented as a solution for this very problem – to replace the <font> tag. In web development circles, this idea is known as the “separation of concerns” – where you separate between content (written in semantic HTML), and layout/styling (written in CSS).

Reusable components

But people kept building ever more complicated websites, and chunks of HTML were repeated in various places, but slightly inconsistent. So we added another level of indirection: components (or in older templating systems called includes or partials) – blocks of several HTML elements that you can reuse in multiple places. (Conceptually similar to a function that you can call in multiple places.)

It’s a powerful, and often very useful, abstraction. In fact, it’s so powerful that people started to use it everywhere for everything. And since everything was a component now, people wondered why they still needed the abstraction that was CSS. If the only place you were using a <h2> tag in your whole codebase was in the <Title> component – then why not add the styles right there? That’s one reason why Tailwind is so popular.

And to be fair, if everything is a component, then why not? But should everything be a component? Do I need a <Button> component if I have a perfectly good <button> HTML element? The answer is, as always, it depends. Perhaps if it’s a very, very complicated button, with lots of different variants. But didn’t we want a consistent layout?

The one gripe I have with components is that they are usually a build-time abstraction: you don’t see them anymore in the browser’s dev tools element inspector. Unless you use web components, but then you have to deal with the shadow DOM, which is its own, hard to penetrate, level of indirection. Or unless you use your framework’s custom developer tools extension, but there you usually don’t see the HTML elements anymore, only your components.

Modern HTML and CSS

Meanwhile, HTML and CSS have not stood still. There are plenty more semantic HTML elements nowadays (like <main>, <header>, <footer>, <section>, <search>, etc.), and you can style them with attribute selectors, parent selectors, and much more. But to use those effectively, you need to be aware of exactly what HTML elements you have on your page, and how they’re nested. And if you overuse components, that abstraction makes it harder to see directly in your code what HTML you'll have in your browser.

To be clear, I’m not saying you should never use components. But I’d recommend going with the least powerful abstraction that still solves your problem. And more often than not, this is semantic HTML with a little bit of CSS. Indeed, there is a danger with CSS that you can get yourself into a mess if you don't restrict yourself enough. Since CSS is so powerful, sometimes you have to be mindful of every character. It pays off to adhere to a few principles like:

Use the direct child combinator > instead of the space wherever possible. (The space selects all children, regardless how deeply nested.)
Don’t invent new classes for everything, but use element selectors where possible. (Read this great piece by Heydon Pickering for elaboration of this point.)
Take a bit of time to set up a few CSS variables, then restrict yourself to using those instead of magic numbers for spacing and sizes.

And sure, maybe you’ll need to factor out a few things to reusable components once your website grows. And you may even want to place their CSS file in the same folder as the component, and use the name of the component as a class. (In HTML5, class attributes are case-sensitive. So one way to mark your classes as “tied to a component” is to uppercase them.) But that doesn't mean you need a bundler or baroque build step: if you have many CSS files and are worried about performance, you can just concatenate them.

Data and reusable templates

On another front, long before there was any talk about components, people wanted to reuse the same content on different pages. Possibly the simplest example is to reuse the titles of your blog posts on the index page of your blog. It would be annoying having to keep the index page and the detail pages manually in sync by always updating both, when you change the title of a blog post.

Thus, another level of indirection was introduced. Instead of having plain HTML files, you have some kind of separate data format: either a database, or maybe just plain markdown and YAML or JSON files.

As with any of the levels of indirection we’ve been talking about here, this especially shines for high-volume productions (i.e. your website has lots of content). And you want all that content to be laid out consistently.

Jeff Eaton has a wonderful slide deck about CMSes with this grid in it:

	low volume	high volume
consistent	piece of cake	structure, templates, APIs
unpredictable	custom design, development	here be dragons

If you’re doing low volume, unpredictable stuff, all these levels of indirection might only get in your way. Why separate content and layout, and why reuse styles, if you only have a handful of things to style anyway? Then you might be better off just using a graphical tool like Webflow, or slapping those inline-styles or Tailwind classes on your stuff.

Tailwind

Did I just say Tailwind is conceptually the same as inline-styles? Yes. Tailwind’s answer to why not just use inline styles? says something about a "predefined design system" (which you can easily set up with CSS variables as well), and about responsive/hover/focus (which are trivial in plain CSS). But they don’t seem to disagree with the claim that at least conceptually, Tailwind is equivalent to inline styles.

What Tailwind unfortunately does impose is a build step, which is another giant level of indirection – especially since it's not a simple transform, but comes with a lot of logic and non-standard CSS keywords like @theme and @utility. And if you inspect an element in your browser's developer tools to debug something, you'll have to understand all that indirection as well.

But there are plenty of utility-class CSS frameworks out there that don't require a build step, if that's what you're after. Whether the elimination of unused CSS is worth the build step is for you to decide. But I wouldn’t sweat the CSS size too much. Consider how big your HTML payload is anyway with all those utility classes, static CSS usually has fairly long cache live-times set, and finally both compress well over gzip/brotli.

Levels of indirection

What’s the take-away of all this? You may have heard this quote:

We can solve any problem by introducing an extra level of indirection – except the problem of having too many levels of indirection.

The difficulty is knowing in which situation you find yourself today.

How to generate og:images from text with Canvas

2025-11-16T12:00:00.000Z

Use the web-standard Canvas API to render text to PNG – without spinning up a whole web browser. Here's how we implemented this approach in @mastrojs/og-image.

A few weeks ago, Scott Jehl posted about the pain of generating Open Graph images: those images you link to with an og:image meta tag from your HTML, which are then displayed on social media or messenger apps when somebody shares a link to that page. (Side-note: a single <meta property="og:image" tag, together with the standard <title> and <meta name="description", is kind of enough.)

Most tools that generate those preview PNGs download and launch a full-blown web browser to take a screenshot of some HTML and CSS that you wrote. While that works, I've had something lighter in mind. All I wanted, was to render the title of the page on a nice-looking background. That sounded doable with the standard Canvas API. Since we don't actually have a browser running when we statically generte our website (d'uh), I used canvaskit-wasm, which emulates a <canvas> in Node.js or Deno.

Now we just have to call fillText(text, x, y) and we're done, right? Not quite. fillText only ever prints a single line of text. What we want is to start a new line when there's no more horizontal space. We need to call fillText again with as much of the remaining text as fits on the next line (and with a y-coordinate of one line-height more than before). And then we continue doing that until we have no more text. If that sounds suspiciously like a layout algorithm to you, you would be right. We even added support for soft hyphens: if the word doesn't fit, but contains at least one soft hyphen, we will hyphenate at the right place. But since we didn't feel like shipping hyphenation dictionaries, you'll need to supply your own soft hyphens to the input.

Feel free to look at the source code. That whole text layouting part is in the util.ts file.

Next up was publishing it as the @mastrojs/og-image package. There you can also see usage examples. The single exported function takes a bunch of options like font, color and padding, to get you started. But in typical Mastro fashion, the API is more powerful than it seems at first glance: using background, you can supply your own function to draw the background image using the standard Canvas API. If you come up with a nice background generating function, please share it on GitHub Discussions. That would be almost like a theme gallery!

Last step for me was to use the package for this very website: for this blog, Mastro docs, and the guide. Running deno task generate to generate the whole static site, including rasterizing and writing to disk the 42 og.png files, takes 2.6 seconds on my MacBook Air M2. Without the image generation, it was 0.6 seconds. I'm not sure how long it takes to spin up a browser and take screenshots, but pretty sure it's longer.

Don't forget to share this post on social media to actually see our glorious, generated image 🤓 If on Bluesky, please mention us with @mastrojs.bsky.social!

How to incrementally migrate from Express to the standard Request/Response API

2025-11-06T12:00:00.000Z

You want to migrate to the modern way to write JavaScript servers, which is supported across JavaScript runtimes. Deno.serve, Bun.serve, Cloudflare Workers etc. – they all use the same standards-based Request/Response API for route handlers:

export const handler = (req: Request) => {
  return new Response(`Hello ${req.url}`);
}

But how do you incrementally migrate from your existing Express app? Simple: start by adding your new server handlers to your existing Express server using the node-fetch-server conversion wrapper:

import { createRequestListener } from "@remix-run/node-fetch-server";
import express from "express";

import { handler } from "./new-server.ts";

const app = express();

// here go legacy express routes you haven't migrated yet

app.all("*rest", async (req, res) => {
  const listener = createRequestListener(handler);
  return listener(req, res);
})

app.listen(3000);

This allows you to incrementally move over each route from the express way of doing things to the new Request/Response API. Crucially, it allows you to have both old and new route running in the same server in production, so you don't have to stop everything and your team can continue to ship new features and bug fixes during the migration.

Finally, when all routes are migrated, you can remove Express from your codebase. For example, using Deno:

import { handler } from "./new-server.ts";

Deno.serve(handler);

Migrating to Mastro

If you're migrating to the Mastro framework, you would replace new-server.ts in the above examples with importing the Mastro server. During the migration:

import mastro from "@mastrojs/mastro/server";
import { createRequestListener } from "@remix-run/node-fetch-server";
import express from "express";

const app = express();

// here go legacy express routes you haven't migrated yet

app.all("*rest", async (req, res) => {
  const listener = createRequestListener(mastro.fetch);
  return listener(req, res);
})

app.listen(3000);

And then when you've removed Express but are still on Node.js:

import mastro from "@mastrojs/mastro/server";
import { createRequestListener } from "@remix-run/node-fetch-server";
import * as http from "node:http";

const server = http.createServer(createRequestListener(mastro.fetch));
server.listen(3000);

Or when you've migrated to Deno:

import mastro from "@mastrojs/mastro/server";

Deno.serve(mastro.fetch);

Congratulations and welcome to the future!

What I learned porting Mastro to Bun

2025-10-29T12:00:00.000Z

In our last blog post, I talked about What I learned porting Mastro from Deno to Node.js. The next step was of course to get Mastro working on Bun as well.

And again, there were some gotchas that took me some time to resolve. Let’s go through them.

fs.glob

The first thing I immediately ran into was easy to understand. Calling the Node.js fs.glob function with the withFileTypes option in Bun, while type-checking fine, results in a “not-implemented” runtime error. There’s a Bun GitHub issue about that, with @robobun making a half-hearted attempt at a PR. You might wonder who @robobun is, and looking at their profile, it says “the official helper for Bun” – appears to be some AI bot.

Anyway, I just resorted to calling fs.glob without the withFileTypes option when in Bun, and making a call to stat for each file, to determine whether it’s a folder or a file.

URLPattern

Next one up. While all three major browsers, Deno, and Node.js now support URLPattern, there is still an open issue about it in Bun.

This was also relatively easy to fix by loading the urlpattern-polyfill, which I added as a dependency to Mastro’s Bun starter template.

bun create

The first tricky one was that running

bun create @mastrojs/mastro@latest

failed to detect that we were running in Bun, and would download the wrong template – even when I checked for typeof Bun or process.versions.bun, which are the official ways to detect that.

But after publishing that package a few times, waiting for it to propagate through the CDNs, and running the command again, I was certain: neither of these work when inside bun create. Probably they're shimming it somehow to fake Node.js compatibility. But I couldn't find any official docs on that.

Thus we do what other such packages seem to do:

process.env.npm_config_user_agent?.startsWith("bun")

Bun.write

When generating the static files, I wanted to call Bun.write instead of the weird Node.js code. That was the second weird gotcha: Bun.write apparently doesn't take a standard ReadableStream, only: string | ArrayBufferLike | TypedArray<ArrayBufferLike> | Blob | BlobPart[]. Just to be sure, I tried passing it a ReadableStream. It didn’t fail at runtime, rejoice! But wait. What do we find when opening the generated file in a text editor? The file contains the contents [object ReadableStream] 🤡

So what does that mean? Does Bun.write just not support streaming into a file? Will it always have to wait for the whole thing to be written into a Buffer in memory first? The official workaround is to go through a Response object, which might or might not stream 🤷🏽‍♂️

Be that as it may, I already had a Response object coming from the Mastro route handler. So I decided to special-case it and directly pass it that Response object (instead of response.body, which is a ReadableStream). Then I ran the program. And... nothing. Like, literally nothing happened. It didn’t print “Generated static site and wrote to generated/ folder” like Mastro usually does. And indeed, while it created the folder, it was empty. But exit code was zero.

So I put some console.logs and an additional try-catch around it:

console.log("before");
try {
  const nrBytesWritten = await Bun.write(outFilePath, response);
  console.log("after", nrBytesWritten);
} catch (e) {
  console.log("caught", e);
}

The above logged "before", and again exited with an exit code of zero. Yes, it just silently seemed to crash. Wow.

For all that the Bun.write docs like to advertise "the fastest syscalls available to copy from input into destination", that doesn't help a whole lot if it doesn't work properly.

And no, I cannot be bothered to create a reproducible test case right now. For the record, this was in Bun v1.3.1 on macOS 15.7.1, and I ran it in the Mastro template for Bun after editing node_modules/@mastrojs/mastro/src/generator.js directly. It might have something to do with response coming from a dynamically imported module (the route handler), or I don't know. I am happy to accept pull requests though, should anybody feel called to make Bun.write work in Mastro.

But for now, the moral of the story seems to be once again to just use Node.js's old-school and verbose API. At least that works – even in Bun.

Either way, it would actually be interesting to update our benchmark to see whether streaming the Response.body into the file is actually really faster and/or consumes less memory, compared to serializing to a string first, and test it in Deno, Node.js and Bun.

Conclusion

While those were weird, the good news is that overall, supporting Bun required very few code changes to Mastro.

What I learned porting Mastro from Deno to Node.js

2025-10-27T12:00:00.000Z

The Mastro web framework and static site generator initially ran only in the browser and Deno – it was living in the future, so to speak. Here's the story of how I ported it to Node.js (which has a surprising amount of functionality built-in nowadays), and what I would do differently next time.

The first part of Mastro that I coded was actually Reactive Mastro (a tiny reactive GUI library), which needs to run only in the browser. Then, I reused that minimal way to construct HTML in the Mastro web framework and static site generator.

I started developing Mastro on Deno. The idea was (and still is) to build a modern tool from first principles – with minimal dependencies. Deno’s extensive standard library, early adoption of web standards like URLPattern, and builtin TypeScript support, made it a relatively easy choice. It was like building an MVP of Mastro in a future version of the JavaScript ecosystem. I don’t even remember whether Bun was already around at that time, or whether Deno’s philosophy of a green-field approach just more appealed to me for my green-field project. At that time, I didn’t know yet whether Mastro would be a one-off experiment, or whether it would turn into something with legs. But after getting it running on Deno, I found it had promise.

In just ~800 lines of TypeScript, I had something that covered like 90% of my use-cases when building websites. It was a very nice bonus that I got the static site generator running as a VSCode for the Web extension, running completely inside the browser. (Try it online)

Deno 2.0 and Node.js compatibility

Then Bun and Deno 2.0 happened, having extensive Node.js compatibility, and even Cloudflare joined in. The Node.js builtins seem to have become the standard library across JavaScript server runtimes – for better or worse. And to be fair, the commitment of the Node.js project to stability is actually something I’d like to see more of in the JavaScript ecosystem.

With Node.js now supporting TypeScript natively, I started to wonder: how much work would it take to make Mastro run in Node.js? And would the result still be minimal, maintainable, and without a build-step? Or would it be too riddled with compromises and if-Deno-else-Node cases?

Deno namespace adieu

So I got to work. Targeting Node.js v24 LTS, we got builtin TypeScript type-stripping, --watch flag, a test runner, and URLPattern support. The first step was obviously to remove all calls to functions in the Deno namespace (like Deno.readTextFile), and replace them with the Node.js equivalents, which run just fine in Deno as well. This was mostly painless.

Pretty much the only case where I decided to still use a Deno-only function when it was available was for writing a stream to a file. Because look at that – please let me know if there's a better way!

const writeFile = async (path: string, data: ReadableStream<Uint8Array>) => {
  if (typeof Deno === "object") {
    return Deno.writeFile(path, data);
  } else {
    const { createWriteStream } = await import("node:fs");
    const { Readable } = await import("node:stream");
    return new Promise<void>((resolve, reject) =>
      Readable.fromWeb(data as any)
        .pipe(createWriteStream(path))
        .on("finish", resolve)
        .on("error", reject)
    );
  }
};

Since Mastro’s route handlers return a standard Response object, and all we have to do now when generating a static file is to call writeFile("index.html", response.body) (using the response.body property), which seems extremely lean. Now let's look at the case of running a server (either for local development, or for production).

Polyfilling Request/Response API

Using the standards-based Request/Response API for route handlers was one of the very first design decisions for Mastro. Val Town’s Steve Krouse called this the API we forgot to name, and Marvin Hagemeister more recently the modern way to write JavaScript servers. Now, on Deno, you can pass such a handler to Deno.serve, and you’re pretty much done: it will start a server, and you can open your website in the browser.

Unfortunately, this is not something Node.js supports (and apparently has no plans to). Thus we need a polyfill: fortunately, the @remix-run/node-fetch-server package does exactly that, seems high-quality, and has no dependencies itself. In keeping with Mastro’s philosophy of exposing primitives and simple helper functions wherever possible, I decided to simple add node-fetch-server to Mastro’s Node.js starter template, where people can configure it to their liking, or even swap it out with something else. Check it out in the server.ts file, it’s still relatively bare-bones – even if not quite as clean as in Mastro’s Deno starter template.

HTTP imports and stdlib

Node.js also doesn’t support http imports. In fact, they recently reverted the --experimental-network-imports flag, because it wasn’t clear how this would work within Node’s security model. This forced me to reorganize some code, and move some non-core Mastro helpers out to their own packages. Arguably, this was for the best anyway, as it makes the modular nature of Mastro clearer. These packages are each only a single file, wrapping a carefully chosen external dependency.

The last two functions from Deno’s standard library that I needed were contentType from @std/media-types and serveFile from @std/http. The former wasn’t a problem, because that package is marked as Node.js-compatible. The latter I ended up simply copying into the Mastro codebase (with proper attribution). They are both pure functions that run on Node.js without any problems.

And voila, we have Mastro fully running on Node.js! But hold on, we still need to publish it as a package somewhere.

NPM vs JSR

If you haven’t been following the Deno ecosystem, you may be surprised to hear that there’s an alternative to the NPM package registry now: JSR. While its search absolutely sucks, its auto-generated docs pages are quite nice. And most importantly for me personally: I can simply push my TypeScript files to it, and it will make the transpiled JavaScript files available for consumption with Node.js. No need for me to install and update TypeScript, @types/node, nor understand the various fields in tsconfig.json. That's all contained in the deno executable.

While pnpm is recommended to consume JSR packages, npm and yarn also work through a compatibility layer. For the Mastro VSCode extension, I use esm.sh to import the Mastro JSR package in the browser.

Thus I have a very simple and lean setup for maintaining a single code-base that runs in the browser, Deno and Node.js – with almost no duplicated code. (After quite some fiddling and experimenting, Bun works as well now, but that's a story for another blog post.)

JSR and npx

To create a new Mastro project, I used to advertise deno run -A jsr:@mastrojs/mastro@0.3.0/init, which would download and run the init export directly from the @mastrojs/mastro package from JSR and run it. Simple.

But remember, Node.js doesn’t do scripts over HTTP. In the Node.js ecosystem it’s all npx nowadays. Or apparently npm create, which runs npx and just prepends create- to the package name?! But then at least you can do pnpm create instead of pnpm dlx 🙈 Either way, unfortunately JSR doesn’t support generating a package.json with a bin field – which is what npx or npm/pnpm create needs when you execute:

pnpm create @mastrojs/mastro@latest

Thus what I ended up doing was simply moving that script out to its own package, and publish that one to NPM. So now the above command works. Because I didn’t want to add TypeScript and a build step just for that, I opted to write that script in plain JavaScript, put the TypeScript type annotations in JSDoc comments, and add a //@ts-check at the top of the file. That way, I can run deno check on it and it’s fully type-checked.

Conclusion

If I’d start a new project today that needs to run on many JavaScript engines, I’d obviously plan ahead a bit more, and use Node.js builtins over the Deno namespace where possible.

But overall, I’m quite happy with how things turned out. Deno allowed me to “live in the future”, before the same features landed in Node.js. And for some things, this is still the case; like Deno.serve (which you can polyfill), or not having to npm install and deal with the node_modules folder.

I hope by reading this, you can avoid some of the pitfalls in your next project.