Django ESM

Django ESM: NextGen JavaScript ESM module support for Django

NextGen JavaScript ESM module support for Django.

Highlights

😌 easy transition
⚡️ smart cache busting
📦 no more bundling
☕️ native ESM support
📍 local vendoring with npm

Setup

Install the package and add it to your INSTALLED_APPS setting:

pip install django-esm[whitenoise]

First, add django_esm to your INSTALLED_APPS settings:

# settings.py
INSTALLED_APPS = [
    # …
    "django_esm",  # add django_esm before staticfiles
    "django.contrib.staticfiles",
]

Optionally: If you are using whitenoise you will need to modify your WSGI application.

import os
import pathlib

from django.core.wsgi import get_wsgi_application

from django_esm.wsgi import ESM

BASE_DIR = pathlib.Path(__file__).parent.parent

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")

application = ESM(get_wsgi_application())

Finally, add the import map to your base template:

<!-- base.html -->
<!DOCTYPE html>
{% load esm %}
<html lang="en">
<head>
  <script type="importmap">{% importmap %}</script>
  <title>Django ESM is awesome!</title>
</head>
</html>

That's it! Remember to run npm install and python manage.py esm --watch.

Treeshaking

By default, every package entry point ends up in the import map. Pass --treeshake to drop entry points that are not reachable from your project's own entry points, keeping only the outputs actually imported:

python manage.py esm --watch --treeshake

Usage

You can now import JavaScript modules in your Django templates:

<!-- index.html -->
{% block content %}
  <script type="module">
    import "lit"
  </script>
{% endblock %}

Form.media

To use your importmap in Django forms, you can use the Form.media attribute:

# forms.py
from django import forms
from django_esm.forms import ImportESModule


class MyForm(forms.Form):
    name = forms.CharField()

    class Media:
        js = [ImportESModule("@sentry/browser")]

Now {{ form.media.js }} will render to like this:

<script type="module">import '@sentry/browser'</script>

Private modules

You can also import private modules from your Django app:

<!-- index.html -->
{% block content %}
  <script type="module">
    import "#myapp/js/my-module.js"
  </script>
{% endblock %}

To import a private module, prefix the module name with #. You need to define your private modules in your package.json file:

{
  "imports": {
    "#myapp/script": "./myapp/static/js/script.js",
    // You may use trailing stars to import all files in a directory.
    "#myapp/*": "./myapp/static/js/*"
  }
}

How it works

Django ESM works via native JavaScript module support in modern browsers. It uses the import map to map module names to their location on the server.

Here is an example import map:

{
  "imports": {
    "htmx.org": "/static/htmx.org/dist/htmx.min.js"
  }
}

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_esm-0.9.0.tar.gz (9.1 kB view details)

Uploaded Aug 21, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

django_esm-0.9.0-py3-none-any.whl (10.1 kB view details)

Uploaded Aug 21, 2026 Python 3

File details

Details for the file django_esm-0.9.0.tar.gz.

File metadata

Download URL: django_esm-0.9.0.tar.gz
Upload date: Aug 21, 2026
Size: 9.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for django_esm-0.9.0.tar.gz
Algorithm	Hash digest
SHA256	`ce69d19a530b78f8f1186db63a22c5e8666dcec424584e1d2dfae8099e3cea13`
MD5	`6256e41fccee93400272eabc8138f68f`
BLAKE2b-256	`410506ad1e408e87d9a72f1b39b5b31ff99df7b25dd6c3e4258eace00f4e6fab`

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_esm-0.9.0.tar.gz:

Publisher: release.yml on codingjoe/django-esm

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: django_esm-0.9.0.tar.gz
- Subject digest: ce69d19a530b78f8f1186db63a22c5e8666dcec424584e1d2dfae8099e3cea13
- Sigstore transparency entry: 2550869211
- Sigstore integration time: Aug 21, 2026
Source repository:
- Permalink: codingjoe/django-esm@39260a471ab6e255fe36e21255ca456bf96e6479
- Branch / Tag: refs/tags/0.9.0
- Owner: https://github.com/codingjoe
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@39260a471ab6e255fe36e21255ca456bf96e6479
- Trigger Event: release