Matthias Kestenholz: Posts about Django

The 2026 way of using importmaps in Django

2026-06-17T12:00:00Z

The 2026 way of using importmaps in Django

I last wrote about Django, JavaScript modules and importmaps in May 2025, slightly over a year ago.

The main topic of this post is the django-js-asset 4.0 release. The library is used in many places, some of the more well-known packages using it are django-mptt and django-ckeditor. I have since done a lot of work evolving the ways of integrating importmaps but the efforts to standardize upon an approach have stalled a bit. The main reason for this, apart from time and energy, was that I wasn’t really all that happy with the global importmap. When I had only a few modules using the importmap facility, I didn’t care all that much. Now that the recently released django-content-editor 9.0 also uses importmaps for shipping a refactored, much more modular JavaScript implementation while still keeping all the benefits of cache busting using ManifestStaticFilesStorage¹, having a global importmap got annoying. The content editor JavaScript is only used within the Django administration interface, but when using a single global importmap object, the importmap entries were always there on each page that used an importmap at all.

A better solution was needed. I’m a big fan of using forms.Media for collecting CSS and JavaScript from widgets, forms and utilities. It helps me avoid inline JavaScript since at least 2017. I’m not using it for site-wide CSS and JavaScript, I’m still transpiling, PostCSS-ing and bundling the assets using rspack as for example written about here and here.

Why importmaps?

A quick refresher on why this matters at all. Django’s ManifestStaticFilesStorage hashes the contents of each file into its name for cache busting, but out of the box it doesn’t rewrite the import statements inside JavaScript modules. Importmaps bridge the gap: your code imports a stable name:

import { initializeEditors } from "django-prose-editor/editor"

and the importmap tells the browser where that name actually lives:

<script type="importmap">
{"imports": {
  "django-prose-editor/editor": "/static/django_prose_editor/editor.6e8dd4c12e2e.js"
}}
</script>

So the import stays clean and constant while the file behind it can get a new hash on every deploy.

django-js-asset 4.0

The updated django-js-asset 4.0 doesn’t ship the old, global importmap at all. This means the upgrade might require some work. Instead of one importmap shared across the whole site, you now get a specific importmap assembled for the context at hand – either by Django itself when it collects the media of your forms, widgets and the admin, or explicitly by you in a view or context processor. The building block in both cases is the ImportMap object; when it travels through js_asset.Media (a subclass of django.forms.Media) the maps are automatically merged into a single <script type="importmap">, by customizing and extending what Django does already when merging media instances.

The release notes go into more detail.

In practice

If you’re using a package such as django-prose-editor in the Django admin you don’t have to do anything, things should just work.

If you’re using such a package outside the admin, you have to remove "js_asset.context_processors.importmap" from your list of context processors. On one particular website the prose editor is the only package with importmap entries outside the admin, so I have to add the importmap to the template context myself:

from django_prose_editor.widgets import importmap

def view(request, ...):
    return render(request, "template.html", {
        # ...
        "importmap": importmap,
    })

The template then just renders it in the <head>:

... {{ importmap }}</head>

On a different site, I have a slightly more involved scenario where I previously used importmap.update(...) to add my own entries to the importmap. There, I’m using a custom context processor to always add these entries to the importmap too:

from django_prose_editor.widgets import importmap as dpe_importmap
from js_asset import ImportMap, static_lazy

_site_importmap = ImportMap({
    "imports": {
        "my-module": static_lazy("my-module.js"),
    }
})
_importmap = dpe_importmap | _site_importmap

def importmap(request):
    return {"importmap": _importmap}

This importmap is merged once at server startup and then served repeatedly to the client. Because we use the lazy version of the static function we can do this during startup and not worry about files not yet collected by collectstatic – we’ll get the correct paths later.

On the same site as the previous example, I also have an admin inline which requires some JavaScript and also an importmap:

from django.contrib import admin
from django.forms import Script
from js_asset import Media, ImportMap

# Initializing this once. Not necessary but I like it better that way.
_importmap = ImportMap({
    "imports": {
        # ...
    }
})

class ModelInline(admin.StackedInline):
    @property
    def media(self):
        return Media(
            js=[
                _importmap,
                Script("module.js", type="module"),
            ]
        )

As of 4.0, JS and CSS produce Django’s own Script and Stylesheet objects, so you can import and use Script directly from django.forms as shown above (on Django 4.2–5.1, import it from js_asset instead, which backports it). The familiar JS("module.js", {"type": "module"}) wrapper still works unchanged if you prefer it — it just takes a positional dict instead of keyword arguments.

Here, it’s really important to use the js_asset.Media and not django.forms.Media. js_asset.Media knows how to handle importmaps – all importmaps are collected from all media lists, merged and added to the output before all other CSS and especially JavaScript. The reason for that is that browsers only honour a single importmap per page, and it really has to appear before all JavaScript modules referencing any entries in the importmap.

The nice thing about js_asset.Media is that it doesn’t have to appear first in the list of media classes which are merged – it can also appear in the middle or last, and still can do its magic after all Media objects have been merged into a single one.

The rest is handled by Django itself, since it already supports collecting media assets. The missing piece was just the importmap object and the js_asset.Media class which knows how to special case them, and which – through the power of overriding __add__ and __radd__ takes over all the other media instances.

What’s next

I haven’t yet used CSP nonces using {% csp_nonce_attr media %} in production myself, but it should just work, even with importmaps and everything else. Given that I have a passing test suite I have no reason to believe it doesn’t already work, but I’d like to have a confirmation.

I’m hoping to standardize some more. If we could get something like this in Django core that would be really nice. Maybe I’ll be able to work on that at Django on the Med 🏖️. Since no browser supports multiple importmaps as of today having multiple implementations of importmaps in the Django ecosystem will lead to trouble down the road. I think there is a clear case to be made for importmap support in Django and I would obviously love it if the approach implemented today in django-js-asset would be the basis for the official solution.

Without having to do any overrides to enable ESM support. ↩

«Anything new?»

2026-06-03T12:00:00Z

«Anything new?»

A lot of time has passed since I officially announced that I want to step down from maintaining django-mptt. I started contributing around 2009, tagged the 0.3 release in April 2010, and have been the sole active maintainer since somewhere around 2019. The post about django-tree-queries has more background, but that’s not today’s topic.

Stepping away isn’t easy

For me, abandoning a project is a bit like stepping out of a relationship: negative emotions end up being a somewhat necessary driver, because the absence of positive events alone rarely provides enough force on its own. I get a lot of satisfaction from a job well done, and walking away means letting that go.

Even with time set aside for open source in my work day, I still have to choose where that time goes. django-mptt stopped being where it needed to go.

The sense of entitlement

When a project is obviously unmaintained, asking for free labor is walking a tightrope. It takes real care not to rekindle exactly the frustrations that led maintainers away in the first place.

It takes energy not to clap back when someone is being rude or insensitive in the issue tracker. Asking “Anything new?” on a ticket where the next steps were outlined clearly and obviously nothing happened in the meantime is just one variant of this.

Quietly quitting isn’t what I want to do — and as a user of django-mptt myself, I can’t really do that either. Taking the high road is the professional choice. But it costs something.

I keep coming back to Mona Eltahawy on refusing to be civil. She’s speaking about something quite different, and I’m aware I write this as a white man. The situations aren’t the same at all. But she articulated something I haven’t managed to put into words as well myself and I like the idea of speaking up and taking the fight to those who awaken these feelings instead of taking the high road.

Doing it with AI

No post these days is complete without the obligatory AI mention, but there’s some relevancy to it.

I fixed and closed almost all open django-mptt issues in a two-hour Claude session. I’ve previously written about using LLMs for open source maintenance, and the productivity gain is real whatever the detractors say. And the quality isn’t suddenly getting worse. Code wasn’t perfect before either. The test suite allows a certain degree of trust in the result and according to my rules for releasing Open Source software we don’t have to require more than that.

