DEP0022 -- Adding import maps to Django by matthiask · Pull Request #101 · django/deps

matthiask · 2025-02-14T16:35:30Z

* origin/main: Removed SC voting language from the document. Updated language for annual release cadence due to DEP 20. (django#120) Marked DEP 20's status as Accepted. (django#116) Use X in Deprecation Policy section of DEP 20 for clarity. (django#115) DEP 20 Adopt Annual Release Cycle (django#109) DEP 0019 - Technical governance for the Django project (django#107) Finalized DEP 0018 Dictionary-based MAILERS (ticket-35514) DEP 0018 Dictionary-based EMAIL_PROVIDERS (ticket-35514) (django#105) Marked DEP 0014 Background Workers as final Extended project template (django#98) Add django command (django#100) Moved DEP 0011 to superseded (django#102)

…ject all the time

…list

rik · 2026-09-30T16:39:39Z

+Browser support for multiple import maps is spotty at the time of writing.
+Chromium and Safari support multiple import maps since early 2025, but Firefox
+still only uses the first import map and ignores all others (see `MDN
+<https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap>`__).
+This means that when we want to use import maps, we have to ensure that there's
+only a single import map in the output or wait for years until we can use this
+feature.


Mozilla has implemented this feature and is discussing enabling it. Given the many related websites listed as broken, I'm pretty sure this will be enabled soon (I'd say in the next 6 months). There's also a proposal to include it in Interop 2027.

So I think the design constraint of only emitting one import map can be relaxed.

Thanks, that's very interesting! I didn't know that we're already at that stage of browser support.

Until a feature is baseline available we still have to wait for ~30 months. That's quite a long time so if we get this supported within a few months or something like that it is still worth doing.

30 months is two and a half years, which means June 2029 for Baseline Widely Available. Meaning this constraint will only be useful in two versions of Django at best (Django 6.2 and Django 2028). Many more future versions of Django will need to adapt to this API constraint (or have a depreciation plan) even though there won't be any practical use case anymore.

I'm mentioning all this because of the extra contributor work that could be avoided if it's considered an ok tradeoff.

I think I'm a bit more conservative in the way I'm interpreting baseline availability. To me it means I don't have to think about it too much when the support is somewhat important. It doesn't mean I get to use it if the availability is central to the project because I definitely am serving environments where browsers and devices are lagging behind.

Not having browser support for multiple import maps isn't a visual glitch or something comparable, it's a total showstopper.

TLDR: some people would have to wait significantly longer than 30 months.

I added a paragraph to the Rationale section with my reasoning for supporting this in Django (a6d9a32). The import map support doesn't have to be removed later, it just becomes less essential.

Thanks for the bugzilla links!

matthiask · 2026-10-01T05:42:42Z

@jacobtylerwalls Can I ask you to apply the Django on the Med label on this PR as well? It has been open for much longer but most of the work was done last week. Thanks in advance :)

codingjoe

@matthiask can I suggest adding type hints to the new APIs you are proposing? Even if they don't make it into production code, they help with the reading. For example, Importmap(integrity) expects a dict, whereas Script(integrit) would expect a string.

It will also help to focus the docstrings on their external behavior, rather than on their arguments.

matthiask · 2026-10-04T17:00:36Z

@matthiask can I suggest adding type hints to the new APIs you are proposing? Even if they don't make it into production code, they help with the reading. For example, Importmap(integrity) expects a dict, whereas Script(integrit) would expect a string.

It will also help to focus the docstrings on their external behavior, rather than on their arguments.

Yes, sure! I just did that now.

codingjoe

I didn't do a full review yet but left some notes and tried implementing it in my package.

I used:

import typing


@typing.runtime_checkable
class ImportMapLike(typing.Protocol):
    """
    Structural type of an import map.
    """
    imports: Mapping[str, str]
    scopes: Mapping[str, Mapping[str, str]]
    integrity: Mapping[str, str]


# my concrete backport
def __or__(self, other):
   if isinstnace(other, ImportMapLike):
      # merging mappsings

My main concern is ImportMap.render(). Should it return a script-tag, or the import map JSON?

Importantly, the importmap-tag is subject to CSP. In my project is don't use neither nonce, nor inline-script for their legitimate security limitations. (Thanks for pointing those out @adamchainz).

Instead I use rendered JSON to add an explicit sha-512 digest to my script-src policy. See also: https://github.com/codingjoe/relay/blob/94847a54b2b4aaaa5b4546e958551d184c018647/root/middleware.py#L11-L44

codingjoe · 2026-10-07T14:09:46Z

