When people say "open source is a gift," they usually mean the final product: a library or application given freely to society, with no expectation of reciprocity.

I agree with this take on the phrase. One of the downsides of releasing software under an open source license is the expectations it can set up for some subset of end users: since they got it for free, they assume that support, bug fixes, and feature requests are also owed to them for free. So I like the phrase as a way to push back on those expectations.

However, I want to talk about a slightly different interpretation of the phrase.

The Gift of Development in the Open

Astral is a venture-capital backed company that has written a handful of tools for the Python ecosystem: ruff for extremely fast formatting and linting, uv for packaging and dependency management, ty for type checking, and most recently a package manager, pyx.

All of these (except pyx) are MIT licensed and developed completely in the open.

Astral's tools have generally been well received. In my experience, this comes down to taste in API design. Their tools just feel good to use. Still, people have (understandably) raised concerns about the Python ecosystem coalescing around tooling from a VC-backed company, given the general likelihood of enshittification that VC money tends to lead to.

I'm not here to talk about that entirely valid concern. Instead, I want to talk about what a gift it is that the development of these well-designed, well-engineered tools is happening entirely in public. Seriously: go look at the pull requests in any of their repos and you will see extremely smart programmers tackling thorny issues in real time. The fact that anyone can learn from that is itself a gift.

The Gift of Learning in Public

For about a year now, I've been working on a language server for Django as a side project. I chose to write it in Rust, despite never having used a low-level, statically typed systems language before.

From one perspective, this was a mistake. If I were being paid to deliver it for a company, I'd agree. The cross-language barrier adds real friction (even with tools like maturin and PyO3 smoothing the way). A well-supported language server library already exists in Python, and there's even a Django language server written in Python that is far more full-featured than mine. Had I chosen Python, I'd no doubt be further along and closer to matching those features.

But I'm not getting paid for this. This is a personal project.

So I chose Rust for entirely personal reasons: I wanted to learn it in a meaningful, non-toy context. Rust offers performance essentially for free, and its type system and borrow checker, while painful at first, force you to think differently about correctness and memory safety. After years of wrestling with type checking in Python projects using mypy and pyright, working in a language with actual types has been refreshing.

And honestly: it was fun.

This is where the "gift" of open source really hit me. Astral's codebases and PRs have become my textbook. Their discussions around error handling, incremental parsing, cross-platform quirks, performance trade-offs - all of it has been incredibly useful while I've been learning Rust.

And beyond reading, I borrowed ideas and techniques directly. The architecture of my Django language server is heavily influenced by techniques I first saw in their repos: using salsa for incremental cached computations, structuring a Rust project into multiple crates within a workspace, and even approaches for integrating cleanly with Python. Astral, in turn, built on ideas from other open projects like rust-analyzer and Cargo itself.

That chain of influence is what makes open source special.

The Gift Passed Along

So yeah, the original meaning of "open source is a gift" holds up. But I think there's more to it than the code you uv add or pip install or cargo add. There's the act of doing the work in the open. Bug triages, design debates in GitHub threads, pull requests anyone can read through - it's all basically a free, ongoing seminar in how good software gets made.

Astral, of course, isn't the only one building in the open - they're just the most relevant to my journey this past year. Countless others, from CPython to Django to projects maintained entirely by volunteers, are out there too, all ready for anyone to study.

The software you install is the obvious gift. But I think there's something just as valuable in the process being open too. It gives you permission to watch how good software gets made, borrow what works, and eventually put your own stuff out there for someone else to learn from.

After making the change to the Dockerfile, I went and worked on something else unrelated for a while. When I circled back after some time had passed and the change had left my brain, I built and started the Docker Compose stack for the application using the updated Dockerfile. That's when the application threw the following traceback:

  File "/usr/local/lib/python3.12/site-packages/django/utils/timezone.py", line 52, in get_default_timezone
    return zoneinfo.ZoneInfo(settings.TIME_ZONE)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/zoneinfo/_common.py", line 24, in load_tzdata
    raise ZoneInfoNotFoundError(f"No time zone found with key {key}")
zoneinfo._common.ZoneInfoNotFoundError: 'No time zone found with key America/Chicago'

I thought that was odd since I had never encountered this error before. I've created plenty of timezone related bugs, but the data had always been there for me to screw up. So, what had changed? Where did my timezones go?

