https://github.com/codingjoe/django-esm
Lightweight JavaScript ESM module loader for Django.
https://github.com/codingjoe/django-esm
assets django esm esmodules import importmaps javascript python rollup staticfiles webpack
Last synced: 5 months ago
JSON representation
Lightweight JavaScript ESM module loader for Django.
- Host: GitHub
- URL: https://github.com/codingjoe/django-esm
- Owner: codingjoe
- License: bsd-2-clause
- Created: 2023-12-21T12:59:50.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-18T14:46:15.000Z (7 months ago)
- Last Synced: 2025-05-18T15:28:11.458Z (7 months ago)
- Topics: assets, django, esm, esmodules, import, importmaps, javascript, python, rollup, staticfiles, webpack
- Language: Python
- Homepage:
- Size: 741 KB
- Stars: 9
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Django ESM
NextGen JavaScript ESM module support for Django.
[](https://pypi.python.org/pypi/django-esm/)
[](https://codecov.io/gh/codingjoe/django-esm)
[](https://raw.githubusercontent.com/codingjoe/django-esm/master/LICENSE)
## 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:
```bash
pip install django-esm[whitenoise]
```
First, add `django_esm` to your `INSTALLED_APPS` settings:
```python
# 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.
```python
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:
```html
{% load esm %}
{% importmap %}
Django ESM is awesome!
```
That's it!
Remember to run `npm install` and `python manage.py esm --watch`.
## Usage
You can now import JavaScript modules in your Django templates:
```html
{% block content %}
import "lit"
{% endblock %}
```
### Form.media
To use your importmap in Django forms, you can use the `Form.media` attribute:
```python
# 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:
```html
import '@sentry/browser'
```
### Private modules
You can also import private modules from your Django app:
```html
{% block content %}
import "#myapp/js/my-module.js"
{% endblock %}
```
To import a private module, prefix the module name with `#`.
You need to define your private modules in your `package.json` file:
```json
{
"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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)
to map module names to their location on the server.
Here is an example import map:
```json
{
"imports": {
"htmx.org": "/static/htmx.org/dist/htmx.min.js"
}
}
```