+        Paths in ``imports`` and ``scopes`` are resolved when rendering, like
+        ``Script`` paths: Relative paths are passed through ``static()``, while
+        URLs with a scheme and paths starting with ``/``, ``./`` or ``../`` are
+        used as they are. Paths ending with ``/`` are used as they are too,
+        since static file storages cannot resolve directories. Scope prefixes
+        are never resolved.


MediaAsset uses if self._path.startswith(("http://", "https://", "/")): so relative paths will be resolved with static.

Thanks! I think we probably should do the same thing Django does in HashedFilesMixin. Passing through ./ and ../ came from django-js-asset and I don't think that's very useful in this context.

EDIT: Not exactly the same, since HashedFileMixin also strips STATIC_URL if files already have it and still processes them. I don't think we should copy that feature here.

codingjoe · 2026-10-07T14:12:09Z

+        def render(self, *, attrs: dict[str, str | bool] | None = None) -> str:
+            """
+            Render the ``<script type="importmap">`` element. The import map
+            with resolved paths is serialized as JSON and escaped using
+            ``json_script()``. ``attrs`` are added like in
+            ``MediaAsset.render()`` (raising a ``ValueError`` for conflicting
+            attributes), e.g. for CSP nonces.
+            """


Importmaps do need a nonce, but not SRI integrity. Still, an integrity method would be great to use a hashed CSP instead of a nonce.

Good point. I added a proposal for adding a csp_hash method or something like that to the ImportMap object. integrity would be a fitting name since it returns the same data structure as proposed in DEP0021, but might be misleading. I'm not sure.

codingjoe · 2026-10-07T14:13:09Z

+        def __eq__(self, other: object) -> bool:
+            """
+            Import maps are equal when their data and attributes are equal.
+            """
+
+        def __or__(self, other: ImportMap) -> ImportMap:
+            """
+            Return a new import map combining this import map and ``other``.
+
+            ``imports``, ``integrity`` and each scope in ``scopes`` are merged
+            like dictionaries, so entries of ``other`` replace entries of this
+            import map. Attributes are merged the same way. Neither import map
+            is modified.
+            """


I think you don't need a docstring here, those methods are fairly self-explainatory ;)

Good point, thanks!

codingjoe · 2026-10-07T15:54:14Z

+        For paths resolved through ``static()``, ``integrity`` metadata is added
+        automatically if the static files storage supports it (see `Deferred
+        functionality`_). ``integrity`` is only needed for other modules, e.g.
+        modules loaded from a CDN.


This would also be limited to relative paths only, which are locaded inside staticfiles.

Yes. I reworded that slightly to explain that specifying the integrity explicitly is only needed for files loaded from elsewhere.

…ld be done in Django

matthiask · 2026-10-13T06:10:13Z

I didn't do a full review yet but left some notes and tried implementing it in my package.

I used:

import typing


@typing.runtime_checkable
class ImportMapLike(typing.Protocol):
    """
    Structural type of an import map.
    """
    imports: Mapping[str, str]
    scopes: Mapping[str, Mapping[str, str]]
    integrity: Mapping[str, str]


# my concrete backport
def __or__(self, other):
   if isinstnace(other, ImportMapLike):
      # merging mappsings

I haven't used protocols often yet, but using protocols makes sense to me. I worry a bit that this introduces some additional complexity to the DEP itself (typing.Protocol isn't used anywhere in Django right now) so I am hesitant to propose it.

My main concern is ImportMap.render(). Should it return a script-tag, or the import map JSON?

Importantly, the importmap-tag is subject to CSP. In my project is don't use neither nonce, nor inline-script for their legitimate security limitations. (Thanks for pointing those out @adamchainz).

Instead I use rendered JSON to add an explicit sha-512 digest to my script-src policy. See also: https://github.com/codingjoe/relay/blob/94847a54b2b4aaaa5b4546e958551d184c018647/root/middleware.py#L11-L44

Looks great, thanks for the link!

I think it should return a full tag as the media assets do. I don't feel too strongly about that though. I added the deferred proposal to add a csp_hash method to the import map object which you could use instead of having to extract the map from the rendered HTML again. 223b1ac also mentions that this method could return the IntegrityMetadataList from DEP0021, but proposes using csp_hash and not integrity because the later might be confusing as well, since import maps don't need SRI integrity (as you write).

LilyFirefly · 2026-10-13T07:16:13Z

runtime_checkable might be an attractive nuisance, unless it has improved in recent releases: https://discuss.python.org/t/is-there-a-downside-to-typing-runtime-checkable/20731

matthiask · 2026-10-14T05:58:27Z

runtime_checkable might be an attractive nuisance, unless it has improved in recent releases: https://discuss.python.org/t/is-there-a-downside-to-typing-runtime-checkable/20731