An unrelated change?

As part of our common Dockerfile template, we install Playwright for end-to-end testing. It's installed in two stages: one to install the library and all the system dependencies it needs, and another to use that stage to load our application code in development. It looks like this:

# the `py` stage (not shown) installs all of our application's
# Python dependencies
FROM py as playwright
ENV PLAYWRIGHT_BROWSERS_PATH /usr/local/bin/playwright-browsers
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
  --mount=type=cache,target=/var/lib/apt,sharing=locked \
  apt-get update --fix-missing \
  && playwright install --with-deps

FROM playwright as dev
# the `app` stage (not shown) copies all of our application's source code
# into the Docker image
COPY --from=app --link /app /app

While this worked, whenever the cache for the initial playwright build stage was invalidated -- typically by changing something regarding a Python dependency -- you would have to install Playwright, its system dependencies, and the browsers all over again. I started to get very frustrated with this as the build process for Playwright involves installing a ton of system dependencies and the browsers themselves, so it can be quite slow.

As a solution, I decided to leverage the Docker image Microsoft provides at mcr.microsoft.com/playwright/python instead of installing Playwright manually. As a bonus, it got rid of the extra build stage and slimmed our Dockerfile down slightly.

-FROM py as playwright
-ENV PLAYWRIGHT_BROWSERS_PATH /usr/local/bin/playwright-browsers
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
-  --mount=type=cache,target=/var/lib/apt,sharing=locked \
-  apt-get update --fix-missing \
-  && playwright install --with-deps

-FROM playwright as dev
+FROM mcr.microsoft.com/playwright/python:v1.43.0 as dev
+COPY --from=py --link /usr/local /usr/local
 COPY --from=app --link /app /app

playwright==1.43.0

Once I made this change, I went and worked on something else. When I came back, I saw the timezone error at the top of the post and was very confused. Where did the timezone data go? Did I bump the version of Python or Django without realizing it and there was a breaking change there? It was just working this morning, why would it not work now? Nothing has changed, I haven't even touched anything related to timezones!

Connecting the dots

It had been just long enough since making the Playwright change that I had completely forgotten that the call was coming from inside the house.

It took me a while to connect the dots, but after testing a bunch of different things -- downgrading both Python and Django, forcing an upgrade to the latest for both, combing through my Dockerfile line-by-line for any clue -- I managed to track down the source of the bug after looking at the source code for the two Dockerfile images.

Playwright Docker image's base is ubuntu and does not come with tzdata installed in the base image -- which Python's stdlib library zoneinfo relies on for Linux. Previously, I used the official Python Docker image as a base for all build stages, which does install tzdata.

