| Name | django-esm JSON |
| Version |
0.4.2
JSON |
| download |
| home_page | |
| Summary | Lightweight JavaScript ESM module loader for Django. |
| upload_time | 2024-01-25 18:36:30 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | |
| keywords |
esm
javascript
importmap
django
module
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Django ESM
NextGen JavaScript ESM module support for Django.
[](https://pypi.python.org/pypi/django-esm/)
[](https://codecov.io/gh/codingjoe/django-esm)
[](https://raw.githubusercontent.com/codingjoe/django-esm/master/LICENSE)
## Highlights
* easy transition
* smart cache busting
* no more bundling
* native ESM support
* local vendoring with npm
## Setup
Install the package and add it to your `INSTALLED_APPS` setting:
```bash
pip install django-esm
```
```python
# settings.py
INSTALLED_APPS = [
# …
'django_esm',
]
```
Next, add a new staticfiles finder to your `STATICFILES_FINDERS` setting:
```python
# settings.py
STATICFILES_FINDERS = [
# Django's default finders
"django.contrib.staticfiles.finders.FileSystemFinder",
"django.contrib.staticfiles.finders.AppDirectoriesFinder",
# django-esm finder
"django_esm.finders.ESMFinder",
]
```
You will also need to expose your `node_modules` directory to Django's
staticfiles finder. You may run `npm ci --omit=dev` prior to running
`collectstatic` to avoid exposing your `devDependencies` publicly.
```python
# settings.py
from pathlib import Path
# add BASE_DIR (if not already present)
BASE_DIR = Path(__file__).resolve().parent.parent
STATICFILES_DIRS = [
# …
BASE_DIR / "node_modules",
]
```
Finally, add the import map to your base template:
```html
<!-- base.html -->
<!DOCTYPE html>
{% load esm %}
<html lang="en">
<head>
<script type="importmap">{% importmap %}</script>
</head>
</html>
```
That's it!
Don't forget to run `npm install` and `python manage.py collectstatic`.
## Usage
You can now import JavaScript modules in your Django templates:
```html
<!-- index.html -->
{% block content %}
<script type="module">
import "htmx.org"
htmx.logAll()
</script>
{% endblock %}
```
### Private modules
You can also import private modules from your Django app:
```html
<!-- index.html -->
{% block content %}
<script type="module">
import "#myapp/js/my-module.js"
</script>
{% endblock %}
```
To import a private module, prefix the module name with `#`.
You need to define your private modules in your `package.json` file:
```json
{
"imports": {
"#myapp/script": "./myapp/static/js/script.js",
// You may use trailing stars to import all files in a directory.
"#myapp/*": "./myapp/static/js/*"
}
}
```
### Testing (with Jest)
You can use the `django_esm` package to test your JavaScript modules with Jest.
Jest v27.4 and upwards will honor `imports` in your `package.json` file.
Before v27.4 that, you can try to use a custom `moduleNameMapper`, like so:
```js
// jest.config.js
module.exports = {
// …
moduleNameMapper: {
'^#(.*)$': '<rootDir>/staticfiles/js/$1' // @todo: remove this with Jest >=29.4
},
}
```
## How it works
Django ESM works via native JavaScript module support in modern browsers.
It uses the [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)
to map module names to their location on the server.
Here is an example import map:
```json
{
"imports": {
"htmx.org": "/static/htmx.org/dist/htmx.min.js"
}
}
```
Raw data
{
"_id": null,
"home_page": "",
"name": "django-esm",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "ESM,JavaScript,importmap,Django,module",
"author": "",
"author_email": "Johannes Maron <johannes@maron.family>",
"download_url": "https://files.pythonhosted.org/packages/be/ec/711a9acbfb814de64fe45b3f5343846361236f464a36c31965362a2af042/django_esm-0.4.2.tar.gz",
"platform": null,
"description": "# Django ESM\n\nNextGen JavaScript ESM module support for Django.\n\n[](https://pypi.python.org/pypi/django-esm/)\n[](https://codecov.io/gh/codingjoe/django-esm)\n[](https://raw.githubusercontent.com/codingjoe/django-esm/master/LICENSE)\n\n## Highlights\n\n* easy transition\n* smart cache busting\n* no more bundling\n* native ESM support\n* local vendoring with npm\n\n## Setup\n\nInstall the package and add it to your `INSTALLED_APPS` setting:\n\n```bash\npip install django-esm\n```\n\n```python\n# settings.py\nINSTALLED_APPS = [\n # \u2026\n 'django_esm',\n]\n```\n\nNext, add a new staticfiles finder to your `STATICFILES_FINDERS` setting:\n\n```python\n# settings.py\nSTATICFILES_FINDERS = [\n # Django's default finders\n \"django.contrib.staticfiles.finders.FileSystemFinder\",\n \"django.contrib.staticfiles.finders.AppDirectoriesFinder\",\n # django-esm finder\n \"django_esm.finders.ESMFinder\",\n]\n```\n\nYou will also need to expose your `node_modules` directory to Django's\nstaticfiles finder. You may run `npm ci --omit=dev` prior to running\n`collectstatic` to avoid exposing your `devDependencies` publicly.\n\n```python\n# settings.py\nfrom pathlib import Path\n\n# add BASE_DIR (if not already present)\nBASE_DIR = Path(__file__).resolve().parent.parent\n\nSTATICFILES_DIRS = [\n # \u2026\n BASE_DIR / \"node_modules\",\n]\n```\n\nFinally, add the import map to your base template:\n\n```html\n<!-- base.html -->\n<!DOCTYPE html>\n{% load esm %}\n<html lang=\"en\">\n<head>\n <script type=\"importmap\">{% importmap %}</script>\n</head>\n</html>\n```\n\nThat's it!\nDon't forget to run `npm install` and `python manage.py collectstatic`.\n\n## Usage\n\nYou can now import JavaScript modules in your Django templates:\n\n```html\n<!-- index.html -->\n{% block content %}\n <script type=\"module\">\n import \"htmx.org\"\n htmx.logAll()\n </script>\n{% endblock %}\n```\n\n### Private modules\n\nYou can also import private modules from your Django app:\n\n```html\n<!-- index.html -->\n{% block content %}\n <script type=\"module\">\n import \"#myapp/js/my-module.js\"\n </script>\n{% endblock %}\n```\n\nTo import a private module, prefix the module name with `#`.\nYou need to define your private modules in your `package.json` file:\n\n```json\n{\n \"imports\": {\n \"#myapp/script\": \"./myapp/static/js/script.js\",\n // You may use trailing stars to import all files in a directory.\n \"#myapp/*\": \"./myapp/static/js/*\"\n }\n}\n```\n\n### Testing (with Jest)\n\nYou can use the `django_esm` package to test your JavaScript modules with Jest.\nJest v27.4 and upwards will honor `imports` in your `package.json` file.\n\nBefore v27.4 that, you can try to use a custom `moduleNameMapper`, like so:\n\n```js\n// jest.config.js\nmodule.exports = {\n // \u2026\n moduleNameMapper: {\n '^#(.*)$': '<rootDir>/staticfiles/js/$1' // @todo: remove this with Jest >=29.4\n },\n}\n```\n\n## How it works\n\nDjango ESM works via native JavaScript module support in modern browsers.\nIt uses the [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)\nto map module names to their location on the server.\n\nHere is an example import map:\n\n```json\n{\n \"imports\": {\n \"htmx.org\": \"/static/htmx.org/dist/htmx.min.js\"\n }\n}\n```\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Lightweight JavaScript ESM module loader for Django.",
"version": "0.4.2",
"project_urls": {
"Changelog": "https://github.com/codingjoe/django-esm/releases",
"Documentation": "https://github.com/codingjoe/django-esm#django-esm",
"Issue-Tracker": "https://github.com/codingjoe/django-esm/issues",
"Project-URL": "https://github.com/codingjoe/django-esm",
"Source": "https://github.com/codingjoe/django-esm"
},
"split_keywords": [
"esm",
"javascript",
"importmap",
"django",
"module"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4a2782391dee880864c75e120cd5622e21ae0f6830fe8ec789df4ac8105fa758",
"md5": "d054224e2c0f23b7c7d3d8089bc2acd4",
"sha256": "db1eb4cd32134921341b4bc34e475d4ba8e5c5086d8ff7b39a58927eea61a788"
},
"downloads": -1,
"filename": "django_esm-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d054224e2c0f23b7c7d3d8089bc2acd4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7618,
"upload_time": "2024-01-25T18:36:28",
"upload_time_iso_8601": "2024-01-25T18:36:28.613951Z",
"url": "https://files.pythonhosted.org/packages/4a/27/82391dee880864c75e120cd5622e21ae0f6830fe8ec789df4ac8105fa758/django_esm-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "beec711a9acbfb814de64fe45b3f5343846361236f464a36c31965362a2af042",
"md5": "6224a637b3978ad54622bad3547c56c9",
"sha256": "1de2f47b3a252421e46087a521ec8b588dbb38ae678ed6e4160c9650f557c5f4"
},
"downloads": -1,
"filename": "django_esm-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "6224a637b3978ad54622bad3547c56c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6257,
"upload_time": "2024-01-25T18:36:30",
"upload_time_iso_8601": "2024-01-25T18:36:30.355643Z",
"url": "https://files.pythonhosted.org/packages/be/ec/711a9acbfb814de64fe45b3f5343846361236f464a36c31965362a2af042/django_esm-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-25 18:36:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "codingjoe",
"github_project": "django-esm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-esm"
}