Thanks! That's interesting. That's another reason to leave it out for now. Adding a factory function which converts an ImportMapLike to an ImportMap would be easy to add if we need it.

…ile rendering

codingjoe · 2026-10-14T12:44:55Z

I don't know if I linked this here before, but just in case: mdn/browser-compat-data#30774
However, this is no holdback for us. Just DEP21 and DEP22 in conjunction will not work until the Safari patch is readily available.

thibaudcolas and others added 4 commits February 14, 2025 16:47

Copy template to new draft DEP doc

b9b6451

Add first draft content

07962bd

Continue working on the DEP

a968cbd

Remove a copy-pasted and confusing comment

e0ca330

matthiask mentioned this pull request Feb 14, 2025

Fixed #36104 -- Returned NotImplemented in Media.__add__ for non-Media RHS. django/django#19058

Closed

6 tasks done

lb- mentioned this pull request Apr 6, 2025

Clarify that the insert_editor_js hook covers all core model editing/creation views wagtail/wagtail#13021

Closed

matthiask mentioned this pull request Apr 10, 2025

Any thoughts on content security policy / django-csp? feincms/django-prose-editor#34

Closed

matthiask added 9 commits September 23, 2026 11:52

Review some parts of the DEP

157cd15

MOre

afb0864

More

4a0b1c9

Update the metadata

0d2afde

Flesh out the document some more

5f7cefd

Assisted rework (still very much a draft)

25e9d2d

More assistance

0363c15

More details

fc1a6be

matthiask changed the title ~~Rejuvenating form media~~ Adding import maps to Django Sep 24, 2026

matthiask added 3 commits September 24, 2026 11:56

Updates

66abf82

Address comments before reading through everything myself

b8c6c3f

Proofread

943775b

matthiask marked this pull request as ready for review September 24, 2026 10:35

matthiask mentioned this pull request Sep 24, 2026

Adding import maps to Django django/new-features#214

Open

1 task done

Use 0022

871a7fc

matthiask changed the title ~~Adding import maps to Django~~ DEP0022 -- Adding import maps to Django Sep 24, 2026

matthiask added 6 commits September 24, 2026 14:44

Mention DEP0021

ca37121

Docstrings instead of implementation

d14cbf1

Address collisions

616294c

Avoid having to wrap import map entries in the top level 'imports' ob…

d07cbc5

…ject all the time

Add a more complete example

a0cdc7e

Rewrite the whole thing: Keep importmaps separate from the JS assets …

6045777

…list

matthiask added 6 commits September 25, 2026 11:47

Do not repeat information which can be read at MDN

b071622

Tweaking

d3f50f4

Reorder, expand the example

4c04010

Avoid wrapping there

1eeb43d

Tweak after rereading

0b77993

Improve the motivation

4476ea7

matthiask mentioned this pull request Sep 28, 2026

DEP0021 -- Subresource Integrity (SRI) #122

Open

rik reviewed Sep 30, 2026

View reviewed changes

LilyFirefly added the Django on the Med 🏖️ label Oct 1, 2026

codingjoe reviewed Oct 4, 2026

View reviewed changes

Add type hints to the function signatures

cb74558

codingjoe reviewed Oct 7, 2026

View reviewed changes

matthiask added 5 commits October 13, 2026 07:58

Address the import map merging support, and why I still think it shou…

a6d9a32

…ld be done in Django

Prune the docstrings a bit

9ab2ad0

Reword the sentence regarding explicit integrity specifications

e1c3330

Do not pass through ./, ../ etc. to align with Django

60c4e78

Address the hashed CSP issue by deferring it (for now)

223b1ac

matthiask added 4 commits October 14, 2026 08:12

Disallow passing a type attribute to the import map constructor or wh…

1954e57

…ile rendering

No change intended regarding data: URLs

4f82bf3

Explicitly state that I don't intend to add data accessors (for now)

008300d

Handling scopes nicely is out of scope

5b35eea

Conversation

matthiask commented Feb 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rik Sep 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthiask commented Oct 1, 2026

Uh oh!

codingjoe left a comment

Choose a reason for hiding this comment

Uh oh!

matthiask commented Oct 4, 2026

Uh oh!

codingjoe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthiask Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthiask commented Oct 13, 2026

Uh oh!

LilyFirefly commented Oct 13, 2026

Uh oh!

matthiask commented Oct 14, 2026

Uh oh!

codingjoe commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

matthiask commented Feb 14, 2025 •

edited

Loading

rik Sep 30, 2026 •

edited

Loading

matthiask Oct 13, 2026 •

edited

Loading

codingjoe commented Oct 14, 2026 •

edited

Loading