It doesn’t change the underlying dynamic, though. rsync and outrage illustrates the trap neatly: Tridgell got flooded with AI-generated security reports, used AI to handle them, and then got criticized for using AI. The tools that created the workload aren’t allowed to address it. The expectation is that the work has to involve sweat and tears and uncountable unpaid hours.

The common goal should be more and better open source software. What we get as Open Source maintainers is shit from both sides: One side took our free work and trained models on it without asking, the other side complains about the supposedly unethical use of AI while acting in unethical ways themselves.

There’s something Kantian about how open source contribution gets framed. Kant’s argument was that the only truly moral acts are those driven by duty and good will — not by desire, inclination, or any expectation of compensation. By that logic, I’m only acting morally if I keep going despite the burnout and the entitlement. If I stop, I’m not.

It’s bleak. The problems with AI are real. The people controlling the large models are assholes. But I have to work in the world as it is while also trying to change it for the better.

Weeknotes (2026 week 17)

2026-05-20T12:00:00Z

Weeknotes (2026 week 17)

I published the last entry near the beginning of March. I’m really starting to see a theme in my Weeknotes publishing schedule.

Releases since the first weeks of March

I’m trying out a longer-form version of those notes here than in the past. I think it’s worth going into some detail and not just listing releases with half a sentence each.

feincms3-sites and feincms3-language-sites

I released updates to feincms3-sites and feincms3-language-sites fixing the same issue in both projects: When an HTTP client didn’t strip the default ports :80 (for HTTP) or :443 (for HTTPS) from a request, finding the correct site would fail. Browsers generally strip the port already, but some other HTTP clients do not.

django-tree-queries

As I wrote elsewhere I closed many issues in the repositories, mostly documentation issues but also some bugs. {% recursetree %} should now work properly and not cache old data anymore, using the primary key in .tree_fields() now raises an intelligible error, and I also fixed a bug with table quoting when using django-tree-queries with the not yet released Django 6.1+.

feincms3-cookiecontrol

feincms3-cookiecontrol not only offers a cookie consent banner (which actually supports only embedding tracking scripts when users give consent) but also a third-party content embedding functionality which allows allowlisting individual services.

The privacy policies of these services are now linked inline instead of with an ugly extra link. This reduces content inside the embed which helps on small screens.

Version 1.7 used a buggy trusted publishing workflow so I immediately published 1.7.1.

django-cabinet and django-prose-editor

django-cabinet can now be used as a media library directly inside django-prose-editor. I’m (ab)using the CKEditor 4 protocol for embedding, which uses window.opener.CKEDITOR.callFunction to send data back from the file manager popup into the editor. It feels icky but works nicely. This is only available if you’re installing the alpha prereleases, but I’m already testing the functionality in production somewhere, so I feel quite good about it.

django-prose-editor now also ships brand new ClassLoom and StyleLoom extensions. Both extensions allow adding either classes or inline styles to text spans or nodes. In an ideal world we might not use something like this, but to make the editor more useful in the real world, editors need more flexibility. These two extensions provide that. I already mentioned ClassLoom in December, now it’s actually available. I’m not completely sold on how they work yet, but both of them are already solving real issues.

Honorable mentions

django-debug-toolbar 6.3 has been released, I only contributed reviews during this cycle.

Switching all of my Python packages to PyPI trusted publishing

2026-04-08T12:00:00Z

Switching all of my Python packages to PyPI trusted publishing

As I have teased on Mastodon, I’m switching all of my packages to PyPI trusted publishing. I have been using it to release the django-debug-toolbar a few times but never set it up myself. The process seemed tedious.

The malicious releases uploaded to PyPI two weeks ago and the blog post about digital attestations in pylock.toml finally pushed me to make the switch. All of my PyPI tokens have been revoked so there is no quick shortcut.

Note

I’m also looking at other code hosting platforms. I have been using git before GitHub existed and I’ll probably still use git when GitHub has completed its enshittification. For now the cost/benefit ratio of staying on GitHub is still positive for me. Trusted publishing isn’t available everywhere, so for now it is GitHub anyway.

In the end, switching an existing project was easier than expected. I have completed the process for django-prose-editor and feincms3-cookiecontrol.

For my future benefit, here are the step by step instructions I have to follow:

Have a package which is buildable using e.g. uvx build
On PyPI add a trusted publisher in the project’s publishing settings:
- Owner: matthiask, feincms, feinheit, whatever the user or organization’s name is.
- Repository: django-prose-editor
- Workflow name: publish.yml
- Environment: release
In the GitHub repository, create a release environment in Settings / Environments. If I want to manually approve releases I’ll add myself and potentially also other releasers as required reviewers.
Run git tag x.y.z and git push, no more uvx twine or hatch publish.
Approve the release in the actions tab on the repository.
Either enjoy or swear and repeat the steps.

I’m happy with testing the release process in production. The older I get the less I care if people think I’m stupid. That’s also why feincms3-cookiecontrol 1.7.0 doesn’t exist, only 1.7.1 – the process failed and I had to bump the patch version and try again. Copy the publish.yml from a known good place, for example from the django-prose-editor repository. I have added the if: github.repository == 'feincms/django-prose-editor' statement which ensures that the workflow only runs in the main repository, but that’s optional if you don’t care about failing workflows.

LLMs for Open Source maintenance: a cautious case

2026-03-25T12:00:00Z

LLMs for Open Source maintenance: a cautious case

When ChatGPT appeared on the scene I was very annoyed at all the hype surrounding it. Since I’m working in the fast moving and low margin business of communication and campaigning agencies I’m surrounded by people eager to jump on the hype train when a tool promises to lessen the workload and take stuff from everyone’s plate.

These discussions coupled with the fact that the training of these tools required unfathomable amounts of stealing were the reason for a big reluctance on my part when trying them out. I’m using the word stealing here on purpose, since that’s exactly the crime Aaron Swartz was accused of by the attorney’s office of the district of Massachusetts. It’s frustrating that some people can get away with the same crime when it is so much bigger. For example, OpenAI and Anthropic downloaded much more data than Aaron ever did.

A somewhat related thing happened with the too-big-to-fail banks: There, the people at the top were even compensated with golden parachutes at the end. LLM companies seem to be above accountability too.

Despite all this, I have slowly started integrating these tools into my workflows. I don’t remember the exact point in time, but since some time in 2025 my opinions on their utility has started to change. At the beginning, I always removed the attribution and took great care to write and rewrite the code myself, only using the LLMs for inspiration and maybe to generate integration tests. More and more I have to admit that they are useful, especially in time constrained projects with a clear focus and purpose.

Last month I fixed and/or closed all open issues in the django-tree-queries repository with the help of Claude Code. Is that a good thing? It could be argued I should have done the work myself. But I wouldn’t have — I have other things I want to do with my time. I don’t want to (always) work on Open Source software in the evening. I definitely also have leaned heavily on LLMs when working on django-prose-editor.

Is faster better?

We can produce more code, more features and close tickets faster than before. In my experience the speed up isn’t as big as some people may want us to believe, but it’s there. And contrary to what people in my LinkedIn feed say, that’s not an obviously good thing. Is it a race to the bottom where we drown in LLM-generated slop in quantities impossible to maintain? It doesn’t feel like that — but it’s a race that could go both ways. Throwaway code can be thrown away though, and well tested code does what the tests say, which is good enough according to my rules for releasing open source software.

Speaking as someone who has put more into the training set than they’ve taken out so far, I don’t feel all that bad using the tools. Coding agents can already be run locally with reasonable hardware requirements, at least during inference, which is where the ongoing cost sits. Maybe using them is still rationalization. But contribution and profit needing to stay in some rough balance feels like the right frame. Total abstinence isn’t the only ethical choice we have.

