Skip to content

Deprecation plan: remove JS and CSS in favor of Script and Stylesheet #44

Open

Description

@matthiask

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 JS and CSS as a whole: every call and every isinstance/issubclass check warns, pointing to Script/Stylesheet/InlineStyle. Their old forms (attrs dict, positional media, inline=True) keep working.
  • Keep the implicit media="all" of CSS(href). It is not cosmetic: Django >= 6.1 wraps "a.css" in css={"all": [...]} into Stylesheet("a.css", media="all"), and attribute-aware equality means a Stylesheet without media renders a second time. The warning says to use Stylesheet(href, media="all").
  • Keep render(nonce=) of Media, JSON and ImportMap deprecated 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/Stylesheet throughout; 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>=4 and put the import map into js lists, which raises a TypeError since 5.0a1, so a stable 5.0 breaks them. Their pre-releases already use Media(importmap=...) and require >=5.0a1. Accepting import maps in js lists 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 ImportMap while at it.

6.0

Done on the experimental-6.0 branch except for the release itself.

  • Remove JS and CSS (no aliases) and the _ProducesAsset metaclass.
  • Remove the remaining render(nonce=) and full import map deprecations.
  • Remove the ImportMap-in-js-lists check in Media._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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions