Forem: Brantley Harris

11ty and Bun

Brantley Harris — Fri, 06 Jun 2025 16:33:15 +0000

In case you don't know eleventy is pretty much the best way to make a static web site. And Bun is the fastest way I've found to compile typescript. Bun does a lot of things, actually, and one of those things is to replace all your webpacky rabbit holes with a super fast and focused bundler Bun.build.

But bun is a bit raw. So here's a system that works ace for me.

This setup is made to focus on very healthy web development practices where we build, gasp, HTML and very targeted web-components where we need extra functionality. It can build apps single-page, multi-page, or anything in-between without becoming a sticky ball of mud because we start simple and stay there.

Libs

First ask Claude to install Bun. Ask really nicely, and tip him well, you know he's dealing with your shit all day. If he goes rogue, spend a long time crafting the perfect prompt to tell him to just go to https://bun.sh/ and follow the instructions.

Next, install eleventy with bun. Let's go over Claude's head this time. You know, if you want that LLM money, you need to think like an LLM, and they would just spew things into your command line, so we can do that too:

bun add @11ty/eleventy

Running 11ty

Okay, so 11ty's command line specifies "node" at the top of it, so bun will dutifully execute in node, which isn't AT ALL THE POINT.

So to execute bun correctly, we need to give bun the '-b' flag, which is '--bun' (I love it when cities have streets that are the name of the city) and that will intercept any calls to node and run them in bun:

bun -b run eleventy --serve

This will serve at https://0.0.0.0:8080, but unless you are an overachiever, should give simply a 404 since we have no files.

Eleventy Basics

Okay, so by default 11ty will do it's 11ty thing, you can create pages like index.md, and save it. That will automatigically become your index.html. You can also give it a "layout", which will become the wrapper around your page.

index.md

---
title: "Yet Another SaaS"
layout: layout.html
---
# {{ title }}

layout.html

<html>
<body>
  <main> {{ content }} </main>
</body>
</html>

".html" pages are actually, by default, liquid templates, which works but also you can change that.

Project Layout

Okay, so you do you, obviously, but here's a project layout that works for me:

_site            -- final built static content directory
pages            -- where we put our content
  _media         -- where we put our images/styles/etc
  _layouts       -- where we put our layouts
     pages.html  -- our default layout
  index.md       -- our index page
components       -- where we will put our typescript / web-components
  index.ts       -- the entrypoint for building
.eleventy.js     -- our 11ty settings
build.js         -- our typescript / web-components build script
package.json     -- our package settings
tsconfig.json    -- our typescript settings

Eleventy Config

Now, 11ty has an evolving system for configs, but the latest and greatest is to put a .eleventy.js in your project root. You can have multiple, and use --config=<filename> to chose, but that's the default one.

Within it, we export a default function that will be called when eleventy starts up:

// Build script for our components
import { build } from "./build.js";