Community tensions

What makes me less comfortable is how communities are reacting. There are real concerns within the Django world, and not just the practical one of overworked maintainers wading through hastily generated patches that don’t actually fix anything. The deeper worry is about the communal nature of contribution: that working on Django is supposed to be a learning experience, a way into the community, and that using an LLM as a vehicle rather than a tool hollows out that process. Reviewers end up interacting with what is essentially a facade, unable to tell whether anyone actually understood the problem. That’s a real concern and I don’t want to dismiss it.

But it maps onto a different situation from what I’ve been describing. Using Claude Code to close issues in projects I maintain and understand is not the same as using it to paper over gaps in comprehension on a ticket in someone else’s project. Whether LLM-assisted contributions to Django itself are appropriate is a difficult question; whether it’s appropriate to use them when maintaining your own software less so.

There’s also a harder tension around quality. Django’s conservatism has real value: rigorous review, minimal magic, a coherent philosophy. The ORM and template system don’t need to reinvent themselves, they work well, are still evolving while staying rock-solid for all my use cases. And reading the release notes always brings me joy. But it could be more exciting more often. Quality isn’t a strictly positive thing. Everything has costs. It’s not great if the price of the bar is that legitimate bugs sit open for years because nobody has a few evenings to spend on them. It happened with django-tree-queries before I went through it with Claude Code. I think the bar for contributing to Django is too high. I would value a little more motion and a little less stability, even as someone running dozens of Django websites and apps.

Then there’s the pile-on dynamic that plays out on Mastodon and GitHub. When the Harfbuzz and chardet maintainers disclosed LLM usage, the reaction from some corners was something to behold. People expressing what amounted to personal grievance over tooling choices in projects they may not even use. There’s a particular kind of entitlement in telling a maintainer – who is keeping software alive, possibly even in their spare time – that the way they choose to do that work is an affront. Open source is a gift, whether paid or not, and nobody has to accept it, but disclosing your tooling isn’t an invitation for complaints. The ethical concerns about training data, resource use and other negative externalities are legitimate and worth raising. Performative outrage directed at individual maintainers is not the same thing.

I don’t have an easy conclusion. The tools are useful, the ethics are murky, and communities are still figuring out how to respond. A cautious, honest use of them feels better to me than the alternatives.

Weeknotes (2026 week 11)

2026-03-11T12:00:00Z

Weeknotes (2026 week 11)

Last time I wrote that I seem to be publishing weeknotes monthly. Now, a quarter of a year has passed since the last entry. I do enjoy the fact that I have published more posts focused on a single topic. That said, what has been going on in open source land is certainly interesting too.

LLMs in Open Source

I have started a longer piece to think about my stance regarding using LLMs in Open Source. The argument I’m thinking about is that there’s a balance between LLMs having ingested all of my published open source code and myself using them now to help myself and others again.

The happenings in the last two weeks (think Pentagon, Iran, and the bombings of schools) have again brought to the foreground the perils of using those tools. I therefore haven’t been motivated to pursue this train of thought for the moment. When the upsides are somewhat questionable and tentative and the downsides are so clear and impossible to miss, it’s hard to use my voice to speak in favor of these tools.

That said, all the shaming when someone uses an LLM that I see in my Mastodon feed also annoys me. I’ll quote part of a post here which I liked and leave it at that for the moment:

The AI hype-cyclone is bad, but so is the anti-AI witch hunt. Commits co-authored by Claude do not mean that a project has “abandoned engineering as a serious endeavor”

[…]

– @nedbat on Mastodon

Other goings-on

Health: My back continues to improve. Some days are still bad, but the idea that the herniation may go away entirely doesn’t sound totally unreasonable anymore.
Gardening: We started weeding the garden last week. Lots to do! Being outside is fun. Weeding isn’t the greatest part ever, but it’s meditative.

Releases since December

django-json-schema-editor 0.12.1: CSS fixes. I have again looked at other, more modern JSON schema editor implementations but all of them are more limited than is acceptable to act as a replacement.
django-debug-toolbar 6.2: I haven’t done much work here! Just some reviewing.
django-content-editor 8.1: Started emitting warnings when using non-abstract base classes for plugins. Using multi table inheritance is mostly an accident and not intended in my experience when using django-content-editor, therefore we have started detecting this case and emitting system checks (warnings, not errors).
django-imagefield 0.23.0a3: We have done some work on supporting libvips as an alternative backend to Pillow because I hoped that memory usage in Kubernetes pods might go down a bit. Results are not conclusive yet, and I’m not yet convinced the additional code complexity is worth it. Debugging and monitoring continues.
FeinCMS 26.2.1: Released a few bugfixes. FeinCMS is still being maintained ~17 years later!
django-auto-admin-fieldsets 0.3: Added a helper to remove fields from the fieldsets structure.
django-tree-queries 0.23.1: Shipped a small bugfix for {% recursetree %} which unintentionally cached children across invocations.
feincms3-downloads: Used PATH from the environment instead of using a very restricted allowlist so that convert and pdftocairo are detected in more locations. This should help with local development for example on macOS.
django-prose-editor 0.24.1: Read the CHANGELOG; there’s too much in there for a short notice.
form-designer 0.27.3: Mosparo captcha support, bugfixes and additional translations.
feincms3 5.5: Started using the OrderableTreeNode from django-tree-queries.

Rich text editors: How restrictive can we be?

2025-12-17T12:00:00Z

Rich text editors: How restrictive can we be?

How restrictive should a rich text editor be? It’s a question I keep coming back to as I work on FeinCMS and Django-based content management systems.

I published the last blog post on django-prose-editor specifically in August 2025, Menu improvements in django-prose-editor. The most interesting part of the blog post was the short mention of the TextClass extension at the bottom which allows adding a predefined list of CSS classes to arbitrary spans of text.

In the meantime, I have spent a lot of time working on extensions that try to answer this question: the TextClass extension for adding CSS classes to inline text, and more recently the NodeClass extension for adding classes to nodes and marks. It’s high time to write a post about it.

Rich Text editing philosophy

All of this convinced me that offering the user a rich text editor with too much capabilities is a really bad idea. The rich text editor in FeinCMS only has bold, italic, bullets, link and headlines activated (and the HTML code button, because that’s sort of inevitable – sometimes the rich text editor messes up and you cannot fix it other than going directly into the HTML code. Plus, if someone really knows what they are doing, I’d still like to give them the power to shoot their own foot).

– Commit in the FeinCMS repository, August 2009, current version from django-content-editor design decisions

Should we let users shoot themselves in the foot?

Giving power users an HTML code button would have been somewhat fine if only the editors themselves were affected. Unfortunately, that was not the case.

As a team we have spent more time than we ever wanted debugging strange problems only to find out that the culprit was a blob of CSS or JavaScript inserted directly into an unsanitized rich text editor field. We saw everything from a few reasonable and well scoped lines of CSS to hundreds of KiBs of hotlinked JavaScript code that broke layouts, caused performance issues, and possibly even created security vulnerabilities.

We have one more case of Betteridge’s law of headlines here.

The pendulum swings

The first version of django-prose-editor which replaced the venerable CKEditor 4 in our project was much more strict and reduced – no attributes, no classes, just a very short list of allowlisted HTML tags in the schema.

We quickly hit some snags. When users needed similar headings with different styles, we worked around it by using H2 and H3 — not semantic at all. I wasn’t exactly involved in this decision; I just didn’t want to rock the boat too much, since I was so happy that we were even able to use the more restricted editor at all in this project.

Everything was good for a while, but more and more use cases crept up until it was clear that something had to be done about it. First, the TextClass extension was introduced to allow adding classes to inline text, and later also the NodeClass extension mentioned above. This was a compromise: The customer wanted inline styles, we wanted as little customizability as possible without getting in the way.

