Skip to content

dlivxpr/django-js-vendor

Repository files navigation

Django JS Vendor

Django JS Vendor 是一个轻量级的前端依赖管理工具,旨在为 Django 项目提供类似 cargopnpm 的体验,无需引入 Node.js 环境。

特性

  • 轻量级: 纯 Python 实现,无 Node.js 依赖。
  • 声明式配置: 使用 pyproject.toml 管理依赖。
  • 版本锁定: 自动生成 js-vendor.lock 确保生产环境一致性。
  • 并发下载: 使用 httpxasyncio 快速并发下载。
  • CDN 支持: 默认支持 unpkg,可扩展。

安装

使用 uv (推荐)

uv add django-js-vendor

使用 pip

pip install django-js-vendor

django_js_vendor 添加到 INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "django_js_vendor",
]

配置

在项目的 pyproject.toml 中添加 [tool.django-js-vendor]

[tool.django-js-vendor]
# 下载目录 (默认为 static/vendor)
destination = "static/vendor"
# 默认 CDN (目前支持 unpkg)
default_provider = "unpkg"

[tool.django-js-vendor.dependencies]
# 简写模式 (自动获取最新版或指定版本)
"htmx.org" = "1.9.10"
alpinejs = "3.13.3"

# 详细模式
jquery = { version = "3.7.1", files = ["dist/jquery.min.js", "dist/jquery.min.map"] }

使用命令

同步依赖

下载 pyproject.toml 中定义的所有依赖,并生成/更新 js-vendor.lock

python manage.py vendor sync

添加依赖

添加新包到配置并下载。

python manage.py vendor add htmx.org
python manage.py vendor add alpinejs 3.13.0

移除依赖

移除依赖及其相关文件,并更新配置。

python manage.py vendor remove htmx.org

更新依赖

更新依赖并刷新 lock 文件。

python manage.py vendor update

模板标签 (Template Tags)

Django JS Vendor 提供了一个便捷的模板标签,用于在 HTML 中自动引入所有已安装的依赖。

引入所有资源

在你的基础模板(如 base.html)中:

{% load vendor_tags %}

<head>
    <!-- 自动生成 <script> 和 <link> 标签 -->
    {% render_vendor_assets %}
</head>

它会根据 js-vendor.lock 的内容,按照 pyproject.toml 中定义的顺序,自动生成对应的 HTML 标签。

按需引入

你也可以只引入特定的包:

{% render_vendor_assets 'htmx' 'alpine' %}

开发指南

本项目使用 uv 进行依赖管理和任务执行。

1. 获取代码

git clone https://github.com/dlivxpr/django-js-vendor.git
cd django-js-vendor

2. 安装环境

使用 uv sync 安装项目依赖(包括开发依赖):

uv sync

3. 运行测试

使用 uv run 执行测试套件:

uv run pytest

4. 代码检查

uv run ruff check .

About

No description, website, or topics provided.

Resources

License

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages