plain.vendor
Download and manage vendored CSS and JavaScript dependencies from CDNs.
- Overview
- Adding dependencies
- Syncing dependencies
- Updating dependencies
- Configuration options
- FAQs
- Installation
Overview
You can use plain vendor to download JavaScript and CSS files from CDNs and store them locally in your project. This keeps third-party assets under version control and avoids runtime dependencies on external CDNs.
Dependencies are configured in your pyproject.toml and downloaded to app/assets/vendor/.
# pyproject.toml
[tool.plain.vendor.dependencies]
htmx = {url = "https://unpkg.com/htmx.org@{version}/dist/htmx.min.js", installed = "2.0.4"}
alpine = {url = "https://cdn.jsdelivr.net/npm/alpinejs@{version}/dist/cdn.min.js", installed = "3.14.8"}
After configuring dependencies, run plain vendor sync to download them:
plain vendor sync
The files are saved to app/assets/vendor/ and can be included in your templates:
<script src="{{ 'vendor/htmx.min.js'|asset }}"></script>
<script src="{{ 'vendor/cdn.min.js'|asset }}"></script>
Adding dependencies
You can add a new dependency directly from the command line:
plain vendor add https://unpkg.com/htmx.org/dist/htmx.min.js
This downloads the file, extracts the version from the URL, and adds an entry to your pyproject.toml. You can also specify a custom name:
plain vendor add https://unpkg.com/htmx.org/dist/htmx.min.js --name htmx
Syncing dependencies
The sync command clears all existing vendored files and re-downloads everything from scratch:
plain vendor sync
Use this when you first clone a project or want to ensure your vendored files match your configuration.
Updating dependencies
The update command checks for newer versions and updates your pyproject.toml:
# Update all dependencies
plain vendor update
# Update specific dependencies
plain vendor update htmx alpine
The update process tries several strategies to find newer versions:
- Requests the "latest" tag (supported by many CDNs)
- Increments version numbers to probe for new releases
Configuration options
Custom filenames
If you want to rename a file when it's downloaded, use the filename option:
[tool.plain.vendor.dependencies]
htmx = {url = "https://unpkg.com/htmx.org@{version}/dist/htmx.min.js", installed = "2.0.4", filename = "htmx.js"}
Source maps
You can automatically download source maps alongside your vendored files:
[tool.plain.vendor.dependencies]
htmx = {url = "https://unpkg.com/htmx.org@{version}/dist/htmx.min.js", installed = "2.0.4", sourcemap = true}
When sourcemap = true, the tool appends .map to the filename and downloads from the same directory. For non-standard source map filenames, provide the filename directly:
[tool.plain.vendor.dependencies]
example = {url = "https://example.com/lib.min.js", installed = "1.0.0", sourcemap = "lib.min.js.map"}
You can also use the --sourcemap flag when adding dependencies:
plain vendor add https://unpkg.com/htmx.org/dist/htmx.min.js --sourcemap
Version placeholders
URLs can include a {version} placeholder that gets replaced with the installed version number:
htmx = {url = "https://unpkg.com/htmx.org@{version}/dist/htmx.min.js", installed = "2.0.4"}
When you run plain vendor sync, the placeholder is replaced with 2.0.4. This makes it easy to see which version is installed and enables the update command to try newer versions.
FAQs
What file types are supported?
The vendor tool accepts JavaScript (application/javascript, text/javascript), CSS (text/css), and JSON (application/json) files. Other content types will raise an error.
Where are vendored files stored?
All vendored files are downloaded to app/assets/vendor/. This directory is created automatically if it doesn't exist.
How does version detection work?
When you add a dependency or update to a new version, the tool parses version numbers from the final URL (after any redirects). It looks for patterns like 1.2.3 or 1.2 in the URL path.
What happens if a CDN is unavailable?
The sync and update commands will fail with an error if any dependency cannot be downloaded. You'll see which dependencies failed in the output.
Installation
Install the plain.vendor package from PyPI:
uv add plain.vendor
After installation, the plain vendor command becomes available. Configure your dependencies in pyproject.toml:
[tool.plain.vendor.dependencies]
htmx = {url = "https://unpkg.com/htmx.org@{version}/dist/htmx.min.js", installed = "2.0.4"}
Then run the sync command to download them:
plain vendor sync
Your vendored files will be available in app/assets/vendor/ and can be referenced in templates using the asset template filter.