That said, we obviously had to move a bit. After all, going back to a less strict editor or even offering a HTML blob injection would be worse. If we try to be too restrictive we will probably have to go back to allowing everything some way or the other, after all:

The more you tighten your grip, Tarkin, the more star systems will slip through your fingers.

– Princess Leia

Combining CSS classes

The last words are definitely not spoken just yet. As teased on Mastodon at the beginning of this month I am working on an even more flexible extension which unifies the NodeClass and TextClass extensions into a single ClassLoom extension.

The code is getting real world use now, but I’m not ready to integrate it yet into the official repository. However, you can use it if you want, it’s 1:1 the version from a project repository. Get the ClassLoom extension here.

This extension also allows combining classes on a single element. If you have 5 colors and 3 text styles, you’d have to add 15 combinations if you were only able to apply a single class. Allowing combinations brings the number of classes down to manageable levels.

Conclusion

So, back to the original question: How restrictive can we be?

The journey from CKEditor 4’s permissiveness through django-prose-editor’s initial strictness to today’s ClassLoom extension has been one of finding that balance. Each extension — TextClass, NodeClass, and now ClassLoom — represents a step toward controlled flexibility: giving content editors the styling options they need while keeping the content structured, maintainable, and safe.

Weeknotes (2025 week 49)

2025-12-05T12:00:00Z

Weeknotes (2025 week 49)

I seem to be publishing weeknotes monthly, so I’m now thinking about renaming the category :-)

Mosparo

I have started using a self-hosted mosparo instance for my captcha needs. It’s nicer than Google reCAPTCHA. Also, not sending data to Google and not training AI models on traffic signs feels better.

Fixes for the YouTube 153 error

Simon Willison published a nice writeup about YouTube embeds failing with a 153 error. We have also encountered this problem in the wild and fixed the feincms3 embedding code to also set the required referrerpolicy attribute.

Updated packages since 2025-11-04

django-sitemaps 2.0.2: Uploaded a new release which includes a wheel build. Rebuilding the wheel all the time when creating new container images was getting annoying. The code itself is unchanged.
django-prune-uploads 0.3.1: The package now supports pruning a storage backed by django-s3-storage efficiently. I have also looked at django-prune-media but since the package uses the storage API instead of enumerating files using boto3 directly it’s unusably slow for my use case.
feincms3-forms 0.6: Much better docs and a new way to reference individual form fields in custom templates.
django-json-schema-editor 0.11: Switched from JSON paths to jmespath instances. Made the JSON model instance reference support easier and more fun to use. Added new ways of customizing the generated proxy model for individual JSON plugin instances.
form-designer 0.27.1: Added support for the mosparo captcha to the default list of field types.
asgi-plausible 0.1.1: No code change really, just added required dependencies to the package metadata.
django-tree-queries 0.23: The package now ships a OrderableTreeNode base model which you can use when you want to order siblings manually. feincms3 already uses this base model for its pages model.
feincms3-data 0.10: This is quite a big one. I discovered issues with the way save_as_new (to copy data) and delete_missing interacted. First the code was cleaned up to delete less data, and then to delete enough data. I’m now somewhat confident that the code does what it should again.
django-prose-editor 0.22.3: Started returning an empty string for an empty document instead of <p></p> also when using the frontend integration; previously, this transformation was only implemented when using at least the form if not the model field. Also, <ol> tags now have a data-type attribute since Chrome cannot case-sensitively match e.g. type="a" vs type="A" for lowercase or uppercase letters. I previously only tested the code in Firefox and there it worked nicely.

Thoughts about Django-based content management systems

2025-11-05T12:00:00Z

Thoughts about Django-based content management systems

I have almost exclusively used Django for implementing content management systems (and other backends) since 2008.

In this time, content management systems have come and gone. The big three systems many years back were django CMS, Mezzanine and our own FeinCMS.

During all this time I have always kept an eye open for other CMS than our own but have steadily continued working in my small corner of the Django space. I think it’s time to write down why I have been doing this all this time, for myself and possibly also for other interested parties.

Why not use Wagtail, django CMS or any of those alternatives?

Let’s start with the big one. Why not use Wagtail?

The Django administration interface is actually great. Even though some people say that it should be treated as a tool for developers only, recent improvements to the accessibility and the general usability suggest otherwise. I have written more about my views on this in The Django admin is a CMS. Using and building on top of the Django admin is a great way to immediately profit from all current and future improvements without having to reimplement anything.

I don’t want to have to reimplement Django’s features, I want to add what I need on top.

Faster updates

Everyone implementing and maintaining other CMS is doing a great job and I don’t want to throw any shade. I still feel that it’s important to point out that systems can make it hard to adopt new Django versions on release day:

The update cycle of many large apps using Django lag behind Django. Wagtail declares an upper version boundary for Django which makes it hard to adopt Django versions faster than Wagtail releases updates.
Some django CMS components such as django-filer have lagged behind in the past. Looking at the project’s CI matrix and activity suggests that this is not the case anymore. That said, a simpler alternative exists.

These larger systems have many more (very talented) people working on them. I’m not saying I’m doing a better job. I’m only pointing out that I’m following a different philosophy where I’m conservative about running code in production and I’d rather have less features when the price is a lot of maintenance later. I’m always thinking about long term maintenance. I really don’t want to maintain some of these larger projects, or even parts of them. So I’d rather not adopt them for projects which hopefully will be developed and maintained for a long time to come. By the way: This experience has been earned the hard way.

The rule of least power

From Wikipedia:

In programming, the rule of least power is a design principle that “suggests choosing the least powerful [computer] language suitable for a given purpose”. Stated alternatively, given a choice among computer languages, classes of which range from descriptive (or declarative) to procedural, the less procedural, more descriptive the language one chooses, the more one can do with the data stored in that language.

Django itself already provides lots and lots of power. I’d argue that a very powerful platform on top of Django may be too much of a good thing. I’d rather keep it simple and stupid.

Editing heterogenous collections of content

Django admin’s inlines are great, but they are not sufficient for building a CMS. You need something to manage different types. django-content-editor does that and has done that since 2009.

When Wagtail introduced the StreamField in 2015 it was definitely a great update to an already great CMS but it wasn’t a new idea generally and not a new thing in Django land. They didn’t say it was and welcomed the fact that they also started using a better way to structure content.

Structured content is great. Putting everything into one large rich text area isn’t what I want. Django’s ORM and admin interface are great for actually modelling the data in a reusable way. And when you need more flexibility than what’s offered by Django’s forms, the community offers many projects extending the admin. These days, I really like working with the django-json-schema-editor component; I even reference other model instances in the database and let the JSON editor handle the referential integrity transparently for me (so that referenced model instances do not silently disappear).

Weeknotes (2025 week 45)

2025-11-04T12:00:00Z

Weeknotes (2025 week 45)

Autumn is nice

I love walking through the forest with all the colors and the rustling when you walk through the leaves on the ground.

Updated packages since 2025-10-23

feincms3 5.4.3: Small fix for the YouTube IFRAME; it seems that the referrerpolicy attribute is now necessary for the embed to work everywhere.
django-json-schema-editor 0.8.2: Allowed forwarding more options to the prose editor component; specifically, not just extensions but also the undocumented js_modules entry. This means that custom extensions are now also supported inside the JSON editor component.
django-prose-editor 0.20: I reworked the menu extension to be customizable more easily (you can now specify button groups and dropdowns directly without using JavaScript code) and I also extended the NodeClass extension to allow assigning predefined CSS classes not only to nodes but also to marks.

Weeknotes (2025 week 43)

2025-10-23T12:00:00Z

Weeknotes (2025 week 43)

I published the last weeknotes entry in the first half of September.