// 11ty runs this function to configure itself
export default function(eleventyConfig) {
    // Before 11ty runs, we will run our build script
    eleventyConfig.on("eleventy.before", async ({ directories, runMode, outputMode }) => {
        // Build our components and put them in the js directory
        build('_site/js').catch((error) => {
            console.error("Error during build:", error);
        });
    });

    // Our content is in the `pages` folder, this is our base
    eleventyConfig.setInputDirectory("pages");

    // Copy files from the `pages/_media` folder and put them in
    // `_site/media` in our final build
    eleventyConfig.addPassthroughCopy({"_media": "media");

    // Our layouts are in "pages/_layouts"
    eleventyConfig.setIncludesDirectory('_layouts');

    // Make a "layout.html" the default layout
    eleventyConfig.addGlobalData("layout", "layout.html");

    // If we make a change to our components, reload
    eleventyConfig.addWatchTarget("./components/");

    // This is using the default, but you can change this here
    eleventyConfig.setOutputDirectory("_site");

    // Short codes are little scripts you can embed, this is for 
    // the copyright in your footer, which legally has to be
    // current, fyi
    eleventyConfig.addShortcode("year", () => `${new 
        Date().getFullYear()}`
    );
}

Build

Alright, so now eleventy will run our build script every time it runs, which includes when you make a file change and it automatically recompiles.

Here is the build script I use, it makes a nice little table to explain what was done. We also set it to import css/html as files, split our files into shared chunks, minify the output, and add external source maps. We also set it to name our files basically like how they are in our components directory with the same relative path.

import { filesize } from "filesize";

export const buildConfig = {
    watchDirs: ['./components'],
    entrypoints: ['./components/index.ts'],
    naming: {
      asset: "[dir]/[name].[ext]"
    },
    publicPath: "/",
  }

/// Building
export async function build(outdir) {
    try {
      Bun.build;
    } catch (e) {
      console.error("Bun is not available. Please install Bun to use this feature. You might need to add -b after bun to make it intercept node.");
      return;
    }

    let result = await Bun.build({
      entrypoints: buildConfig.entrypoints,
      outdir: outdir,
      publicPath: buildConfig.publicPath,
      naming: buildConfig.naming,
      loader: {
        ".css": "file",
        ".html": "file",
      },
      splitting: true,
      minify: true,
      sourcemap: 'external'
    })

    if (!result.success) {
      result.logs.forEach(log => console.error(log, '\n\n----\n'));
      console.log("\n❌ ", new Date(), "\n");
      return;
    }

    let items = result.outputs.filter(art => !art.path.endsWith('.map')).map(art => ({
      'name': '📗 .' + art.path,
      'loader': art.loader,
      'size': "\x1b[33m" + filesize(art.size) + "\x1b[0m"
    }));

    console.table(items);
    console.log("\n✔️ ", new Date(), extraStatus, "\n");
  }

More Example Stuff

Entrypoint `components/index.ts`

import './menu-toggle.ts';
// Anything else you want to build

Menu Toggle `components/menu-toggle.ts`

import {LitElement, css, html, svg} from 'lit';
import {customElement, property} from 'lit/decorators.js';

let hamburgerIcon = svg`
<svg width="19" height="13" viewBox="0 0 19 13" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path d="M0.342712 0.743286H18.3427V2.74329H0.342712V0.743286ZM0.342712 5.74329H18.3427V7.74329H0.342712V5.74329ZM0.342712 10.7433H18.3427V12.7433H0.342712V10.7433Z" fill="black"/>
</svg>
`

@customElement('menu-toggle')
export class MenuToggle extends LitElement {
  static styles = css`
    :host {
        border: none;
        background: transparent;
        padding: var(--site-menu-toggle-padding, 0);
        cursor: pointer;
    }
  `;

  connectedCallback(): void {
    super.connectedCallback();
    this.addEventListener('click', () => {
      document.body.classList.toggle('menu-open');
    });
  }

  render() {
    return html`${hamburgerIcon}`;
  }
}

Layout `pages/_layouts/layout.html`

<!DOCTYPE html>

<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <title>{{ title }}</title>

  <script type="module" src="/js/index.js"></script>
  <link rel="stylesheet" href="/media/base.css">
</head>

<body>
    <nav>
      <menu-toggle></menu-toggle>
      <ul class="title">
        <li class="logo">Yet Another SaaS</li>
        <li><a href="/about">About Us</a></li>
      </ul>
    </nav>
    <main>
        {{ content }}
    </main>
    <footer>
        &copy; {{ year }} Extremely SaaS Solutions
    </footer>
  </div>
</body>

Entrypoint `components/app.ts`

You can create many entrypoints (see buildConfig in build.js),
so keep your index/page bundle small. For complex apps make more entry points for the functionality you need.

import './app-harness.ts';
import './data-sources.ts';
import './data-complex-things.ts';
import {thing } from 'weirdLibrary';
thing.configure({'name': 'Project Orpheus'});

Credits

My name is Brantley Harris and I do consulting work, you can find me on LinkedIn for one.

Photo by Anete Lusina via Pexels

What if there was a CLI called "py" that got you working right away?

Brantley Harris — Fri, 06 May 2022 15:21:24 +0000

I'm tired of dealing with runtimes and virtual environments and remembering how to get everything set up for various projects, and I've been programming Python for 20 years now, I don't even understand how novice devs get along these days.

Scaffolding

In learning science, there is an idea of "scaffolding". This is a way of teaching that crosses the gap between providing rails or crutches, which make learners depend on the tools, often unable to move beyond them; and free form, which leaves learners out by themselves, often paralyzed by the possibilities. Scaffolding finds a good center where learners and pros-alike can get their bearings, pick comfortable directions, and feel supported along the way.

Two great ways to perform scaffolding are one, to provide examples, which can be taken wholly at first, and then deviated from; and also through an emphasis on goal-setting, which lets learners see clearly their paths ahead of them.

What does this have to do with a python CLI you might wonder? Well, that's exactly the issue: it doesn't usually. But what if we made a CLI that embraced scaffolding. And so here is my goal, to experiment with a different kind of CLI that works with goals and examples.

Introducing Py

Of course, all of this is ephemeral at this point; I haven't created it yet, but I've begun experimenting and I'd love to know what people think.

Py has two modes of running:

Firstly, a user-friendly CLI to run python programs; setup/install projects, environments, and runtimes; run recipes of all sorts; and generally be a very simple hub of activity for any sort of python-related tasks. But most importunately does this while negotiating virtual environments and runtimes cleanly.

This first mode would certainly step on some toes of some great projects like pyenv and poetry, but would rather use them rather than make them obsolete.

The second mode of running would be if you just typed in "py". This is where the scaffolding comes into play. Instead of seeing a crufty help screen, you would see something of a screen like this:

Thanks to Rich for the wonderful interface API. With Rich, we can now create much more compelling terminal user experiences, which is something I wish to leverage here.

Goals

The goals you first get might be general, they might change based on your usage, or if you are in an existing project. And maybe your school or company could customize these based on common needs. Some initial goals might be:

Initialize a new python project - Create a new project by selecting a runtime environment, e.g. python 3.10.4, creating a virtual environment, and setting up a pyproject.toml with dependencies.

Check out an existing project and prepare to run it - Clone or download an existing project and prepare your environments to run it.

Run the python shell - Run the latest python shell, IDLE, or a notebook.

View and modify your local python environments and installations - See a list of runtime environments, and potentially upgrade or edit them.

And finally Browse other goals and find more created by the community - Which I imagine as a sort of mini-pypi user-submitted catalog of goals and recipes, browsable right here in the CLI. Imagine things like "Start a new data-science project" or even "Begin Sarah's machine learning tutorial #1".

Project

So if this interests you, send me some feedback. I'd love to hear if you like the idea, obstacles, etc. I don't have a lot of free time to work on this, so also if you'd like to jump in, let's go.

Web Components in Style

Brantley Harris — Thu, 04 Mar 2021 22:40:37 +0000

Web Components are really easy to style. You can share styles between them at nearly zero cost, and they can still be styled from outside. They are easy to set up and progressively enhance. There are a throng of frameworks that use Web Components, and if you got into one, you'd know all this naturally. But it's really hard to understand coming from React, Vue, Angular, etc. So let's talk about it.

Baseline

Web Components are probably the most misunderstood technology right now on the web. It's no one's fault really, the tech is in an awkward place. The industry is caught in a React fever dream, and if not React, then surely Vue, and if not Vue then I guess Angular? All of these frameworks work in their own eco-system. And it's really hard to see what's going on outside of them.

Web Components are about bringing everyone out of the closed-systems to share with each other. It's really easy to make your own walled-garden in tech, and in fact, once you've created it, you have incentives to keep it going. It's a whole other magnitude more difficult to do the work to create standards that everyone can agree on and that build interoperability.

So let's go into what Web Components literally are. I'm obliged to go deep because of the misconceptions out there. There are three main browser features collectively called "Web Components":

Custom Elements

Being able to make your own elements, your own buttons, your own inputs whatever. The implementation is stupidly simple. You just create a new class extending HTMLElement, and then you register the name.

class MyButton extends HTMLElement {
   connectedCallback() {
       super.connectedCallback();
       console.debug("I just appeared on the page!");
   }
}

customElements.register('my-button', MyButton);

Et voila you can use <my-button> anywhere in your HTML. Cool. BTW, you can use it in React and Vue also. It just works. Yes, we have to run JavaScript, but it's easy for this to be progressively enhanced because the browser treats it like a DIV until the javascript is loaded. You can still style it from the outside.

This implementation of components is about the most straightforward, simple thing you could think of. It's wicked fast because it's using the browser's native object system already, and it's completely full-featured. Also, when you inspect it in the browser, you see it, not some weird <div class="rg84823">, not some huge pile of indecipherable elements. Just <my-button>.

HTML Templates

HTML Templates is a way to define fragments of HTML in the DOM without them having to actually run on the page. This lets you do declarative things without having to use JavaScript.

Shadow DOM

The Shadow DOM is a way of encapsulating and hiding chunks of HTML. Even though <my-button> looks like a single element, it can have lots of sub-elements in its Shadow DOM. Just like the <select> element has its own inaccessible sub-elements like the dropdown arrow, your Custom Element can have its own little world.

Yeah, it's kind of a mind-fudge. Because you're very used to the DOM tree as being, well a tree. Shadow DOM turns it into a hyper-tree. The nodes can have their own sub-trees off the main tree. That has a cost, mentally. And, honestly, any good developer will naturally want to turn off their brain here because the complexity doesn't seem to have an immediate payoff. But rather than giving up on the concept of Web Components entirely, let's first remember that we don't have to use Shadow DOM to use Custom Elements, and secondly, maybe we can keep trekking on over the conceptual hill, and see what's on the other side.

One of the first things you'll find is that it lets you control how CSS affects the inner-workings of your component. This allows you to shield it from the mess above. Specifically, components become a boundary of the cascade, or in other words, the CSS for your component becomes scoped to it.

There are multiple ways to pierce in and control the style within a component. The easiest, when you are writing the component is to have shared styles. This is a set of CSS styles that components all rely on, a style library. The browser caches it, but gives it to each component. In LitElement you'd do something like:

const buttonStyles = css`
  .icon { width: 32px; vertical-align: middle }
`;

class MyButton extends LitElement {
  static styles = [buttonStyles, myStyles];
}

class YourButton extends LitElement {
  static styles = [buttonStyles, yourStyles];
}

MyButton and YourButton will both use buttonStyles, and whatever else they want, without being changed by the CSS coming from above them.

Another is CSS variables, which if you aren't using, you really should. Components get the CSS variables from above them in the tree. It's common to define and publish with your component variables they support like --my-button-color. It becomes simple to change it from above.

We've also got CSS Parts, which lets the component author define pieces to alter.

And finally, since it's a simple JavaScript class, you can extend whatever element you want and hand it new styles.

With these systems, you'll find CSS to be much, much easier to manage. You are naturally pushed towards styling components separately, vs layout, utility, page-elements, etc. You'll find you aren't nesting nearly as much. And generally, you'll find it much easier to organize your styles. I don't even use sass/scss anymore, because I just don't need it.

Frameworks

Let's talk about the really big misconception. People seem to think Web Components are a competitor to frameworks like React, Vue, Angular, etc. NO! Web Components build a path for these frameworks to provide components for you. Ideally, as an end developer, you would never have to worry about Custom Elements or ShadowDOM except to understand some of the details of styling and encapsulation.

A lot of frameworks are doing this, but not the popular big three, who each have a vested interest in keeping themselves closed off. Check out the many ways to make a webcomponent, all of these frameworks have different strategies and systems, but all of them can be used anywhere, not only in their own garden.

Yes, you can use Web Components in a zero-dependency way, and that's a great option for things like date pickers or very specific one-offs. But it's not the main way you're supposed to consume or even create Web Components. It's just one of many options in an ever-expanding, open system.

Please ask me anything, I'll do my best to help: @deadwisdom

Firestore: What You Should Know

Brantley Harris — Tue, 19 Jan 2021 22:54:33 +0000

Here are my notes on Firestore, and what I wish I knew. This is a rundown, so I've put bits in bold so you can scan.

The Basics

Firebase is one of the most popular "backendless" services. The whole idea is: let's provide everything we need for our applications as direct services that make setting up a backend server redundant. Firestore continues this: let's just connect right to our database from the client. The client here is our website, or a mobile app, a desktop client, whatever.

Firestore is a document store database, which means everything is an amorphous document that you set values on. It is schemaless, meaning each document can have whatever fields you want on it– you aren't setting up columns or properties ahead of time.

Every document is in a collection, kind of like a table, but you can think of it as a directory with the documents as files. In fact, they are named exactly like directory paths /collection-name/document-id, and can keep going: you can have sub-collections like /collection-name/document-id/subcollection-name/subdocument-id. In truth, there is absolutely no relation between the sub-document and the document, deleting the document won't even delete the sub-document. It merely serves as a way to organize.

Again, you connect directly to Firestore from the client / front end. You can update the value of a document, you can read a document, and you can query for multiple documents in a collection. Also, you can subscribe to a document, collection, or collection query, and get real-time updates in the form of "snapshots".

Queries are really simple. We're not doing SQL queries here, just things like "is this field equal to this value" and "is this field bigger than this value". You can combine multiple query statements, but they require creating special indexes. Fortunately, when you attempt to use an index that doesn't exist, the library is smart enough to throw an error and give you an exact link to click on to create the query index. But probably 80% of the time, when I make an index, it turns out I don't actually need it. If you're making a lot of indexes in Firestore, it's a red flag that you're laying out your data wrong.

You might be thinking: if it connects directly and we read and write directly, how do we keep those reads and writes secure? That's done with a magical system called Firebase "Rules". You set up rules using a special domain-specific language that sort of resembles javascript. The rules dictate what requests can write and read to documents. In the rule statement you can reference the incoming request, the user, and the requested document.

Generally, there is no processing on writes and reads, so whatever the client writes goes directly into the database. Whatever is in the database, the client reads. However, there is a way to trigger cloud functions when a document is created or written. This lets you simulate processing but, importantly it is after the fact, so there's a quasi-state between writing and processing where things can be out of whack. This task gets scheduled somewhere by Firebase, in my tests it occurred a few seconds after the data was saved.

And that's basically it. Firestore is purposefully super simple. If you need more, you're using the wrong tool.

Where it shines

Don't overthink Firestore. It exists in a larger offering called "Google Cloud Platform". It has a lot of friends to pick up its slack, and it's not trying too hard, so you shouldn't either.

It's one of the fastest ways I know of going from zero to a full "backend" solution. It's amazing for prototyping, amazing for simple applications, and great as a front for a larger system, as a sort of caching layer. It's also pretty cheap, given the alternatives. Just make sure you aren't doing a lot of writes.

Connecting directly from the client is as easy as you'd think it should be. It feels like cheating, and it's worth the price of admission. Although the documentation can be pretty obtuse, once you figure out that you're mostly basing everything off of a document reference: firestore.collection('collection-name').doc('doc-id'), you begin to fly. And once you figure out snapshots, you're golden.

It's fast. Special caching and indexing make it feel like real-time, especially when you subscribe to changes, they seem to come instantly.

It has a live interface to view and edit the data. It's amazing for prototyping because you can see real-time changes. If your client is subscribing to the data, you can make the change in the interface and see it live. Absolute filth for live demos to upper management. "Oh, you want to change this name? Already done."

Another "feature" is that it forces you to simplify your data organization. This can be bad and good, but I've found that it gives you all you need for most simple applications. So if you're struggling with data layout, it's a red flag that you either need a separate solution for that feature, or you're thinking about it all wrong.

Where it's dull

The simplicity will quickly box you in, though. This isn't a relational database. It's a specialized non-relational database– you will have to learn a different way of thinking that matches it, specifically.

With no real way of doing relations, you're going to make a lot of reads and round-trips. This is by design, and probably fine, but we're not able to do anything fancy with joins or graph queries. This also means being very, very aware of how you set up your data. In many places, you will be duplicating data and will have to manage to update this duplicated data in a system that, frankly, doesn't want to help you.

But easily the biggest problem with Firestore is the rules system. This system is nasty. First of all, let's have a new language for you to learn that is not well documented and feels just close enough to javascript to make you feel like it should be, but no. Sorry, not sorry. It would be bad enough to leave it there, but there's almost no feedback. Your requests either work or don't. Debugging is practically impossible. They allow you to "test" the queries from their front-end, but it's buggy, and I don't recommend it. The biggest issue here is that you are simply left wondering about your security. Not a good place to be.

Another big issue is that there is no schema, at all. You cannot be sure of data consistency. That means you have to set up defenses in your client code when you read and/or setup post-processing cloud function triggers to ensure sanity. A lot of object.title || '' or use a schema validation library. It is really pushing the schema work to the client. This is a pretty awful indictment when you compare it to services offering things like GraphQL that handle this inherently.

And given that a nefarious user could, with some console scripting, update whatever they have access to with whatever data they wanted, you can't rely on any of it. Again, security becomes a big question.

Finally: pricing is weird. On the surface, Firestore has a straightforward pricing model: you pay a certain amount per read and per write. But things can get problematic. It's hard to figure out what special functions like subscribing to collection queries do, and it's hard to know what cloud functions might trigger either a read or a write. At best, you'll be able to estimate based on projected users and activity. At worst, like most cloud services, you'll have to do some linear regressions after you've run it for a while to see how much your app will cost when it scales. But, hey, this is why we have CFOs, right?

Strategies

Here are some strategies for success with Firestore:

Employ pricing limits.

First thing, first thing: Set up pricing limits. Make something reasonable. Da pricing calculator don't care that your script went into an infinite loop, your credit card is still on the line. Big daddy Google ain't messing around. Though to be fair, I've heard of people messing this up and Google has been lenient. Still, put the limit in.

Keep public and private data separated.

As a general rule, separating public and private data is great. In Firebase it's even more greaterific. This lets you write public rules that are super simple, and focused, well crafted, private rules. It's also a good line on which to duplicate data, e.g. have private user profiles with all their information, and public profiles, in a separate collection, with only a subset of fields.

Consider moving writes to a separate service.

I abandoned making writes at all directly from the client. Instead, I set up an App Engine REST API to do this. You could easily do serverless functions, an API Gateway with Cloud Run, whatever. Yes, this throws out the idea of fully backendless as you're literally making a backend. But I find it much, much easier to ensure security and data schema in custom functions. Best to do this after the prototyping phase. Get the functionality down, then move on to data consistency and security — batten down the hatches, so to speak.

An alternative to this is to have special collections set up for writes, and then have serverless functions trigger and process them. This is a fine system, but you're essentially just doing the same thing as above.

Consider using Firestore to augment your existing services.

If you start thinking of Firestore as essentially a specialized, fast, subscribable read-only data source, it's easy to imagine gradually putting it in between your existing services and clients. Gradually put data into it and move clients to read from it. Slowly your backend becomes write-only, decreasing complexity and cost.

Test your security rules with a deployment script.

The rules are such little jerks, you need to be sure they are working. Don't leave it to the interface, it's just waiting to fail.

On server-side, use transactions.

The client bends backward to make every operation idempotent, so you can't get the database in a weird state. But on the server, you need to use transactions to make sure you don't create a weird state of the database. Also, it can save on pricing as a single transaction sort of bundles costs up. But, uh, don't quote me on that last part, it's not well defined.

Watch the videos.

Google has done an impressive job creating videos to help you understand how to organize your data. I've dealt with a lot of document store and non-relational databases and they still very much helped me think in Firestore.

Conclusion

Welp, that's all I got. Overall, I really like Firestore. It lets me get building fast. But it's a special thing, and it's best to understand it before you jump in.

It's well-executed; most of the issues are from trade-offs that I can't fault them on. Although the rules system really needs a lot of work.

Going forward, the horizon looks good for some other backendless technologies. AWS is coming around the corner with Amplify, and any GraphQL service is going to have a huge benefit here since we're already giving up REST. But it remains to be seen if the simplicity, cost, and speed of Firebase will shine through.

Cover image: Photo by burak kostak from Pexels

Meet me on twitter: @deadwisdom

I'm available for consulting services on architecture and web development.

Embracing JAMStack with Python: Generating a Static Website with Flask and Deploying to Netlify

Brantley Harris — Mon, 26 Oct 2020 22:14:43 +0000

The Big Idea

JAMStack completely changes how individuals and entire organizations alike iterate on a web app. It decouples your frontend and backend workflow, so you can focus on speed to your end-user, worry less about how it's served, keep separate iteration cycles, and best of all, enable easy feature branching.

I'll show, step by step, how you can use the powerful, sophisticated tools of Flask and Python without bothering with specialized static-site generators.

Important Links:

Before We Begin

Black lives matter.
We need diversity and women in tech.
Trans rights are human rights.
Reminder that we are quickly destroying the earth.

All I ask for this content is that you are mindful about applying technology. It is not ours to fix everything, nor must we take on every cause as an individual, but we are the modern day wizards and we must remember that our actions matter.

And finally, if you struggle with this tutorial or the concepts herein, know that we all struggle. Tech is a deep, long journey, we all (at every level) get frustrated and doubt ourselves constantly. The best way is to keep going, ignore the haters, and reach out to others for help.

JAMStack

JAMStack is a terrible name. It sounds like a local event for jarring preserves. But it's a great concept: Focus on a separation of Javascript, API, and Markup.

The frontend and the backend decouple, with the Markup becoming a static platform which the JavaScript builds on. Dynamic data is delivered from the API to the client via JavaScript. You can still do some dynamic Markup generation on the server, but that is now an edge-case and is done through the API.

Since our client assets are now all static, it lends itself to serving directly from a Content Delivery Network. This ensures your site is delivered as fast and efficiently as possible. This is where Netlify comes in. It makes deploying from your repository to a website super slick. And a real fire and forget solution. More on that later.

Keeping your frontend and backend decoupled is an amazing thing once you set it up. It's easily worth the price of admission. Backend often requires a lot of tests, analysis, optimization, and generally way longer iteration cycles than frontend, which often wants to make changes and iterate by the minute with immediate results. When you are changing the border radius of a button, you'd rather not wait for a backend build that's often compiling a docker image, running tests, deploying, etc...

Testing frontend feature branches, without needing to create a whole new backend environment is game changing. It revolutionizes everyone's experience, from the developer all the way to business stakeholders. Netlify gives you a unique URL for every deploy meaning you can try out new features, review old deploys, and quickly test for production readiness.

Lastly, keeping things decoupled also makes it easy to slot in serverless endpoints or backendless options like Firebase or AWS Amplify.

Modularity... Composition... Wow! Who knew it was so great?

When not to use JAMStack

JAMStack has one place where classic markup generation is better, and that's when you need to generate a lot of dynamic content, i.e. Markup that changes depending on the user viewing or some other trip to the database.

With something like a stock-ticker, that's still doable, because it comes from an API. But for something like a CMS, where the content often changes via a database, then classic Jinja rendering is still where it's at.

Still, a lot of the promises of database-driven CMSs have yet to materialize, and people are increasingly finding it easier to simply change the content in the source code and redeploy, especially when it's done automatically and quickly.

Further it's simple to put some content generation behind an API endpoint, if you don't need a lot of that.

Generating Static Websites with Flask

This technique allows you to generate a static website in much the same way you'd make a classic Flask app. And this example parallels examples shown by generators like 11ty, Gatsby, and Jekyll, but in my opinion is better because it allows us to use Python, Flask and all the great tools that come with.

Some benefits of using Flask instead of other static site generators:

During development, we just get to use a Flask server, there's no compile step.
No scaling problems when you get to lots of pages.
We can use the same tools and mindset we use to build standard servers and API servers.
No new domain-specific languages to do things like for-loops, and shoe-horn database querying into Markdown.
We can still integrate with any database Flask can, any remote api, and generally do anything Python can do, which is a lot.

Now, we could easily use Django, FastAPI, Starlette, or any other framework for this, but Flask has two extensions that make the process really easy: Frozen-Flask and Flask-FlatPages.

Tutorial

We're going to break our endeavour into these goals:

Setup / Install Our Dependencies and Setup Github
Create Our Flask App
Freeze It
Add Pages / Content with Markdown
Add JavaScript and Connect to an API

Then afterwards, I'll show you how to deploy with Netilify.

Now to it!

Goal 1: Setup / Install our Dependencies and Setup Github

First we will setup our Git repository. Using Github here, cause it's a big old standard.

Let's create a new repository. I named it "flask-static-tutorial". I checked "Initialize this repository with a README", added a gitignore (Python), and a license (MIT). You do you.

Once it's made, clone the repository locally.

I'm going to assume you have Python 3.6+ on your system. I like using Pyenv which manages the installation and selection of multiple Python versions. A great tutorial is available here.

We're also going to use Pipenv for this tutorial. It will manage our Python dependencies. I'm using it mostly because Netlify supports Pipfile directly. So go ahead and install that.

Now that we have those installed, we'll install our requirements:

$ pipenv --python 3.7 install flask frozen-flask flask-flatpages

Pipenv nicely creates a virtual environment for us, a Pipfile , and Pipfile.Lock , and installs our packages. We also tell it to use 3.7, because it is the default version for Netlify.

Now let's commit it, and move on:

$ git add .
$ git commit -m 'project setup'
$ git push

Goal 2: Create Our Flask App

This part is basically just following the flask tutorial. The only little change is that we're using Pipenv.

Let's make app.py :

from flask import Flask

# Create our app object, use this page as our settings (will pick up DEBUG)
app = Flask(__name__)

# For settings, we just use this file itself, very easy to configure
app.config.from_object(__name__)

# We want Flask to allow no slashes after paths, because they get turned into flat files
app.url_map.strict_slashes = False

# Create a route to our index page at the root url, return a simple greeting
@app.route("/")
def index():
    return "Hello, Flask"

Basic Flask stuff. Of course, you can do anything here, even talk to a database, but you don't want to add anything that is based on user interaction or state. Everything should respond to a simple GET request. Accessing the request global is a red-flag here. It's static content after all.

Now we run our server, and this is where using Flask is great, because we can develop our site as we go, without having to rebuild or run some command to do so after changes. We just pretend we are making any old Flask site. And really, we are.

First setup our environment, then run it with Pipenv.

$ export FLASK_DEBUG=True
$ export FLASK_APP=app.py
$ pipenv run flask run

We tell pipenv to run flask and flask to run . Hope you follow. Alternatively you can create a pipenv script. But that's your bizzniss.

Now we can open our browser to http://127.0.0.1:5000/ and be greeted.

Great work! But don't get arrogant, we have more to do.

Goal 3: Freeze It

Did you know you can make frozen ice cubes in the hot desert like the Persians thousands of years ago? Did you also know you can make a frozen Flask website in your computer? Even in the desert.

Earlier we installed Frozen-Flask. To get started, all we need is another file freeze.py :

from flask_frozen import Freezer
from app import app

freezer = Freezer(app)

if __name__ == '__main__':
    freezer.freeze()

And then run it:

$ pipenv run python freeze.py

You'll see that it makes a directory build and the file index.html . Open it up and you'll see exactly what your browser gets when it goes to 'http://127.0.0.1:5000/' when our flask process is running.

Frozen-Flask is really simple. It just runs your app, gets every root endpoint (ones without a path variable), copies the Markup, and saves it to a corresponding file. To find other pages, it tracks every response from url_for() and adds them to its queue.

To find pages that are outside of your root tree, read more about how it finds urls here.

We are really close. Now we just need, you know content.

Goal 4: Add Pages / Content with Markdown

It is time. Time for you to look into your cold, frozen heart to see what kind of website you want to make. For me, it's simple: A site for a pet detective agency. But you do you.

One of the things 11ty, Jekyll and basically every ~~blog creation framework~~ static site generator does is easily let you create pages with markdown. We're going to do the same.

This is where Flask-FlatPages comes in. It lets us create pages in any format we want, process them, and then deliver them as HTML.

App.py Changes

Let's update our app.py :

from flask import Flask, render_template
from flask_flatpages import FlatPages

# Tell Flatpages to auto reload when a page is changed, and look for .md files
FLATPAGES_AUTO_RELOAD = True
FLATPAGES_EXTENSION = '.md'

# Create our app object, use this page as our settings (will pick up DEBUG)
app = Flask(__name__)

# For settings, we just use this file itself, very easy to configure
app.config.from_object(__name__)

# We want Flask to allow no slashes after paths, because they get turned into flat files
app.url_map.strict_slashes = False

# Create an instance of our extension
pages = FlatPages(app)

# Route to FlatPages at our root, and route any path that ends in ".html"
@app.route("/")
@app.route("/<path:path>.html")
def page(path=None):
    # Look for the page with FlatPages, or find "index" if we have no path
    page = pages.get_or_404(path or 'index')

    # Render the template "page.html" with our page and title
    return render_template("page.html", page=page, title=page.meta['title'])

Note, that we could make other routes to do whatever we want, but currently we just have one that works with Flask-FlatPages.

Markdown Pages

We've got Flask-FlatPages looking for pages in a pages directory as default. So let's create some pages. You can click on each one to copy them or make your own content. Any file you add here that has an '.md' extension will turn into a page, provided you also link to it in another page with url_for() .

browse files

pages/
  content.md
  index.md
  team.md

At the top of each page, you'll notice its "meta" section, which is YAML and looks something like this:

Title: Rare Pup Detective Agency
Description: We sniff out the clues.

Within the pages, you might notice some HTML. Don't forget, markdown lets us embed HTML! Use it.

Jinja Template

Now let's create our Jinja template, that serves as the wrapper for our pages templates/page.html :

<!doctype html>
<html>
  <head>

    <meta charset="utf-8">
    <title>{{ title }}</title>
    <link rel="stylesheet" href="/static/base.css">
    <meta name="viewport" content="width=device-width, initial-scale=1">

  </head>
  <body>

    <header>
      <nav>
        <a href="/" class="logo" aria-hidden="true"></a>
        <a href="/" {% if page.path == "index" %}active{% endif %}>Home</a>
        <a href="{{ url_for('page', path='team') }}" {% if page.path == "team" %}active{% endif %}>Team</a>
        <a href="{{ url_for('page', path='contact') }}" {% if page.path == "contact" %}active{% endif %}>Contact</a>
      </nav>
    </header>

    <main>
      <article>
      {% block content %}
          <h1>{{ page.meta.description }}</h1>
          {{ page.html|safe }}
      {% endblock content %}
      </article>
    </main>

  </body>
</html>

Mostly we have a basic page here. There are a few things to note:

<a href="{{ url_for('page', path='team') }}" {% if page.path == "team" %}active{% endif %}>Team</a>

We use flask's url_for() method to get the final url of our "team" page, also we have add an 'active' attribute to the <a> tag when we are on that page, for styling purposes.

Also in our content block, we do:

<h1>{{ page.meta.description }}</h1>
{{ page.html|safe }}

We add an <h1> with the description from the page meta. And finally, we grab the page.html and run a safe filter on it because it includes HTML that we want to render unescaped.

Static assets

Finally, any static assets like images, css, or js that we link to need to go into /static . Frozen-Flask will automatically grab them if they are used. For this example, I'm only using a few, but you might many more:

browse files

static/
  images/
    logo.png
  base.css

Develop & Freeze

Alright, alright. That was a lot. Let's check out how we did, make changes, etc. During development we simply use the flask server, and it will auto-reload. We can pretend it's just a normal flask site:

$ pipenv run flask run

When we're done, we can test the freeze, it should put all our pages and assets into the build directory:

build/
  static/
    images/
      logo.png
    base.css
  content.html
  index.html
  team.html

Goal 5: Add JavaScript and Connect to an API

As a final step, we'll add some functionality to call an external API. In a real world scenario, you'd create the API, and host it yourself, or use a serverless option. Here we are just calling out to the wonderful service Dog CEO, Dog Api.

We'll add the script linked below:

static/js/dogs.js

It defines a custom element "dog-picture" which we've already spread through the site. If the user didn't have JavaScript, the browser just ignores all of the <dog-picture> elements. Once this script is loaded, they spring to life. Custom Elements. Neat.

We link it in templates/page.html with a simple:

<script type="module" src="/static/js/dogs.js"></script>

When we freeze, you'll see, it gets added to build/ . If we need to compile our JavaScript with rollup, parcel, or webpack it's simple enough to run that before we do freeze.

Only one more thing, let's deploy the thing...

Netlify

Once we have the static content, we need somewhere to put it. Since it's all static, we can basically put it anywhere: behind nginx, on an S3, whatever. But it's best to put it behind a Content Delivery Network, where your data will live on multiple servers around the globe that are specially designed to cache and serve content quickly. The only trouble is managing that deployment process.

And that's why we use Netlify. They have really figured out the process. Basically, it hooks into your repo, listens for updates, then runs a build command, puts it on a CDN, and routes to it.

Every build gets served by a unique url. This is key. It means we can create feature branches of our frontend without a thought.

And, nicely, it's free for small projects like this.

Create the Site

First we make our account: https://app.netlify.com/

Next we make our first site: https://app.netlify.com/start

Connect it to Github, and select your repository. For the build options, tell it the command "python freeze.py", and our build directory is "build".

Note: Netlify's basic build environment will look at our Pipfile to determine the python version, and requirements. Since it configures the base python environment we don't have to actually run it with pipenv.

Now press "Deploy Site". You can watch the progress by clicking on the deploy item, it will give you a full output and status. If you get a big old "Deploy Failed", go into the deploy and scroll down in the page to see why.

When it succeeds you will see "Published" at at the top of the 'Deploys' screen you'll see a link like "https://infallible-beaver-cf7576.netlify.app". Click on it to view it.

As awesome as "infallible-beaver-cf7576" is, you can rename your site by going to Settings > Domain Management. You can also bring in a custom domain.

Now every time you commit, it will go live. You can also make it only publish a specific branch, setup triggers, etc. There's a million different options, so play around.

Some Netlify Extras

Netlify has a decent redirect feature, allowing you to remap a request like /api/* to wherever you want, including a custom API endpoint. Read about Redirects and Rewrites.

Our contact.md page has a form that doesn't go anywhere, but it has a data-netlify="true" tag, which is automatically processed by Netlify. It gather all submissions, and you can read them in the site admin. Also, you can set up notifications for them. Read about Netlify Forms.

Light authentication can be done pretty simply with Netlify's Authentication System.

Connecting a Bundler

The great part about this approach is we don't need a build step, but sometimes you need JavaScript to bundle, by running Rollup, Webpack, Parcel, etc. There are two places you need this. One is during development when you make a change, and the other is during your publish step.

Bundle For Publishing

One is to change your Netlify build command to something like this:

$ npm run build && python freeze.py

Have your package manager build right into your static folder like /static/build , and then have your Flask template pickup the JavaScript file there. Flask-Freeze will then move it to the /build directory for Netlify to use.

Bundle For Development

I'll encourage you to use a resource like open-wc.org or Snowpack so that you don't have to build anything for development. ES6 being what it is, you don't need to anymore.

That said, sometimes we don't get to choose. In that case, we need to run our flask server and the bundler in watch mode.

The simplest way is to just run two terminals:

    Terminal 1: $ pipenv run flask run

    Terminal 2: $ npm run webpack --watch

Bundle with Webpack

If you're using Webpack, Andrew Montalenti (@amontalenti) wrote a bridge between Webpack and Flask that leans on Flask-Static, check it out at his gist:

https://gist.github.com/amontalenti/ffeca0dce10f29d42a82e80773804355

Final Thoughts

I hope I've shown how JAMStack can be an amazing way to develop, and how we don't need to leave all the glorious wealth we have from Python to get there. From here you can look into Zappa for serverless endpoints, deploying containers to AWS Fargate, or using good old Google App Engine, for your API needs. I still prefer the latter for setting up quick Python APIs.

Some Tips

Do remember that the JavaScript part of JAMStack should be your last resort. Too much these days developers are pushing giant React bundles into clients, and our poor devices just can't handle them.

Progressive enhancement is still, after all these years, the goal. Think as close to Markup as possible, and then move outward as needed. So much of our time is spent implementing doomed features that are overly complex and JavaScript nightmares. Meanwhile what the user really needs is just some web form. JAMStack can help us here, but it can also lead us to Single Page React App nightmares.

A great way to organize your apps is authenticated vs unauthenticated. Think of Markup as always anonymous, and then JavaScript adds functionality when they login. And think of your APIs as private and public endpoints. That helps you a lot when you get to caching.

Alternatives to Netlify

Netlify isn't really doing anything special here. There's nothing that necessitates it, and the adventurous might want to make their own deployment system. Static assets mean that you can put the hash in a filename and cache them indefinitely. Before Netlify I had a system that chunked my large JS bundles and placed them on S3 named by hash. When I made changes, clients only had to download the updated chunk files.

You can also publish right to GitHub Pages.

Host it on an NGinx server, and put CloudFare in front of it.

Alternatives to Flask

Django has Django-Freeze to create static content in much the same way you'd do it here.

Pelican is a python based static site generator.

Use 11ty if you want a full-featured specialized static generator written in Javascript.

Communicate With Me!

If you spot any problems, have any questions, or want to request further tutorials create an issue in the project repo: https://github.com/DeadWisdom/flask-static-tutorial/issues

Or hit me up on twitter: @deadwisdom

Also I am available as a consultant, primarily in helping organizations streamline their innovation and development cycles, especially where product, design, and development need to communicate.

Thanks to those that helped me writing this, including @matteasterday, @DanielReesLewis, and @amontalenti.

And thank you!