Install & Compatibility
Where this runs
tested against v4.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.774s · 66.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.5s · import 0.694s · 67MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
JS
✓ from js_asset import JS
CSS
✓ from js_asset import CSS
JSON
✓ from js_asset import JSON
Define a custom widget or form and declare your JavaScript, CSS, or JSON assets within its inner `Media` class using `JS`, `CSS`, and `JSON` objects. This allows for passing additional HTML attributes to script/style tags or embedding JSON data directly. The `forms.Media` is then rendered in your template using `{{ form.media }}`.
from django import forms
from js_asset import JS, CSS, JSON
# Example form demonstrating usage of JS, CSS, and JSON objects in Media
class MyWidget(forms.TextInput):
class Media:
js = [
# Embed JSON data directly into a script tag
JSON({"setting": "value", "number": 123}, id="my-widget-config"),
# Include a JavaScript module with custom attributes
JS("my_app/js/script.js", {"type": "module", "data-priority": "high"}),
]
css = {
"all": [
# Include an external stylesheet
CSS("my_app/css/style.css"),
# Include inline CSS directly
CSS("p { color: blue; }", inline=True),
]
}
class MyForm(forms.Form):
my_field = forms.CharField(widget=MyWidget)
# In a Django template, you would render the media like this:
# {{ form.media }}
Debug
Known issues
gotchaDjango 5.2+ introduces its own `Script` object for `forms.Media` with similar functionality. While `django-js-asset` offers a 'slightly different API' and extended features (like CSS/JSON objects and importmap support), users upgrading to Django 5.2 should be aware of the native option and choose the library that best fits their needs.fixReview Django 5.2 documentation for `forms.Media`'s native `Script` object. Decide whether to migrate to Django's native implementation or continue using `django-js-asset` for its extended features like CSS/JSON/Importmap handling and broader Django version support.
affects: Django >=5.2
deprecatedThe importmap support provided by `django-js-asset` is explicitly labeled as 'extremely experimental' and browser support for multiple importmaps is not generally available or standardized. Relying heavily on this feature in production is cautioned.fixUse the importmap feature with caution, particularly in production environments. Monitor browser compatibility and web standards for importmaps. Consider alternative asset bundling or management strategies for critical applications.
affects: All versions
gotchaWhen using the experimental importmap feature, if you add `importmap` to `forms.Media(js=[...])` and also include `{{ importmap }}` directly in your base templates (e.g., for Django admin), the importmap definition might be duplicated in the rendered HTML.fixTo avoid duplication, either ensure that `{{ importmap }}` is only rendered if not already included via `form.media`, or implement different widget classes for admin vs. public site if the importmap setup differs. affects: All versions (with importmap feature)
gotchaThe `static()` function's implementation can vary between Django versions, especially concerning `django.contrib.staticfiles`. `django-js-asset` provides its own `js_asset.static` helper to ensure correct static file URL resolution across supported Django versions.fixAlways use `js_asset.static` when defining paths if you require compatibility across a wide range of Django versions or encounter issues with standard `django.contrib.staticfiles.static` resolving paths.
affects: All versions, especially older Django versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'js_asset'
The `django-js-asset` package is either not installed in the Python environment or not added to the `INSTALLED_APPS` list in your Django `settings.py` file.
fixFirst, ensure the package is installed: `pip install django-js-asset`. Then, add `'js_asset'` to your `INSTALLED_APPS` list in `settings.py`.
ImportError: cannot import name 'JS' from 'js_asset'
You are trying to import the `JS` object (or `CSS`, `JSON`) from `js_asset` but there is a typo in the import statement, or the Python environment cannot find the module correctly.
fixCorrect the import statement to `from js_asset import JS` (or include `CSS`, `JSON` if needed, e.g., `from js_asset import JS, CSS, JSON`).
Uncaught ReferenceError: [function name] is not defined
JavaScript or CSS assets defined using `django-js-asset`'s `JS`, `CSS`, or `JSON` objects within `forms.Media` are not being rendered in your Django template, often because `{{ form.media }}` is missing or incorrectly placed.
fixEnsure that `{{ form.media }}` is included in your Django template. For CSS, place it within the `<head>` section; for JavaScript, it's typically placed before the closing `</body>` tag. NameError: name 'importmap' is not defined (in template) or ImportError: cannot import name 'importmap' from 'js_asset' (in Python)
The experimental `importmap` feature's context processor is not enabled in your Django settings, or the `importmap` object is not correctly imported in your Python code, leading to it being unavailable in templates or Python.
fixFor template usage, add `'js_asset.context_processors.importmap'` to `TEMPLATES['OPTIONS']['context_processors']` in your `settings.py` and ensure `{{ importmap }}` is present in your base template. For Python code, use `from js_asset import importmap`. Upgrade
Version history
4.1.0latest on PyPI · released Aug 28, 2026
Audit
Dependencies
No dependency data recorded yet.