Drama in OSS

I have been following the Ruby gems debacle a bit. Initially at Feinheit we used our own PHP-based framework swisdk2 to build websites. This obviously didn’t scale and I was very annoyed with PHP, so I was looking for alternatives.

I remember comparing Ruby on Rails and Django, and decided to switch from PHP/swisdk2 to Python/Django for two reasons: The automatically generated admin interface and the fact that Ruby source code just had too much punctuation characters for my taste. It’s a very whimsical reason and I do not put any weight on that. That being said, given how some of the exponents in Ruby/Rails land behave I’m very very glad to have chosen Python and Django. While not everything is perfect (it never is) at least those communities agree that trying to behave nicely to each other is something to be cheered and not something to be sneered at.

Copilot

I assigned some GitHub issues to Copilot. The result wasn’t very useful. I don’t know if I want to repeat it, local tools work fine for when I really need them.

Python and Django compatibility

It’s the time again to update the GitHub actions matrix and Trove identifiers. I do not like doing it. You can expect all maintained packages to be compatible with the latest and best versions, no upper bounds necessary. Man, if only AI could automate those tasks…

Updated packages since 2025-09-10

feincms3: We use hashlib.md5, but not for security.
django-tree-queries 0.21.2: django-tree-queries now bundles an admin interface for trees.
django-content-editor 8.0.3: Minor CSS fix so that the editor looks nicer with Django 6.0.
django-json-schema-editor 0.8.1: Fixes for multiple JSON editors in the same window, better JSONPlugin.__str__ default implementation.
django-cabinet 0.18.1: Fix a minor bug around the selected folder handling. Invalid folder ID values could crash the backend under some circumstances.
django-prose-editor 0.18.5: No large changes, mainly Tiptap updates.

My favorite Django packages

2025-10-22T12:00:00Z

My favorite Django packages

Inspired by other posts I also wanted to write up a list of my favorite Django packages. Since I’ve been working in this space for so long and since I’m maintaining quite a large list of packages I worry a bit about tooting my own horn too much here; that said, the reasons for choosing some packages hopefully speak for themselves.

Also, I’m sure I’m forgetting many many packages here. Sorry for that in advance.

Core Django

speckenv: Loads environment variables from .env and automatically converts them to their Python equivalent if ast.literal_eval understands it. Also contains implementations for loading database, cache, email and storage configuration from environment variables (similar to dj-database-url). I added this functionality to speckenv when some of the available environment configuration apps’ maintenance state was somewhat questionable.
django-cors-headers: CORS header support for Django. This would be a nice addition to Django itself.
sentry-sdk: I’m using Sentry in almost all projects.
django-template-partials: Template partials for Django! This has been added to the upcoming 6.0 release of Django. While the Django template language has always been evolving and improving, this feels like the first larger step in a long time. As I and others have said, the combination of htmx and django-template-partials is really really nice. It isn’t surprising at all that htmx is so well loved in the Django community.
django-s3-storage: Yes, django-storages exist, but I prefer django-s3-storage because of its focus and simplicity.
django-imagefield: Image field which validates images deeply, and supports pre-rendering thumbnails etc. I understand why Django only superficially validates uploaded images because of the danger of denial of service attacks, but I’d rather not have files on the sites I manage which the great Pillow library doesn’t support.
psycopg: Whenever I can I work with PostgreSQL, and psycopg is how I interface with the database.

Data structures

django-tree-queries: My favorite way to work with trees except when talking about real trees.
django-translated-fields: My preferred way to do model-level internationalization.

CMS building

I have been working on FeinCMS since 2009. So, it shouldn’t surprise anyone that this is still my favorite way to build CMS on top of Django. I like that it’s basically a thin layer on top of Django’s administration interface and doesn’t want to take over the whole admin interface or even the whole website.

feincms3: The modern, focussed foundation replacing FeinCMS.
django-content-editor: The admin interface extension providing core components to build content editing interfaces.
django-prose-editor: A nice HTML editor by yours truly.
django-json-schema-editor: JSON schema-based editing using @json-editor/json-editor.

Working with external content

micawber: Micawber is my favorite tool to embed third party content (YouTube, Vimeo, whatever) when feincms3’s own very limited embedding functionality is insufficient.
feincms3-cookiecontrol: Everyone likes cookie banner (or not). feincms3-cookiecontrol implements not just an informative cookie banner, but actually supports not embedding tracking scripts and third party content unless the user consented, either a blanket or a per-provider consent for embedded media. It does NOT support the very annoying interface where you have to deselect each tracking service individually.

PDF generation

Reportlab: Reportlab is nice if you need fine-grained control over PDF generation. Reportlab has created more than 10‘000 invoices for the company I work at, so I’m definitely grateful for it :-)
Weasyprint: I have been using Weasyprint more and more for generating PDFs. Using HTML and CSS can be nicer than using Reportlab’s Platypus module. Weasyprint doesn’t instrument a webbrowser to produce PDFs but instead implements the rendering engine itself. It works really well.

Testing and development

I actually do like unittest. I have started using pytest somewhat more often because using -k keyword to filter tests to run is great.
factory-boy: This package has always treated me well when creating data for tests.
playwright: Playwright is the end-to-end test browser automation library I prefer.

Last but not least, I really like django-debug-toolbar. So much, that I’m even helping with the maintenance since 2016.

Serving

We mostly use Kubernetes to serve websites these days. Inside the pods, I’m working with the granian RSGI/ASGI server and with blacknoise for serving static files.

LLMs are making me a better programmer...

2025-09-12T12:00:00Z

LLMs are making me a better programmer…

I’m still undecided about LLMs for programming. Sometimes they are very useful, especially when working on a clearly stated problem within a delimited area. Cleaning the code up afterwards is painful and takes a long time though. Even for small changes I’m unsure if using LLMs is a way to save (any) resources, be it time, water, energy or whatever.

They do help me get started, and help me be more ambitious. That’s not a new idea. Simon Willison wrote a post about this in 2023 and the more I think about it or work with AI the more I think it’s a good way to look at it.

A recent example which comes to mind is writing end to end tests. I can’t say I had a love-hate relationship with end to end testing, it was mostly a hate-hate relationship. I hate writing them because it’s so tedious and I hate debugging them because of all the timing issues and the general flakyness of end to end testing. And I especially hate the fact that those tests break all the time when changing the code, even when changes are mostly unrelated.

When I discovered that I could just use Claude Code to write those end to end tests I was ecstatic. Finally a way to add relevant tests to some of my open source projects without having to do all this annoying work myself! Unfortunately, I quickly discovered that Claude Code decided (ha!) it’s more important to make tests pass than actually exercising the functionality in question. When some HTML/JavaScript widget wouldn’t initialize, why not just manipulate innerHTML so that the DOM looks as if the JavaScript actually ran? Of course, that’s a completely useless test. The amount of prodding and instructing the LLM agent required to stop adding workarounds and fallbacks everywhere was mindboggling. Also, since tests are also code which has to be maintained in the future, does generating a whole lot of code actually help or not? Of course, the amount of code involved wasn’t exactly a big help when I really had to dig into the code to debug a gnarly issue, and the way the test was written didn’t exactly help!

I didn’t want to go back to the previous state of things when I had only backend tests though, so I had to find a better way.

Playwright codegen to the rescue

I already had some experience with Playwright codegen, having used it for testing some complex onboarding code for a client project I worked on a few years back, so I was already aware of the fact that I could run the browser, click through the interface myself, and playwright would actually generate some of the required Python code for the test itself.

This worked fine for a project, but what about libraries? There, I generally do not have a full project ready to be used with ./manage.py runserver and Playwright. So, I needed a different solution: Running Playwright from inside a test!