Once I tracked this down, it was a simple fix:

 FROM playwright as dev
 FROM mcr.microsoft.com/playwright/python:v1.43.0 as dev
 COPY --from=py --link /usr/local /usr/local
 COPY --from=app --link /app /app
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+  --mount=type=cache,target=/var/lib/apt,sharing=locked \
+  apt-get update --fix-missing \
+  && apt-get install -y --no-install-recommends \
+  tzdata \
+  && apt-get autoremove -y && apt-get clean -y && rm -rf /var/lib/apt/lists/*

I considered adding the tzdata Python package to my application's dependencies. However, since this Docker build stage is solely used in development and I can rely on the official Python Docker image to include tzdata (for now!), sticking with this approach seemed the best way forward.

This was an interesting bug to track down. Fortunately, the recent switch to the Playwright Docker image was still fresh in my mind. Even though I initially forgot about the change, this proximity in time helped me quickly track down the source of the bug. Had there been a delay of a day or more between introducing the change and the bug happening, I can't help but wonder how much longer it might have taken to solve this puzzle.

So, here's how I like to organize the staticfiles in my Django projects and the reasoning behind the choices I've made.

For context, these days I mostly build Django projects with server-side generated templates. Standard, predictable... the boring choice. Within those Django templates, I use the following:

• Tailwind CSS with its utility CSS classes for styling, using the excellent django-tailwind-cli
• HTMX for getting SPA-like interactions
• Alpine.js for sprinkles of JS interactivity (menu dropdowns, dynamic CSS classes, etc.)

For projects requiring more than what the HTMX and Alpine.js combination offers, I use React and Vite, with django-vite helping integrate them with Django.

Below is the tree view layout of the relevant staticfiles directories in my projects:

project/
├── static/
│   ├── dist/
│   ├── public/
│   └── src/
└── staticfiles/

We'll start with static/public/ and static/src/, as those are where the actual files go.

static/public/ is for assets that require no processing by external tools, such as logo images, vendored CSS/JS assets, and any handwritten vanilla JS files that do not need to be compiled or transpiled.

static/src/ houses assets that require processing to be usable. For instance, my Tailwind CSS styles.css file and any JavaScript/TypeScript files destined for Vite processing are placed here.

After those assets have been run through whatever build pipeline they need, they end up in the static/dist/ folder.

staticfiles/ serves as the collection point for all assets, gathered via the python manage.py collectstatic Django management command during the deployment build process.

Here are the Django settings you need to set in order to use this layout:

# settings.py
# django.contrib.staticfiles
STATIC_ROOT = BASE_DIR / "staticfiles"

STATIC_URL = "/static/"

STATICFILES_DIRS = [
    BASE_DIR / "static" / "dist",
    BASE_DIR / "static" / "public",
]

# django-tailwind-cli
TAILWIND_CLI_DIST_CSS = "css/tailwind.css"

TAILWIND_CLI_SRC_CSS = "static/src/tailwind.css"

# django-vite (optional)
DJANGO_VITE_ASSETS_PATH = BASE_DIR / "static" / "dist"

With this configuration, the collectstatic command will gather all files from STATICFILES_DIRS (static/dist/ and static/public/ here in these example settings), store them in STATIC_ROOT (staticfiles/), and in production serve them under the url prefix STATIC_URL (/static/).

A quirk of the django-tailwind-cli configuration is that the path for the source CSS file originates from the BASE_DIR, whereas the path for the compiled CSS file is relative to the first location listed in STATICFILES_DIRS. That means the TAILWIND_CLI_SRC_CSS setting must include the static/src/ prefix, while TAILWIND_CLI_DIST_CSS should omit the static/dist/ prefix to align with the expectations of the package. Importantly, django-tailwind-cli considers only the first entry in STATICFILES_DIRS for locating compiled assets, which is why static/dist/ is positioned first in the list.

For completeness, below is an example vite.config.ts file for projects that process JavaScript/TypeScript files using Vite.

// vite.config.ts
import { defineConfig } from "vite";
import { resolve } from "path";
import react from "@vitejs/plugin-react";

export default defineConfig({
    // Set the base path for all static assets. Useful for deployment where paths need prefixing.
    base: "/static/",
    build: {
        // Directory for storing build-time assets (empty here to avoid nesting).
        assetsDir: "",
        // Enable the generation of manifest.json for asset management.
        manifest: true,
        // Output directory for built files, resolved to 'static/dist' within the project.
        outDir: resolve(__dirname, "./static/dist"),
        rollupOptions: {
            // Entry point for the app, necessary for multi-page apps to specify multiple entries.
            input: [resolve(__dirname, "./static/src/main.tsx")],
            output: {
                chunkFileNames: undefined,
            },
        },
    },
    plugins: [react()],
    // The directory to serve as the public folder (empty here since we're managing paths manually).
    publicDir: "",
    resolve: {
        // Aliases to simplify imports; '@' points to the 'static/src' directory.
        alias: {
            "@": resolve(__dirname, "./static/src"),
        },
        extensions: [".js", ".jsx", ".ts", ".tsx"],
    },
    // Root directory for source files, set to 'static/src' to centralize code.
    root: resolve(__dirname, "./static/src"),
    server: {
        host: "127.0.0.1",
        port: 5173,
        open: false,
        watch: {
            usePolling: true,
            disableGlobbing: false,
        },
    },
});

Additionally, you should update your project's .gitignore to exclude the static/dist/ and staticfiles/ directories from version control. This prevents unnecessary tracking of compiled and collected assets:

#.gitignore
staticfiles/
static/dist/
# Optionally, to universally ignore all 'dist' directories:
# dist

What it looks like in practice

Below is the structure of the static/ folder from one of my smaller Django projects.

You can see the tailwind.css file in both the static/src/css/ and static/dist/css/ folders. The version in src is the shell CSS file required by Tailwind CSS for its initial configuration, while the one in dist contains the compiled CSS styles actively used by the project.

For JavaScript libraries, I use the static/public/vendor/js/ folder to store minified scripts for HTMX and Alpine.js. I prefer to place any vendored assets in their own vendor/ folder, which helps keep the directory structure clean and organized for easier management.

static/
├── dist/
│   └── css/
│       └── tailwind.css          # Compiled CSS
├── public/
│   ├── vendor/
│   │    └── js/
│   │        ├── alpinejs.min.js  # Minified Alpine.js
│   │        └── htmx.min.js      # Minified HTMX
│   └── logo-sm.png               # Static image asset
└── src/
    └── css/
        └── tailwind.css          # Source CSS for Tailwind

For a slightly more complicated setup, consider a project of mine that incorporates a fairly large React SPA. The structure below demonstrates how I organize files to support both development and production environments effectively:

static/
├── dist/
│   ├── css/
│   │   └── tailwind.css     # Compiled CSS
│   ├── main-BvH4oN1P.js     # Compiled main JS file with hash for cache busting
│   ├── main-D-2GwwJG.css    # Compiled main CSS file with hash
│   ├── router-9A0RiP7h.css  # Compiled router CSS with hash
│   └── router-DlIDJo3H.js   # Compiled router JS with hash
├── public/
│   └── logo-sm.png          # Static image asset
└── src/
    ├── api/                 # API interaction layers
    ├── components/          # React components
    ├── config/              # Configuration files
    ├── contexts/            # React contexts
    ├── helpers/             # Helper functions
    ├── hooks/               # Custom React hooks
    ├── images/              # Source images
    ├── models/              # Data models
    ├── queries/             # Data fetching queries
    ├── routes/              # Route definitions
    ├── scss/                # SCSS files before processing
    ├── utils/               # Utility functions
    ├── main.tsx             # Main entry point for the SPA
    ├── router.tsx           # Router setup
    ├── tailwind.css         # Source CSS for Tailwind
    └── vite-env.d.ts        # TypeScript definitions for Vite

This directory structure accommodates a comprehensive React application by separating source files, components, and configuration data into subdirectories within src/. The dist/ directory holds compiled and versioned assets.

Why?

So, why opt for this segmented directory setup rather than a single static/ or assets/ folder containing all CSS, JS, and other static files directly in the base of the project?

To be honest, this is a strategy that many popular JS frameworks — such as Astro, Next.js, and SvelteKit — get right. They clearly distinguish between source files requiring processing and those that can be directly served. This common pattern, which I've adopted, involves placing directly servable files within a public/ directory and others in the src/ directory. This approach allows anyone to immediately understand which source files depend on some sort of build pipeline.

One consideration when using two source folders but only one distribution folder is the potential for file conflicts and one folder’s files clobbering another’s. However, this can generally be managed by maintaining unique filenames or organizing files within specific directories. Additionally, when using tools like Vite, which generates hashed filenames during the build, this concern is mitigated. Nonetheless, it's a trade-off worth noting in this setup.

Thanks for reading! I hope you've found this post useful — whether it's inspired you to try a new way of organizing your Django staticfiles, or even if it's a method you'd prefer to avoid.

I'm on Mastodon at @josh@joshthomas.dev and would love to hear what you think.

Many thanks to Jeff for reading the first draft and offering his thoughts on how I could improve it.

Again.

I wanted to write a much longer post about the history of my personal website -- and I definitely will later, unless my ADHD gets the better of me -- but if I don't at least write something, I'll never get this website refresh out the door. For now I'll just say, I've settled on using the language and framework I'm most comfortable with, Python and Django.

This site has been through many iterations built with so many different languages and frameworks over the years. It's been fun to dabble and it's taught me a lot. That's what I like best about having a personal website, being able to try out new things in public but with relatively low stakes.

But these days with a very busy full time job, 2 kids, a wife, a house and yard to take care of, and the desire to have some fun with my free time, I find I just don't have the patience for the upkeep that comes with using something I don't know for this site. I still want this to be a playground for exploring new ideas, but for now I'm choosing the boring choice and going with what I know.

For those curious, the site is open source and is available over on my GitHub profile.