plain.importmap
Use import maps in templates.
Heavily inspired by rails/importmap-rails, this app adds a simple process for integrating import maps into Django.
This is a new project and it hasn't been used in production yet. But if you're looking to use import maps with Django, give it a try and tell us how it goes. The structure (and code) is pretty simple. Contributions are welcome!
How to use it
You'll need to do four things to use plain-importmap.
The TL;DR is:
- Add "importmap" to
INSTALLED_PACKAGES
- Create an
importmap.toml
- Run
python manage.py importmap_generate
- Use
{% importmap_js %}
in your template
1. Install it
Do the equivalent of pip install plain-importmap
and add it to your INSTALLED_PACKAGES
list in your settings.py
file.
# settings.py
INSTALLED_PACKAGES = [
...
"importmap",
]
2. Create an importmap.toml
file
This should live next to your manage.py
file.
Here you'll add a list of "packages" you want to use.
The "name" can be anything, but should probably be the same as what it you would import from in typical bundling setups (i.e. import React from "react"
).
The "source" will get passed on to the jspm.org generator, but is basically the <npm package>@<version>
you want to use.
[[packages]]
name = "react"
source = "[email protected]"
3. Run importmap_generate
To resolve the import map, you'll need to run python manage.py importmap_generate
.
This will create importmap.lock
(which you should save and commit to your repo) that contains the actual import map JSON (both for development and production).
You don't need to look at this file yourself, but here is an example of what it will contain:
{
"config_hash": "09d6237cdd891aad07de60f54689d130",
"importmap": {
"imports": {
"react": "https://ga.jspm.io/npm:[email protected]/index.js"
},
"scopes": {
"https://ga.jspm.io/": {
"object-assign": "https://ga.jspm.io/npm:[email protected]/index.js"
}
}
},
"importmap_dev": {
"imports": {
"react": "https://ga.jspm.io/npm:[email protected]/dev.index.js"
},
"scopes": {
"https://ga.jspm.io/": {
"object-assign": "https://ga.jspm.io/npm:[email protected]/index.js"
}
}
}
}
4. Add the scripts to your template
The import map itself gets added by using {% load importmap %}
and then {% importmap_js %}
in the head of your HTML. This will include the es-module-shim.
After that, you can include your own JavaScript!
This could be inline or from static
.
Just be sure to use type="module"
and the "name" you provided when doing your JS imports (i.e. "react").
{% load importmap %}
<!DOCTYPE html>
<html lang="en">
<head>
{% importmap_js %}
<script type="module">
import React from "react"
console.log(React);
</script>
</head>
<body>
</body>
</html>
When it renders you should get something like this:
<!DOCTYPE html>
<html lang="en">
<head>
<script async src="https://ga.jspm.io/npm:[email protected]/dist/es-module-shims.js"></script>
<script type="importmap">
{
"imports": {
"react": "https://ga.jspm.io/npm:[email protected]/dev.index.js"
},
"scopes": {
"https://ga.jspm.io/": {
"object-assign": "https://ga.jspm.io/npm:[email protected]/index.js"
}
}
}
</script>
<script type="module">
import React from "react"
console.log(React);
</script>
</head>
<body>
</body>
</html>
Project status
This is partly an experiment, but honestly it's so simple that I don't think there can be much wrong with how it works currently.
Here's a list of things that would be nice to do (PRs welcome):
- Command to add new importmap dependency (use
^
version automatically?) - Django check for comparing lock and config (at deploy time, etc.)
- Use deps to update shim version
- Preload option
- Vendoring option (including shim)
- More complete error handling (custom exceptions, etc.)
1import hashlib
2import json
3import logging
4import os
5
6import tomli
7from marshmallow import Schema, fields
8
9from .generator import ImportmapGenerator
10
11logger = logging.getLogger(__name__)
12
13
14DEFAULT_CONFIG_FILENAME = "importmap.toml"
15DEFAULT_LOCK_FILENAME = "importmap.lock"
16
17
18class PackageSchema(Schema):
19 name = fields.String(required=True)
20 source = fields.String(required=True)
21 # preload
22 # vendor, or vendor all is one option?
23
24
25class ConfigSchema(Schema):
26 packages = fields.List(fields.Nested(PackageSchema), required=True)
27
28
29class LockfileSchema(Schema):
30 config_hash = fields.String(required=True)
31 importmap = fields.Dict(required=True)
32 importmap_dev = fields.Dict(required=True)
33
34
35def hash_for_data(data):
36 return hashlib.md5(json.dumps(data, sort_keys=True).encode("utf-8")).hexdigest()
37
38
39class Importmap:
40 def __init__(
41 self,
42 config_filename=DEFAULT_CONFIG_FILENAME,
43 lock_filename=DEFAULT_LOCK_FILENAME,
44 ):
45 self.config_filename = config_filename
46 self.lock_filename = lock_filename
47 self.config = {}
48 self.map = {}
49 self.map_dev = {}
50
51 def load(self):
52 # TODO preflight check to compare lock and config hash
53
54 self.config = self.load_config()
55
56 if not self.config:
57 # No config = no map and no lockfile
58 self.map = {}
59 self.map_dev = {}
60 self.delete_lockfile()
61 return
62
63 config_hash = hash_for_data(self.config)
64 lockfile = self.load_lockfile()
65
66 if not lockfile or lockfile["config_hash"] != config_hash:
67 # Generate both maps now, tag will choose which to use at runtime
68 self.map = self.generate_map()
69 self.map_dev = self.generate_map(development=True)
70
71 lockfile["config_hash"] = config_hash
72 lockfile["importmap"] = self.map
73 lockfile["importmap_dev"] = self.map_dev
74 self.save_lockfile(lockfile)
75
76 elif lockfile:
77 # Use map from up-to-date lockfile
78 self.map = lockfile["importmap"]
79 self.map_dev = lockfile["importmap_dev"]
80
81 def load_config(self):
82 # TODO raise custom exceptions
83
84 if not os.path.exists(self.config_filename):
85 logger.warning(f"{self.config_filename} not found")
86 return {}
87
88 with open(self.config_filename) as f:
89 # why doesn't tomli.load(f) work?
90 toml_data = tomli.loads(f.read())
91
92 return ConfigSchema().load(toml_data)
93
94 def load_lockfile(self):
95 if not os.path.exists(self.lock_filename):
96 return {}
97
98 with open(self.lock_filename) as f:
99 json_data = json.load(f)
100
101 return LockfileSchema().load(json_data)
102
103 def save_lockfile(self, lockfile):
104 with open(self.lock_filename, "w+") as f:
105 json.dump(lockfile, f, indent=2, sort_keys=True)
106
107 def delete_lockfile(self):
108 if os.path.exists(self.lock_filename):
109 os.remove(self.lock_filename)
110
111 def generate_map(self, *args, **kwargs):
112 return ImportmapGenerator.from_config(self.config, *args, **kwargs).generate()