If your test uses the LiveServerTestCase all you have to do is insert the following lines into the body of your test, directly after creating the necessary data in the database (using fixtures, or probably better yet using something like factory-boy):

import subprocess
print(f"Live server URL: {live_server.url}")
subprocess.Popen(["playwright", "codegen", f"{self.live_server_url}/admin/"])
input("Press Enter when done with codegen...")

Or of course the equivalent invocation using live_server.url when using the live_server fixture from pytest-django.

Of course Tim pointed me towards page.pause(). I didn’t know about it; I think it’s even better than what I discovered, so I’m probably going to use that one instead. I still think writing down the discovery process makes sense.

So now, when LiveServerTestCase is already set up and I already have a sync Playwright context lying around, I can just do:

page = context.new_page()
page.pause()

TLDR

Claude Code helped getting me to get off the ground with adding end to end tests to my projects. Now, my tests are better because – at least for now – I’m not using AI tools anymore.

Weeknotes (2025 week 37)

2025-09-10T12:00:00Z

Weeknotes (2025 week 37)

I’m having a slow week after the last wisdom tooth extraction. Finally! I’m slowly recuperating from that.

I’m trying to split up the blog posts a bit and writing more standalone pieces instead of putting everything into weeknotes. Publishing more focussed pieces sounds like a good thing and should also help me with finding my own writing later.

Releases

django-content-editor 8.0.2: I fixed the ordering calculation in the cloning functionality; the tests are a bit too forgiving for my taste now but I just can’t figure out why the gap for inserting cloned items is sometimes larger than it should be. It doesn’t matter though, since ordering values do not have any significance, they only have to provide a definite ordering for content items.
django-prose-editor 0.18.2: Cleaned up the documentation after the 0.18 cleanup (where automatic dependency management has been removed), fixed table styles when using dark mode.

Weeknotes (2025 week 35)

2025-08-29T12:00:00Z

Weeknotes (2025 week 35)

Summer was and is nice. The hot days seem to be over (for now), but in the last years summer hasn’t really left until the end of September, so we’ll see. I personally like the warm weather but I really hoped that our leaders were smarter. The climate emergency could be seen from far away. The pigheadedness is hard to stomach. And of course it’s not the only problem we’re facing as humanity at all.

Releases

I did some longer-form writing about two of the releases here: Menu improvements in django-prose-editor and django-content-editor now supports cloning of content

django-debug-toolbar 6.0: We have released a new version of the toolbar which supports persisting debugging data to the database. This is especially useful when using ASGI, because we cannot use threadlocal storage for this data then.
django-prose-editor 0.18: Reworked the menu system to support dropdowns, not just button groups. Added a custom TextClass extension which allows adding classes to spans and a NodeClass extension which allows adding classes to nodes. Tiptap supports adding arbitrary styles, I’d rather limit this a bit more and only offer predefined CSS classes.
django-content-editor 8.0: Added support for cloning content. Made the region tabs stick to the top of the browser window.
django-cabinet 0.18: Improved the folder deletion interface slightly.
django-mptt 0.18: I still seem to be maintaining the project even though I officially marked the project as unmaintained more than 4 years ago.

django-content-editor now supports cloning of content

2025-08-27T12:00:00Z

django-content-editor now supports cloning of content

What is the content editor?

Django’s builtin admin application provides a really good and usable administration interface for creating and updating content. django-content-editor extends Django’s inlines mechanism with an interface and tools for managing and rendering heterogenous collections of content as are often necessary for content management systems.

We are using django-content-editor in basically all projects, as a part of feincms3. The content editor is used not only for building page content, but also for blog entries, for building multi-step intelligent form wizards, for learning units and even to digitize teaching materials for schools, including static and interactive content.

The great thing about it is that it enables us to edit complex content inside Django’s administration interface without trying to replace it with a completely separate interface, as some other more well-known Django-based CMS want to do.

Cloning content

The complexity of managed content has grown a bit, especially since we introduced support for nesting sections. Teaching materials are often available in several learning levels, with only minor differences between them. Unfortunately, the differences aren’t purely additive: It’s not the case that higher levels just have more materials available. Otherwise, we’d probably have used a level on content items to hide content which shouldn’t be shown to students. Content is sometimes totally different. Because of this we’re using content editor’s regions for the learning level, one region per level.

Even then, the basic structure is often the same and building that manually for all levels is annoying at best. That’s why I finally got the occasion to add support for cloning content between regions to the editor.

Of course, cloning should also take the other features into account and allow selecting sections as a whole instead of having to select individual items. Here’s a screenshot of the current interface:

Closing thoughts

I’m still really happy with the content editor; I wish the Django admin would look a little bit nicer because then people would probably be more encouraged to actually learn how powerful it is. The first impression is unfortunately that it looks old and a bit too technical, but in my experience working with many many customers it’s not really the case. Most people are immediately able to work with it and find the interface well structured and appreciate the no bullshit attitude, because working with it really is efficient.

Menu improvements in django-prose-editor

2025-08-23T12:00:00Z

I have repeatedly mentioned the django-prose-editor project in my weeknotes but I haven’t written a proper post about it since rebuilding it on top of Tiptap at the end of 2024.

Much has happened in the meantime. A lot of work went into the menu system (as alluded to in the title of this post), but by no means does that cover all the work. As always, the CHANGELOG is the authoritative source.

0.11 introduced HTML sanitization which only allows HTML tags and attributes which can be added through the editor interface. Previously, we used nh3 to clean up HTML and protect against XSS, but now we can be much more strict and use a restrictive allowlist.

We also switched to using ES modules and importmaps in the browser.

Last but not least 0.11 also introduced end-to-end testing using Playwright.

The main feature in 0.12 was the switch to Tiptap 3.0 which fixed problems with shared extension storage when using several prose editors on the same page.

In 0.13 we switched from esbuild to rslib. Esbuild’s configuration is nicer to look at, but rslib is built on the very powerful rspack which I’m using everywhere.

In 0.14, 0.15 and 0.16 the Menu extension was made more reusable and the way extension can register their own menu items was reworked.

The upcoming 0.17 release (alpha releases are available and I’m using them in production right now!) is a larger release again and introduces a completely reworked menu system. The menu now not only supports button groups and dialogs but also dropdowns directly in the toolbar. This allows for example showing a dropdown for block types:

The styles are the same as those used in the editor interface.

The same interface can not only be used for HTML elements, but also for HTML classes. Tiptap has a TextStyle extension which allows using inline styles; I’d rather have a more restricted way of styling spans, and the prose editor TextClass extension does just that: It allows applying a list of predefined CSS classes to <span> elements. Of course the dropdown also shows the resulting presentation if you provide the necessary CSS to the admin interface.

Weeknotes (2025 week 27)

2025-07-05T12:00:00Z

Weeknotes (2025 week 27)

I have again missed a few weeks, so the releases section will be longer than usual since it covers six weeks.

django-prose-editor

I have totally restructured the documentation to make it clearer. The configuration chapter is shorter and more focussed, and the custom extensions chapter actually shows all required parts now.

The most visible change is probably the refactored menu system. Extensions now have an addMenuItems method where they can add their own buttons to the menu bar. I wanted to do this for a long time but have only just this week found a way to achieve this which I actually like.

