Repository navigation
Description
JS and CSS produce Django's own Script and Stylesheet (backported where Django lacks them). Instead of turning them into aliases, they are deprecated as a whole in 5.0 and removed in 6.0; code should use the canonical Script and Stylesheet names. This issue plans when the shims go away.
Current shims
| Shim | Introduced | Known public users |
|---|---|---|
JS(src, {...}) / JS(src, attrs={...}) |
original API | django-ckeditor, django-mptt (< 0.20), django-tree-queries (< 0.27), feincms3 (< 6.1.1), django-prose-editor (< 0.28a9), django-content-editor (< 9.1a3), django-json-schema-editor (< 0.15a4) |
CSS(href, "print") (positional media) |
3.1 | none found |
CSS(..., attrs={...}) |
5.0a1 | none found |
CSS(..., inline=True) → InlineStyle |
3.0 | none found |
CSS(href) adding media="all" implicitly |
3.1 | none found |
ImportMap({"imports": ..., ...}) (full import map) |
before 5.0 | none found (django-prose-editor and django-content-editor use the imports-only form) |
ImportMap.render(nonce=), JSON.render(nonce=) |
before 4.2 | none found |
Media.render(nonce=) |
4.0 | none found |
ImportMap in js lists raising a helpful TypeError |
5.0a1 | migration aid, not a shim |
"Known public users" is from GitHub code search (public default branches only).
Constraint: already released downstream versions
django-mptt before 0.20 and django-tree-queries before 0.27 don't constrain django-js-asset, and django-ckeditor requires >=2.0. Their existing releases will resolve to whatever js-asset is newest, so removing the JS dict form breaks projects which upgrade js-asset but not those packages. New downstream releases can't change that.
The new form JS(src, **attrs) doesn't work with js-asset 4.x (JS(js, attrs=None)), so downstream releases switching to it must require django-js-asset>=5.0. from js_asset import Script avoids that: js-asset has exported Script(src, **attrs) (a backport below Django 5.2) since 4.0, so it only needs django-js-asset>=4.0.
Which packages need js-asset at all?
django.forms.Script exists since Django 5.2, Stylesheet since 6.1. None of the packages uses CSS from js-asset, so only Script matters. Django 4.2 is out of support since April 2026, so raising their floor to 5.2 is reasonable:
| Package | Django floor | Uses from js-asset | With Django >= 5.2 |
|---|---|---|---|
| django-mptt | 4.2 | Script since 0.20 (django-js-asset>=4.0) |
django.forms.Script, drop js-asset |
| django-tree-queries | 4.2 since 0.27 (js-asset is the optional admin extra) |
Script since 0.27 (django-js-asset>=4.0) |
django.forms.Script, drop js-asset and the extra |
| feincms3 | 4.2 | Script since 6.1.1 |
django.forms.Script, drop js-asset |
| django-ckeditor | 3.2 | JS |
django.forms.Script, drop js-asset |
| django-prose-editor | 4.2 | Script since 0.28a9, ImportMap (imports-only form), Media, static_lazy |
Script, js-asset for import maps |
| django-content-editor | 4.2 | Script since 9.1a3, JSON, ImportMap (imports-only form), Media |
Script, js-asset for import maps and JSON |
| django-json-schema-editor | 4.2 | Script since 0.15a4, ImportMap (imports-only form), Media |
Script, js-asset for import maps |
Packages which keep supporting Django 4.2 use from js_asset import Script with django-js-asset>=4.0 instead.
Plan
5.0 (final)
Minimal breaking changes: nothing is removed beyond what the 5.0a1/a2 pre-releases already changed (import maps, attribute conflicts in render(attrs=), ./ paths in import maps). Everything else warns and keeps working until 6.0.
- Deprecate
JSandCSSas a whole: every call and everyisinstance/issubclasscheck warns, pointing toScript/Stylesheet/InlineStyle. Their old forms (attrs dict, positional media,inline=True) keep working. - Keep the implicit
media="all"ofCSS(href). It is not cosmetic: Django >= 6.1 wraps"a.css"incss={"all": [...]}intoStylesheet("a.css", media="all"), and attribute-aware equality means aStylesheetwithoutmediarenders a second time. The warning says to useStylesheet(href, media="all"). - Keep
render(nonce=)ofMedia,JSONandImportMapdeprecated until 6.0. They were public in 4.x and only deprecated during the 5.0 pre-releases, so 4.x users never saw a warning in a final release. - Add
RemovedInDjangoJsAsset60Warning(DeprecationWarning)and use it for all deprecations, so projects can turn exactly these into errors. - README uses
Script/Stylesheetthroughout; changelog lists the deprecations. - Release 5.0 together with stable releases of django-prose-editor, django-content-editor and django-json-schema-editor. Their current stable releases (0.27.3, 9.0.2, 0.14.1) require
django-js-asset>=4and put the import map intojslists, which raises aTypeErrorsince 5.0a1, so a stable 5.0 breaks them. Their pre-releases already useMedia(importmap=...)and require>=5.0a1. Accepting import maps injslists again was considered and rejected: there should be one way to declare them, and import maps must always be merged into one.
Downstream (during 5.x)
Switch to Script(src, **attrs), either django.forms.Script (Django >= 5.2, drop js-asset where possible) or from js_asset import Script (django-js-asset>=4.0), and release:
- django-ckeditor (
ckeditor/widgets.py) - django-mptt (
mptt/admin.py) - django-tree-queries (
tree_queries/admin.py) - feincms3 (
feincms3/inline_ckeditor.py, two call sites) - django-prose-editor (
django_prose_editor/widgets.py, docs) - django-content-editor (
content_editor/admin.py) - django-json-schema-editor (
django_json_schema_editor/forms.py) - Check them for the full import map form of
ImportMapwhile at it.
6.0
Done on the experimental-6.0 branch except for the release itself.
- Remove
JSandCSS(no aliases) and the_ProducesAssetmetaclass. - Remove the remaining
render(nonce=)and full import map deprecations. - Remove the
ImportMap-in-js-lists check inMedia._js. - Keep
RemovedInDjangoJsAsset60Warning(no longer emitted) so warning filters referencing it don't fail on import; remove it in 6.1. - Changelog: projects stuck on old downstream releases pin
django-js-asset<6. - Timing: not tied to downstream adoption (all listed packages have released the switch). At least one feature-release cycle of 5.x warnings, roughly six months after 5.0 final.
Open questions
None at the moment. Decided: no removals in 5.0 final; JS/CSS removed instead of aliased in 6.0; 6.0 follows the usual schedule (see above).
Activity
Use Script instead of the deprecated JS attrs dict
Use Script instead of JS with an attributes dict
Use Script instead of the deprecated JS attrs dict, require Django 4.2
Use Script instead of the deprecated JS attrs dict
Use Script instead of the deprecated JS attrs dict
[-]Deprecation plan: turn JS and CSS into aliases of Script and Stylesheet[/-][+]Deprecation plan: remove JS and CSS in favor of Script and Stylesheet[/+]Use Script instead of the deprecated JS attrs dict