# django-importmap
Heavily inspired by [rails/importmap-rails](https://github.com/rails/importmap-rails),
this app adds a simple process for integrating [import maps](https://github.com/WICG/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 django-importmap.
The TL;DR is:
- Add "importmap" to `INSTALLED_APPS`
- Create an `importmap.toml`
- Run `python manage.py importmap_generate`
- Use `{% importmap_scripts %}` in your template
### 1. Install it
Do the equivalent of `pip install django-importmap` and add it to your `INSTALLED_APPS` list in your `settings.py` file.
```python
# settings.py
INSTALLED_APPS = [
...
"importmap",
]
```
### 2. Configuring an import map
You JavaScript dependencies are conveniently located in your`pyproject.toml` file.
They are listed under `[tool.importmap.dependencies]` and you can add them there. The format is `name = "version"`,
similar to how you would add a dependency to your `package.json` file.
```toml
# pyproject.toml
[tool.importmap.dependencies]
react = "17.0.2"
react-dom = "17.0.2"
```
[jspm.org generator](https://jspm.org/docs/api#install) is used lock and serve the dependencies,
but is basically just like installing them via `npm i <npm package>@<version>`.
### 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:
```json
{
"config_hash": "09d6237cdd891aad07de60f54689d130",
"importmap": {
"imports": {
"react": "https://ga.jspm.io/npm:react@17.0.2/index.js"
},
"scopes": {
"https://ga.jspm.io/": {
"object-assign": "https://ga.jspm.io/npm:object-assign@4.1.1/index.js"
}
}
},
"importmap_dev": {
"imports": {
"react": "https://ga.jspm.io/npm:react@17.0.2/dev.index.js"
},
"scopes": {
"https://ga.jspm.io/": {
"object-assign": "https://ga.jspm.io/npm:object-assign@4.1.1/index.js"
}
}
}
}
```
### 4. Add the scripts to your template
The import map itself gets added by using `{% load importmap %}` and then `{% importmap_scripts %}` in the head of your HTML. This will include the [es-module-shim](https://github.com/guybedford/es-module-shims).
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").
```html
{% load importmap %}
<!DOCTYPE html>
<html lang="en">
<head>
{% importmap_scripts %}
<script type="module">
import React from "react"
console.log(React);
</script>
</head>
<body>
</body>
</html>
```
When it renders you should get something like this:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<script async src="https://ga.jspm.io/npm:es-module-shims@1.3.6/dist/es-module-shims.js"></script>
<script type="importmap">
{
"imports": {
"react": "https://ga.jspm.io/npm:react@17.0.2/dev.index.js"
},
"scopes": {
"https://ga.jspm.io/": {
"object-assign": "https://ga.jspm.io/npm:object-assign@4.1.1/index.js"
}
}
}
</script>
<script type="module">
import React from "react"
console.log(React);
</script>
</head>
<body>
</body>
</html>
```
## Adding static files to import maps
You can include your own static files in the import map by passing kwargs to the `{% importmap_scripts %}` tag.
You can actually use this to include any additional imports, but by using `{% static "name" as name_static %}` you can get the URL to the static file.
```html
{% load importmap static %}
<!DOCTYPE html>
<html lang="en">
<head>
{% static "my-script.js" as my_script_static %}
{% importmap_scripts myscript=my_script_static %}
<script type="module">
import MyScript from "myscript"
</script>
</head>
<body>
</body>
</html>
```
## Using Jinja2
To use django-importmap with Jinja2 templates,
you can add `importmap` to a customized Jinja environment.
```python
TEMPLATES = [
{
"BACKEND": "django.template.backends.jinja2.Jinja2",
...
"OPTIONS": {
"environment": "app.jinja2.environment",
...
},
}
]
```
Then in `app/jinja2.py`:
```python
from django.conf import settings
from jinja2 import Environment
from importmap import Importmap
def environment(**options):
env = Environment(**options)
env.globals.update({"importmap": Importmap.json(development=settings.DEBUG)})
return env
```
Then in your Jinja templates you can include a module shim and output the `importmap` variable like this:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<script async src="https://ga.jspm.io/npm:es-module-shims@1.3.6/dist/es-module-shims.js"></script>
<script type="importmap">
{{ importmap|safe }}
</script>
<script type="module">
import React from "react"
console.log(React);
</script>
</head>
<body>
</body>
</html>
```
To include your own static files in the import map,
you can pass a dictionary of names and URLs to the `Importmap.json` method:
```python
from django.conf import settings
from django.templatetags.static import static
from jinja2 import Environment
from importmap import Importmap
def environment(**options):
env = Environment(**options)
env.globals.update(
{
"importmap": Importmap.json(
development=settings.DEBUG, extra_imports={"myjs": static("myjs.js")}
)
}
)
return env
```
## 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](https://www.dependencies.io/) to update shim version
- Preload option
- Vendoring option (including shim)
- More complete error handling (custom exceptions, etc.)
Raw data
{
"_id": null,
"home_page": "https://github.com/dropseed/django-importmap",
"name": "django-importmap",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "django,javascript,import,map,import-maps",
"author": "Dave Gaeddert",
"author_email": "dave.gaeddert@dropseed.dev",
"download_url": "https://files.pythonhosted.org/packages/49/4a/7315cc335e65d54c287bc8dd79ded27a5b8631c04568d3c6c9a9b370e684/django_importmap-0.3.0.tar.gz",
"platform": null,
"description": "# django-importmap\n\nHeavily inspired by [rails/importmap-rails](https://github.com/rails/importmap-rails),\nthis app adds a simple process for integrating [import maps](https://github.com/WICG/import-maps) into Django.\n\nThis is a new project and it hasn't been used in production yet.\nBut if you're looking to use import maps with Django, give it a try and tell us how it goes.\nThe structure (and code) is pretty simple.\nContributions are welcome!\n\n## How to use it\n\nYou'll need to do four things to use django-importmap.\n\nThe TL;DR is:\n\n- Add \"importmap\" to `INSTALLED_APPS`\n- Create an `importmap.toml`\n- Run `python manage.py importmap_generate`\n- Use `{% importmap_scripts %}` in your template\n\n### 1. Install it\n\nDo the equivalent of `pip install django-importmap` and add it to your `INSTALLED_APPS` list in your `settings.py` file.\n\n```python\n# settings.py\nINSTALLED_APPS = [\n ...\n \"importmap\",\n]\n```\n\n### 2. Configuring an import map\n\nYou JavaScript dependencies are conveniently located in your`pyproject.toml` file.\n\nThey are listed under `[tool.importmap.dependencies]` and you can add them there. The format is `name = \"version\"`,\nsimilar to how you would add a dependency to your `package.json` file.\n\n```toml\n# pyproject.toml\n[tool.importmap.dependencies]\nreact = \"17.0.2\"\nreact-dom = \"17.0.2\"\n```\n\n[jspm.org generator](https://jspm.org/docs/api#install) is used lock and serve the dependencies,\nbut is basically just like installing them via `npm i <npm package>@<version>`.\n\n### 3. Run `importmap_generate`\n\nTo resolve the import map, you'll need to run `python manage.py importmap_generate`.\n\nThis 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).\n\nYou don't need to look at this file yourself, but here is an example of what it will contain:\n\n```json\n{\n \"config_hash\": \"09d6237cdd891aad07de60f54689d130\",\n \"importmap\": {\n \"imports\": {\n \"react\": \"https://ga.jspm.io/npm:react@17.0.2/index.js\"\n },\n \"scopes\": {\n \"https://ga.jspm.io/\": {\n \"object-assign\": \"https://ga.jspm.io/npm:object-assign@4.1.1/index.js\"\n }\n }\n },\n \"importmap_dev\": {\n \"imports\": {\n \"react\": \"https://ga.jspm.io/npm:react@17.0.2/dev.index.js\"\n },\n \"scopes\": {\n \"https://ga.jspm.io/\": {\n \"object-assign\": \"https://ga.jspm.io/npm:object-assign@4.1.1/index.js\"\n }\n }\n }\n}\n```\n\n### 4. Add the scripts to your template\n\nThe import map itself gets added by using `{% load importmap %}` and then `{% importmap_scripts %}` in the head of your HTML. This will include the [es-module-shim](https://github.com/guybedford/es-module-shims).\n\nAfter that, you can include your own JavaScript!\nThis could be inline or from `static`.\nJust be sure to use `type=\"module\"` and the \"name\" you provided when doing your JS imports (i.e. \"react\").\n\n```html\n{% load importmap %}\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n {% importmap_scripts %}\n <script type=\"module\">\n import React from \"react\"\n\n console.log(React);\n </script>\n</head>\n<body>\n\n</body>\n</html>\n```\n\nWhen it renders you should get something like this:\n\n```html\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n <script async src=\"https://ga.jspm.io/npm:es-module-shims@1.3.6/dist/es-module-shims.js\"></script>\n <script type=\"importmap\">\n {\n \"imports\": {\n \"react\": \"https://ga.jspm.io/npm:react@17.0.2/dev.index.js\"\n },\n \"scopes\": {\n \"https://ga.jspm.io/\": {\n \"object-assign\": \"https://ga.jspm.io/npm:object-assign@4.1.1/index.js\"\n }\n }\n }\n </script>\n\n <script type=\"module\">\n import React from \"react\"\n\n console.log(React);\n </script>\n</head>\n<body>\n\n</body>\n</html>\n```\n\n## Adding static files to import maps\n\nYou can include your own static files in the import map by passing kwargs to the `{% importmap_scripts %}` tag.\nYou can actually use this to include any additional imports, but by using `{% static \"name\" as name_static %}` you can get the URL to the static file.\n\n```html\n{% load importmap static %}\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n {% static \"my-script.js\" as my_script_static %}\n {% importmap_scripts myscript=my_script_static %}\n <script type=\"module\">\n import MyScript from \"myscript\"\n </script>\n</head>\n<body>\n\n</body>\n</html>\n```\n\n## Using Jinja2\n\nTo use django-importmap with Jinja2 templates,\nyou can add `importmap` to a customized Jinja environment.\n\n```python\nTEMPLATES = [\n {\n \"BACKEND\": \"django.template.backends.jinja2.Jinja2\",\n ...\n \"OPTIONS\": {\n \"environment\": \"app.jinja2.environment\",\n ...\n },\n }\n]\n```\n\nThen in `app/jinja2.py`:\n\n```python\nfrom django.conf import settings\nfrom jinja2 import Environment\n\nfrom importmap import Importmap\n\n\ndef environment(**options):\n env = Environment(**options)\n env.globals.update({\"importmap\": Importmap.json(development=settings.DEBUG)})\n return env\n```\n\nThen in your Jinja templates you can include a module shim and output the `importmap` variable like this:\n\n```html\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n <script async src=\"https://ga.jspm.io/npm:es-module-shims@1.3.6/dist/es-module-shims.js\"></script>\n <script type=\"importmap\">\n {{ importmap|safe }}\n </script>\n <script type=\"module\">\n import React from \"react\"\n console.log(React);\n </script>\n</head>\n<body>\n\n</body>\n</html>\n```\n\nTo include your own static files in the import map,\nyou can pass a dictionary of names and URLs to the `Importmap.json` method:\n\n```python\nfrom django.conf import settings\nfrom django.templatetags.static import static\nfrom jinja2 import Environment\n\nfrom importmap import Importmap\n\n\ndef environment(**options):\n env = Environment(**options)\n env.globals.update(\n {\n \"importmap\": Importmap.json(\n development=settings.DEBUG, extra_imports={\"myjs\": static(\"myjs.js\")}\n )\n }\n )\n return env\n```\n\n## Project status\n\nThis is partly an experiment,\nbut honestly it's so simple that I don't think there can be much wrong with how it works currently.\n\nHere's a list of things that would be nice to do (PRs welcome):\n\n- Command to add new importmap dependency (use `^` version automatically?)\n- Django check for comparing lock and config (at deploy time, etc.)\n- Use [deps](https://www.dependencies.io/) to update shim version\n- Preload option\n- Vendoring option (including shim)\n- More complete error handling (custom exceptions, etc.)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "JavaScript import maps for Django",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/dropseed/django-importmap",
"Homepage": "https://github.com/dropseed/django-importmap",
"Repository": "https://github.com/dropseed/django-importmap"
},
"split_keywords": [
"django",
"javascript",
"import",
"map",
"import-maps"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5dd89db7092e9661a9fafa702392647943caaa51505cf865ed97bfb114c72c41",
"md5": "8711517fb303c01c9cd6cdc4cb2e0f53",
"sha256": "5bfe2e1f4b45a3fb0dce1c81572fa52bc460b0947450b859c40f58271c16e009"
},
"downloads": -1,
"filename": "django_importmap-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8711517fb303c01c9cd6cdc4cb2e0f53",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 8021,
"upload_time": "2023-11-28T20:34:50",
"upload_time_iso_8601": "2023-11-28T20:34:50.618627Z",
"url": "https://files.pythonhosted.org/packages/5d/d8/9db7092e9661a9fafa702392647943caaa51505cf865ed97bfb114c72c41/django_importmap-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "494a7315cc335e65d54c287bc8dd79ded27a5b8631c04568d3c6c9a9b370e684",
"md5": "227ea1024b84e320873f15945e547dc6",
"sha256": "e65fce1735bec7ca4ee0c21fb72ce29b0028dddd1e9a6e3faa5083e2b9baeb92"
},
"downloads": -1,
"filename": "django_importmap-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "227ea1024b84e320873f15945e547dc6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 7637,
"upload_time": "2023-11-28T20:34:51",
"upload_time_iso_8601": "2023-11-28T20:34:51.601048Z",
"url": "https://files.pythonhosted.org/packages/49/4a/7315cc335e65d54c287bc8dd79ded27a5b8631c04568d3c6c9a9b370e684/django_importmap-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-28 20:34:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dropseed",
"github_project": "django-importmap",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-importmap"
}
JSON
