Skip to main content

Lightweight JavaScript ESM module loader for Django.

Project description

Django ESM

NextGen JavaScript ESM module support for Django.

PyPi Version Test Coverage GitHub 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:

pip install django-esm
# settings.py
INSTALLED_APPS = [
    # …
    'django_esm',
]

Next, add the node_modules directory to your staticfiles directories:

# settings.py
STATICFILES_DIRS = [
    BASE_DIR / "node_modules",
]

Finally, add the import map to your base template:

<!-- 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:

<!-- 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:

<!-- 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:

{
  "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:

// 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 to map module names to their location on the server.

Here is an example import map:

{
  "imports": {
    "htmx.org": "/static/htmx.org/dist/htmx.min.js"
  }
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_esm-0.2.2.tar.gz (5.4 kB view hashes)

Uploaded Source

Built Distribution

django_esm-0.2.2-py3-none-any.whl (6.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page