DEV Community: paulbrowne

JavaScript in, HTML out: building a simpler static site generator

paulbrowne — Fri, 14 Aug 2026 10:20:00 +0000

I build a lot of websites, and at some point I started wondering: why does building a mostly-static website require so much stuff?

A framework, a bundler, a router, a rendering strategy, hydration, server components, client components, adapters, deployment configuration… all to eventually just send some HTML to a browser.

So I built ⁠Sitelo a small, zero-config framework for building fast websites with JavaScript:

npm install -D sitelo

JavaScript in. HTML out.

The basic idea behind Sitelo is deliberately boring. Create:

src/
  index.ht.js
  about.ht.js
  blog/
    [slug].ht.js

The .ht.js marks a file as a page — Sitelo turns each one into a route.

And Sitelo turns that into a website.

Your pages (files named *.ht.js or .html.js) are JavaScript functions that return HTML:

// index.ht.js

export default () => `
  <html>
    <head>
      <title>Home Page</title>
    </head>
    <body>
      <h1>Hello world</h1>
    </body>
  </html>
`

Then:

sitelo build

And you get static HTML in dist/ There’s no application runtime required to serve it, no hydration, and no JavaScript shipped to the browser unless you actually ask for it.

Zero JavaScript should be the default

A lot of modern frameworks start with a JavaScript application and then give you increasingly sophisticated ways to reduce how much JavaScript reaches the browser.

Sitelo starts from the opposite direction: there is no browser JavaScript by default.

If your page doesn’t need JavaScript, Sitelo doesn’t send any. If it does, link a script:

export default () => `
  <html>
    <head>
      <title>Hello</title>
      <script src="/js/some-frontend-script.js"></script>
    </head>
    ...
  </html>
`

Sitelo sees it and lets Vite bundle it, while the rest of your page-generation code stays on the build side.

This gives you a very simple mental model:

Generate HTML first. Add JavaScript only where the browser actually needs JavaScript.

But I still want modern framework features

So do I. Simple shouldn’t mean primitive.

Sitelo has file-based routing:

src/about.ht.js          → /about
src/blog/[slug].ht.js    → /blog/:slug
src/docs/[...path].ht.js → /docs/*

It has build-time data loading and dynamic routes, supports JavaScript and TypeScript, and if you like JSX, you can use .jsx and .tsx too.

Sitelo uses Vite internally, so CSS, TypeScript and browser JavaScript still get the modern tooling you’d expect — you just don’t need to configure Vite yourself.

Static doesn’t mean everything has to be static

One of my favourite parts of Sitelo is server islands.

Most of a page can remain static:

┌─────────────────────────────┐
│                             │
│       Static HTML           │
│                             │
│     ┌───────────────┐       │
│     │ Server island │       │
│     └───────────────┘       │
│                             │
│       Static HTML           │
│                             │
└─────────────────────────────┘

Individual regions can then be rendered on the server at request time.

That means you don’t have to turn your entire site into a server-rendered application just because one part of one page needs dynamic content. The site stays static where it can be, with small dynamic pieces where they’re actually needed.

Batteries included, without becoming a kitchen sink

There are a bunch of small things that every real website eventually needs, and Sitelo handles those too.

You can generate things like:

404.html
sitemap.xml
RSS feeds
static search with Pagefind

There are also deployment configurations for Netlify, Vercel, Cloudflare Pages and AWS Amplify.

The dev server includes a small toolbar showing things like the current route, source file, parameters and island count.

The goal isn’t to add every possible feature. It’s to remove the repetitive work between:

“I want to build a website”

and

“Here’s the website.”

It’s also designed for coding with AI

There’s another reason I wanted Sitelo to stay small and predictable: AI coding agents work particularly well when the rules of a project are simple.

They’re considerably less useful when they have to reason about seven layers of framework abstractions before changing an <h1>.

Sitelo can generate llms.txt and project rules that explain the framework to coding agents. More importantly, the framework itself has a small mental model:

Files are routes. Functions generate HTML. Browser code is explicit.

That makes the project easier to reason about, whether the code is being written by a human or an AI agent.

Why not Astro?

Astro, Next.js, Eleventy, Hugo and the many other tools in this space are great at what they do. Sitelo isn’t an attempt to prove that they’re bad or replace them.

It’s an attempt to explore a smaller point on the framework spectrum.

I wanted something where I could:

write JavaScript → generate HTML → deploy it anywhere.

At the same time, I still wanted file-based routing, dynamic routes, data loading, Vite, TypeScript, JSX, search and the occasional bit of server rendering — without starting every project by making a bunch of architectural decisions.

That’s the space Sitelo is trying to occupy.

Who is it for?

I think Sitelo makes the most sense for:

documentation
blogs
marketing sites
portfolios
company websites
content-heavy sites
sites backed by a CMS or REST API
developers who like JavaScript but don’t necessarily want a JavaScript application

If you’re building something that behaves primarily like an application, use an application framework.

But if you’re building a website, maybe start with HTML.

Sitelo is open source and MIT licensed.

sitelo docs
npm sitelo
github

I’d love to see what people build with it — and if you find something that makes Sitelo more complicated than it needs to be, open an issue.

The whole point is to keep it boring, in the best possible way.

inline imports FTW!

paulbrowne — Thu, 06 Mar 2025 16:00:00 +0000

event-import-then-function

html

<input
    onchange="import('/js/form.js').then(M => M.default(this))"
/>
<input
    onchange="import('/js/form.js').then(M => M.reverse(this))"
/>
<input
    onchange="import('/js/form.js').then(M => M.upperCase(this))"
/>

note: the M is just short for Module

form.js

console.log('form.js loaded')

export const reverse = element => {
    element.value = [...element.value].reverse().join("");
}

export const upperCase = element => {
    element.value = element.value.toUpperCase();
}

export default element => {
    console.log(element.value)
}

In the above example form.js will be loaded only once, no matter how many times the onchange events are triggered. So you'll only ever see one "form.js loaded" in the console.

Since the loading of form.js is deferred until after the onchange event has been triggered, there will be a slight delay whilst the browser fetches it.

If you want to avoid this delay you can always prefetch the resource by adding:

<link rel="prefetch" href="/js/form.js" />

to the html. This will of course fetch the file regardless if the user ever needs it.

Lazyload Scripts like Images

paulbrowne — Sat, 05 Oct 2024 10:57:40 +0000

One of the best improvements to html over the recent years was the loading="lazy" attribute that you can add to images (also iframes) that will tell the browsers to not load the image until it is in the viewport.

    <img src="/images/your-image.png" loading="lazy">

Very simple, very useful. But wouldn't it be great if you could do this for scripts as well. So that you could lazily load your components, only if/when they are actually needed...

Well, one other feature the <img> element has, is the ability to run a script after the image loads (or doesn't load) with the onload and onerror attributes.

    <img 
        src="/images/your-image.png" 
        loading="lazy"
        onload="() => console.log('image loaded')"
    >

This onload "callback" will only be fired when that image is loaded, and if the image is been lazily loaded, then it will fire only when the image is in the viewport. Et voilà! A Lazily loaded script.

Unfortunately, like this, it isn't much use. Firstly you'll have a unwanted image on your page, and secondly, you'll need to inline the javascript you want to run, which kinda defeats the purpose of lazy loading. So, lets make some changes to improve on this.

The image itself can be anything, or, more importantly, nothing. As I mentioned earlier there is the onerror callback, which - as the name would suggest - will fire when the image doesn't load.

This doesn't mean you need to point the src to a non-existent image, that would result in a console full of red 404 errors about missing images, and nobody wants that.

The onerror callback also fires if the src image is not actually an image, and the easiest way to do that is to "badly encode" an image using the data: format. This also has the benefit of not filling the console with warnings of missing images 👍

    <img 
        src="data:," 
        loading="lazy"
        onerror="() => console.log('image not loaded')"
    >

This will still result in the page having the "broken image" thumbnail, but we'll get to that.

Ok, But we still need to inline the javascript we want to run, so how do we fix that?

Well, now that ES module support is almost universal, we can use the very powerful event-import-then-default javascript loading technique to load a script after an event has fired, like so:

    <img 
        src="data:," 
        loading="lazy"
        onerror="import('/js/some-component.js').then(_ => _.default(this))"
    >

Note: This also works for onclick, onchange, etc. events
Note: The underscores are just shorthand way to access the Module, you could also write .then(Module => Module.default(this))

Ok, so what is going on here!?

First lets take a look at what some-component might look like:

// some-component.js

export default element => {
    element.outerHTML = `
        <div class="whatever">
            <p>Hello world!</p>
        </div>
    `;
}

So, you might have noticed that in the onerror callback, I passed this as an argument to the default export. The reason I did this (excuse the pun 😁) was to give the script the <img> that called it, since in this (I did it again 🤦) context this = <img>.

Now you can simply element.outerHTML to replace the broken image with your html markup and there you have it, lazyloaded scripts! 😱

Caching, and Passing Arguments

If, you are using this technique more than once on a page, then you'll need to pass a "cache-busting" index, or random number to the data:, eg, something like:

    <img 
        src="data:,abc123" 
        loading="lazy"
        onerror="import('/js/some-component.js').then(_ => _.default(this))"
    >
    <img 
        src="data:,xyz789" 
        loading="lazy"
        onerror="import('/js/some-other-component.js').then(_ => _.default(this))"
    >

The string after the ":," can be anything, just so long as they are different.

A very simple way to pass params to the function would be to use the data-something attribute in the html like so:

    <img 
        src="data:," 
        loading="lazy"
        data-message="hello world"
        onerror="import('/js/some-component.js').then(_ => _.default(this))"
    >

Since we are passing the this to the function, you can access the data attributes like so:

export default element => {
    const { message } = element.dataset
    element.outerHTML = `
        <div class="whatever">
            <p>${message}</p>
        </div>
    `;
}

Please let me know what you think in the comments! ❤️