I’ve reported a bug to Tiptap where a .can() chain always succeeded even though the actual operation could fail (#6306).

Finally, I have also switched from esbuild to rslib; I’m a heavy user of rspack anyway and am more at home with its configuration.

django-content-editor

The 7.4 release mostly contains minor changes, one new feature is the content_editor.admin.RefinedModelAdmin class. It includes tweaks to Django’s standard behavior such as supporting a Ctrl-S shortcut for the “Save and continue editing” functionality and an additional warning when people want to delete inlines and instead delete the whole object. This seems to happen often even though people are shown the full list of objects which will be deleted.

Releases

django-prose-editor 0.15: See above
django-content-editor 7.4.1: See above.
django-json-schema-editor 0.5.1: Now supports customizing the prose editor configuration (when using format: "prose") and also includes validation support for foreign key references in the JSON data.
html-sanitizer 2.6: The sanitizer started crashing when used with lxml>=6 when being fed strings with control characters inside.
django-recent-objects 0.1.1: Changed the code to use UNION ALL instead of UNION when determining which objects to fetch from all tables.
feincms3 5.4.1: Added experimental support for rendering sections. Sections can be nested, so they are more powerful than subregions. Also, added warnings when registering plugin proxies for rendering and fetching, since that will mostly likely lead to duplicated objects in the rendered output.
django-tree-queries 0.20: Added tree_info and recursetree template tags. Optimized the performance by avoiding the rank table if easily possible. Added stronger recommendations to pre-filter the table using .tree_filter() or .tree_exclude() when working with small subsets of large datasets.
django-ckeditor 6.7.3: Added a trove identifeir for recent Django versions. It still works fine, but it’s deprecated and shouldn’t be used since it still uses the unmaintained CKEditor 4 line (since we do not ship the commercial LTS version).
feincms3-cookiecontrol 1.6.1: Golfed the generated CSS and JavaScript bundle down to below 4000 bytes again, including the YouTube/Vimeo/etc. wrapper which only loads external content when users consent.

Preserving referential integrity with JSON fields and Django

2025-06-04T12:00:00Z

Preserving referential integrity with JSON fields and Django

Motivation

The great thing about using feincms3 and django-content-editor is that CMS plugins are Django models – if using them you immediately have access to the power of Django’s ORM and Django’s administration interface.

However, using one model per content type can be limiting on larger sites. Because of this we like using JSON plugins with schemas for more fringe use cases or for places where we have richer data but do not want to write a separate Django app for it. This works well as long as you only work with text, numbers etc. but gets a bit ugly once you start referencing Django models because you never know if those objects are still around when actually using the data stored in those JSON fields.

Django has a nice on_delete=models.PROTECT feature, but that of course only works when using real models. So, let’s bridge this gap and allow using foreign key protection with data stored in JSON fields!

Models

First, you have to start using the django-json-schema-editor and specifically its JSONField instead of the standard Django JSONField. The most important difference between those two is that the schema editor’s field wants a JSON schema. So, for the sake of an example, let’s assume that we have a model with images and a model with galleries. Note that we’re omitting many of the fields actually making the interface nice such as titles etc.

from django.db import models
from django_json_schema_editor.fields import JSONField

class Image(models.Model):
    image = models.ImageField(...)

gallery_schema = {
    "type": "object",
    "properties": {
        "caption": {"type": "string"},
        "images": {
            "type": "array",
            "format": "table",
            "minItems": 3,
            "items": {
                "type": "string",
                "format": "foreign_key",
                "options": {
                    # raw_id_fields URL:
                    "url": "/admin/myapp/image/?_popup=1&_to_field=id",
                },
            },
        },
    },
}

class Gallery(models.Model):
    data = JSONField(schema=gallery_schema)

Now, if we were to do it by hand, we’d define a through model for a ManyToManyField linking galleries to images, and adding a on_delete=models.PROTECT foreign key to this through model’s image foreign key and we would be updating this many to many table when the Gallery object changes. Since that’s somewhat boring but also tricky code I have already written it (including unit tests of course) and all that’s left to do is define the linking:

Gallery.register_data_reference(
    # The model we're referencing:
    Image,
    # The name of the ManyToManyField:
    name="images",
    # The getter which returns a list of stringified primary key values or nothing:
    getter=lambda obj: obj.data.get("images"),
)

Now, attempting to delete an image which is still used in a gallery somewhere will raise ProtectedError exceptions. That’s what we wanted to achieve.

Using a gallery instance

When you have a gallery instance you can now use the images field to fetch all images and use the order from the JSON data:

def gallery_context(gallery):
    images = {str(image.pk): image for image in gallery.images.all()}
    return {
        "caption": gallery.data["caption"],
        "images": [images[pk] for pk in gallery.data["images"]],
    }

JSONPluginBase and JSONPluginInline

I would generally do the instantiation of models slightly differently and use django-json-schema-editor’s JSONPluginBase and JSONPluginInline which offer additional niceties such as streamlined JSON models with only one backing database table (using proxy models) and supporting not just showing the primary key of referenced model instances but also their __str__ value.

The example above would have to be changed to look more like this:

from django_json_schema_editor import JSONPluginBase

class JSONPlugin(JSONPluginBase, ...):
    pass

JSONPlugin.register_data_reference(...)

Gallery = JSONPlugin.proxy("gallery", schema=gallery_schema)

However, that’s not documented yet so for now you unfortunately have to read the code and the test suite, sorry for that. It’s used heavily in production though so if you start using it it won’t suddenly start breaking in the future.

How I'm bundling frontend assets using Django and rspack these days

2025-05-26T12:00:00Z

How I’m bundling frontend assets using Django and rspack these days

I last wrote about configuring Django with bundlers in 2018: Our approach to configuring Django, Webpack and ManifestStaticFilesStorage. An update has been a long time coming. I wanted to write this down for a while already, but each time I started explaining how configuring rspack is actually nice I look at the files we’re using and switch to writing about something else. This time I managed to get through – it’s not that bad, I promise.

This is quite a long post. A project where all of this can be seen in action is Traduire, a platform for translating gettext catalogs. I announced it on the Django forum.

Our requirements

The requirements were still basically the same:

Hot module reloading during development
A process which produces hashed filenames depending on their content so that we can use far-future expiry headers to cache assets in browsers
While running Node.js in development is fine we do not want Node.js on the server (in the general case)
We still want transpiling and bundling for now

We have old projects using SASS. These days we’re only using PostCSS (especially autoprefixer and maybe postcss-nesting. Rewriting everything is out of the question, so we needed a tool which handled all that as well.

People in the frontend space seem to like tools like Vite or Next.js a lot. I have also looked at Parcel, esbuild, rsbuild and others. Either they didn’t support our old projects, were too limited in scope (e.g. no HMR), too opinionated or I hit bugs or had questions about their maintenance. I’m sure all of them are great for some people, and I don’t intend to talk badly about any of them!

In the end, the flexibility, speed and trustworthiness of rspack won me over even though I have a love-hate relationship with the Webpack/rspack configuration. We already had a reusable library of configuration snippets for webpack though and moving that library over to rspack was straightforward.

That being said, configuring rspack from scratch is no joke, that’s why tools such as rsbuild exist. If you already know Webpack well or really need the flexibility, going low level can be good.

High-level project structure

The high-level overview is:

Frontend assets live in their own folder, frontend/.
We’re using fabric and rspack, their configuration resides in the root folder of the project as does Django’s manage.py.
The frontend is transpiled and bundled directly into static/ for production and into tmp/ during development.
We use the HTML plugin of rspack to emit snippets containing <link> and <script> tags. The HTML snippet can be included as-is, without any postprocessing.
frontend/ or frontend/static is optionally added to STATICFILES_DIRS so that some of the files from the frontend can easily be referenced in {% static %} tags.

During development:

We use the dev server of rspack/node to handle 127.0.0.1:8000. This server handles requests for frontend assets and the websocket for hot module reloading and proxies everything else to the Django backend running on a different random port.

During deployment:

The assets are compiled to static/ and either rsynced to the server or added to the container separately from the standard ./manage.py collectstatic --noinput.

In production:

Separate cache busting filenames from ManifestStaticFilesStorage and rspack allow us to set far-future expiry headers on all static assets.
I’m serving static assets from the same origin as the website itself. (rspack can be configured for different requirements!)
I don’t worry anymore about duplicating assets which are both referenced from frontend code and backend code. This doesn’t affect many assets after all.
The HTML snippet is loaded once only.

Example configuration

Here’s an example configuration which works well for us. What follows is the rspack configuration itself, building on our snippet library rspack.library.js. We mostly do not change anything in here except for the list of PostCSS plugins:

rspack.config.js:

module.exports = (env, argv) => {
  const { base, devServer, assetRule, postcssRule, swcWithPreactRule } =
    require("./rspack.library.js")(argv.mode === "production")

  return {
    ...base,
    devServer: devServer({ backendPort: env.backend }),
    module: {
      rules: [
        assetRule(),
        postcssRule({
          plugins: [
            "postcss-nesting",
            "autoprefixer",
          ],
        }),
        swcWithPreactRule(),
      ],
    },
  }
}

The default entry point is main and loads frontend/main.js. The rest of the JavaScript and styles are loaded from there.

The HTML snippet loader works by adding WEBPACK_ASSETS = BASE_DIR / "static" to the Django settings and adding the following tags to the <head> of the website, most often in base.html:

{% load webpack_assets %}
{% webpack_assets 'main' %}

The corresponding template tag in webpack_assets.py follows:

from functools import cache

from django import template
from django.conf import settings
from django.utils.html import mark_safe

register = template.Library()

def webpack_assets(entry):
    path = settings.BASE_DIR / ("tmp" if settings.DEBUG else "static") / f"{entry}.html"
    return mark_safe(path.read_text())

if not settings.DEBUG:
    webpack_assets = cache(webpack_assets)
register.simple_tag(webpack_assets)

Last but not least, the fabfile contains the following task definition:

@task
def dev(ctx, host="127.0.0.1", port=8000):
    backend = random.randint(50000, 60000)
    jobs = [
        f".venv/bin/python manage.py runserver {backend}",
        f"HOST={host} PORT={port} yarn run rspack serve --mode=development --env backend={backend}",
    ]
    # Run these two jobs at the same time:
    _concurrently(ctx, jobs)

The fh-fablib repository contains the _concurrently implementation we’re using at this time.

The library which enables the nice configuration above

Of course, the whole library of snippets has to be somewhere. The fabfile automatically updates the library when we release a new version, and the library is the same in all the dozens of projects we’re working on. Here’s the current version of rspack.library.js:

const path = require("node:path")
const HtmlWebpackPlugin = require("html-webpack-plugin")
const rspack = require("@rspack/core")
const assert = require("node:assert/strict")
const semver = require("semver")

assert.ok(semver.satisfies(rspack.rspackVersion, ">=1.1.3"), "rspack outdated")

const truthy = (...list) => list.filter((el) => !!el)

module.exports = (PRODUCTION) => {
  const cwd = process.cwd()

  function swcWithPreactRule() {
    return {
      test: /\.(j|t)sx?$/,
      loader: "builtin:swc-loader",
      exclude: [/node_modules/],
      options: {
        jsc: {
          parser: {
            syntax: "ecmascript",
            jsx: true,
          },
          transform: {
            react: {
              runtime: "automatic",
              importSource: "preact",
            },
          },
          externalHelpers: true,
        },
      },
      type: "javascript/auto",
    }
  }

  function swcWithReactRule() {
    return {
      test: /\.(j|t)sx?$/,
      loader: "builtin:swc-loader",
      exclude: [/node_modules/],
      options: {
        jsc: {
          parser: {
            syntax: "ecmascript",
            jsx: true,
          },
          transform: {
            react: {
              runtime: "automatic",
              // importSource: "preact",
            },
          },
          externalHelpers: true,
        },
      },
      type: "javascript/auto",
    }
  }

  function htmlPlugin(name = "", config = {}) {
    return new HtmlWebpackPlugin({
      filename: name ? `${name}.html` : "[name].html",
      inject: false,
      templateContent: ({ htmlWebpackPlugin }) =>
        `${htmlWebpackPlugin.tags.headTags}`,
      ...config,
    })
  }

  function htmlSingleChunkPlugin(chunk = "") {
    return htmlPlugin(chunk, chunk ? { chunks: [chunk] } : {})
  }

  function postcssLoaders(plugins) {
    return [
      { loader: rspack.CssExtractRspackPlugin.loader },
      { loader: "css-loader" },
      { loader: "postcss-loader", options: { postcssOptions: { plugins } } },
    ]
  }

  function cssExtractPlugin() {
    return new rspack.CssExtractRspackPlugin({
      filename: PRODUCTION ? "[name].[contenthash].css" : "[name].css",
      chunkFilename: PRODUCTION ? "[name].[contenthash].css" : "[name].css",
    })
  }

  return {
    truthy,
    base: {
      context: path.join(cwd, "frontend"),
      entry: { main: "./main.js" },
      output: {
        clean: PRODUCTION,
        path: path.join(cwd, PRODUCTION ? "static" : "tmp"),
        publicPath: "/static/",
        filename: PRODUCTION ? "[name].[contenthash].js" : "[name].js",
        // Same as the default but prefixed with "_/[name]."
        assetModuleFilename: "_/[name].[hash][ext][query][fragment]",
      },
      plugins: truthy(cssExtractPlugin(), htmlSingleChunkPlugin()),
      target: "browserslist:defaults",
    },
    devServer(proxySettings) {
      return {
        host: "0.0.0.0",
        hot: true,
        port: Number(process.env.PORT || 4000),
        allowedHosts: "all",
        client: {
          overlay: {
            errors: true,
            warnings: false,
            runtimeErrors: true,
          },
        },
        devMiddleware: {
          headers: { "Access-Control-Allow-Origin": "*" },
          index: true,
          writeToDisk: (path) => /\.html$/.test(path),
        },
        proxy: [
          proxySettings
            ? {
                context: () => true,
                target: `http://127.0.0.1:${proxySettings.backendPort}`,
              }
            : {},
        ],
      }
    },
    assetRule() {
      return {
        test: /\.(png|webp|woff2?|svg|eot|ttf|otf|gif|jpe?g|mp3|wav)$/i,
        type: "asset",
        parser: { dataUrlCondition: { maxSize: 512 /* bytes */ } },
      }
    },
    postcssRule(cfg) {
      return {
        test: /\.css$/i,
        type: "javascript/auto",
        use: postcssLoaders(cfg?.plugins),
      }
    },
    sassRule(options = {}) {
      let { cssLoaders } = options
      if (!cssLoaders) cssLoaders = postcssLoaders(["autoprefixer"])
      return {
        test: /\.scss$/i,
        use: [
          ...cssLoaders,
          {
            loader: "sass-loader",
            options: {
              sassOptions: {
                includePaths: [path.resolve(path.join(cwd, "node_modules"))],
              },
            },
          },
        ],
        type: "javascript/auto",
      }
    },
    swcWithPreactRule,
    swcWithReactRule,
    resolvePreactAsReact() {
      return {
        resolve: {
          alias: {
            react: "preact/compat",
            "react-dom/test-utils": "preact/test-utils",
            "react-dom": "preact/compat", // Must be below test-utils
            "react/jsx-runtime": "preact/jsx-runtime",
          },
        },
      }
    },
    htmlPlugin,
    htmlSingleChunkPlugin,
    postcssLoaders,
    cssExtractPlugin,
  }
}

Closing thoughts

Several utilities from this library aren’t used in the example above, for example the sassRule or the HTML plugin utilities which are useful when you require several entry points on your website, e.g. an entry point for the public facing website and an entry point for a dashboard used by members of the staff.

Most of the code in here is freely available in our fh-fablib repo under an open source license. Anything in this blog post can also be used under the CC0 license, so feel free to steal everything. If you do, I’d be happy to hear your thoughts about this post, and please share your experiences and suggestions for improvement – if you have any!