Integrate HTML importmaps with Django for modern web development
Project description
dj-importmap: HTML importmaps like a boss!
dj-importmaps is designed to help you declare your importmaps
in a djangonic way.
Show me an example!
For instance, the following:
# importmaps.py in one of your Django apps
from importmap import static
importmaps = {
# From your static files
"SearchComponent": static("js/search-component.js"),
# Or declare directly from a CDN
"StimulusJS": "https://unpkg.com/stimulus@3.2.2/dist/stimulus.umd.js"
}
This will generate the following:
<script type="importmap">
{
"imports": {
"SearchComponent": "/static/js/search-component.js",
"StimulusJS": "https://unpkg.com/stimulus@3.2.2/dist/stimulus.js"
}
}
</script>
And now, you can use JS modules like nothing:
import {Controller, Application} from "StimulusJS"
import * as Search from "SearchComponent"
export default class {
// ...
}
Cool! How do I use it?
-
Install from PyPI
pip install dj-importmap
-
Add to your `INSTALLED_APPS:
INSTALLED_APPS = [ # ... "importmap" # ... ]
-
Create a
importmaps.pynext to your rooturls.pyor in any of your Django app:importmaps = { # ... }
-
Add
{% importmap %}to you template:{% load importmap %} <!doctype html> <html lang="fr" data-fr-scheme="light"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>…</title> <!-- This must be placed before the very first <script> in order to work --> {% importmap %} </head> </html>
You're good to go!
Advanced usage
Per-app importmaps.py
You can declare an different importmap for your whole Django project as well as for each application. By default,
when you call {% importmap %} in a template, dj-importmap will merge them all in the order the app were declared in
INSTALLED_APPS, the latter take precedence over the former.
If you want to use a importmaps.py declared in a spcific app, you can use {% importmap "app_name" %} where
app_name corresponds to the AppConfig.name declared in your Django's app apps.py. In this case, {% importmap %}
will merge the app's importmaps.py to the project importmaps.py, if exists.
dj-importmap expects to find the project's importmaps.py next to the project's urls.py, as declared in
settings.ROOT_URLCONF.
Alternatively, if settings.ROOT_IMPORTMAPCONF is declared and points to a valid Python module, dj-importmap will
source that one as the project's root importmap.
Additionnal HTML attribute to the generated <script>
{% importmap %} accepts kwargs to let you add arbitrary HTML attributes to the generated <script>:
{% importmap defer="true" %}
<!-- Using attributes with chars unauthorized in Django templates -->
{% importmap defer="true" "yes" as "data-is-cool" %}
<!-- Attribute without value -->
{% importmap "defer" "yes" as "data-is-cool" %}
Note: trying to specify an HTML attribute with no value as the first argument of {% importmap %} creates an
ambiguity with the optionam app name. In this case, {% importmap %} will raise a TemplateSyntaxError.
{% importmap %} offer the possibility to suppress this ambiguity by setting a series of dashes as its first
argument:
<!-- TemplateSyntaxError: ambiguity -->
`{% importmap "defer" %}`
<!-- Ok -->
{% importmap "--" "defer" %}
Dev
Release
To perform a release, fill the CHANGELOG.md with changes, and update package's __version__.
Open a new PR with these changes. When merge, you can publish a new release on Github.
Then you can publish on PyPI with uv build and uv publish.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file dj_importmap-1.0.0.tar.gz.
File metadata
- Download URL: dj_importmap-1.0.0.tar.gz
- Upload date:
- Size: 18.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.7.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6d2ae02d0e66fc34d73d6341670566452d712110f64fc00309792beac7da6af5
|
|
| MD5 |
9a44af29ffabf86ffd7190e892dc32a9
|
|
| BLAKE2b-256 |
e334a29ec305ce16002af6eaa59a885ecc395a0ebc778e24f052b28c6d9f392f
|
File details
Details for the file dj_importmap-1.0.0-py3-none-any.whl.
File metadata
- Download URL: dj_importmap-1.0.0-py3-none-any.whl
- Upload date:
- Size: 18.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.7.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6d892504d6199fa4904ffffb9c7ba490708bb263ed24372618b374fc1d297187
|
|
| MD5 |
fffedd110352df41daccc91321980173
|
|
| BLAKE2b-256 |
b72071e19afe963e2a81433145189afa66632986829a0e70a78540f6e8fb045d
|
