Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tbeseda/vendurl
Vendor a JS dependency from a URL
https://github.com/tbeseda/vendurl
Last synced: 5 days ago
JSON representation
Vendor a JS dependency from a URL
- Host: GitHub
- URL: https://github.com/tbeseda/vendurl
- Owner: tbeseda
- Created: 2023-09-26T22:10:27.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2023-11-27T20:29:38.000Z (12 months ago)
- Last Synced: 2024-04-14T13:19:17.774Z (7 months ago)
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/vendurl
- Size: 43 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
vendurl 🛍️
Vendor (verb: download and store) a JS dependency from a URL.
vendurl on npmjs.org »
Contents:
Install
•
How it works
•
Development
•
FAQ
> [!NOTE]
> `vendurl` is in no way intended to replace `npm` for dependency management. It is best utilized for vendoring a few, small packages that are not published in a way you'd like to consume.
## Installation and usage
```sh
npm i -D vendurl
```
Add packages to the "vendurl" key in `package.json` by setting a filename with extension and package specifier:
```json
{
"vendurl": {
"packages": {
"temporal.js": "@js-temporal/polyfill",
"chalk4.mjs": "chalk@4",
"leftpad.cjs": "https://unpkg.com/[email protected]/index.js"
}
}
}
```
Run `vendurl` to download and store the packages:
```sh
npx vendurl
```
Use the packages in your code:
```js
import { Temporal } from './vendor/temporal.js';
import chalk from './vendor/chalk4.mjs';
import leftpad from './vendor/leftpad.cjs';
```
### Options
#### Optional `package.json` `vendurl` configuration:
```js
{
"vendurl": {
"destination": "./src/lib", // default: "./vendor"
"provider": "https://unpkg.com/", // default: "https://esm.sh/"
"bundle": false, // esm.sh specific. default: true
"packages": { }
}
}
```
#### Specifier options
The specifier can be an object:
```js
{
"vendurl": {
"packages": {
"leftpad.cjs": {
"specifier": "[email protected]/index.js",
"provider": "https://unpkg.com/",
"bundle": false
},
"robots.txt": {
"specifier": "https://raw.githubusercontent.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/master/robots.txt/robots.txt",
"destination": "./public"
}
}
}
}
```
#### npm postinstall
```js
{
"scripts": {
"postinstall": "vendurl"
},
"vendurl": {
"packages": { }
}
}
```
### CLI Options and Exit Codes
> [!IMPORTANT]
> `vendurl` will exit with code `1` if there are any errors, but will optimistically continue to vendor what it can.
Verbose output is available with `--verbose` or `-v`:
```sh
npx vendurl --verbose
```
Use the `--clean` flag to nuke the destination folder before downloading (this will not clean destinations specified in object specifiers):
```sh
npx vendurl --clean
```
Pass `--yes` to skip the confirmation prompt:
```sh
npx vendurl --clean --yes
```
## How it works
Mostly with `fetch` and `fs`: download the file and save it. `index.js` is brief and has no dependencies; check it out!
`vendurl` leans on [esm.sh](https://esm.sh) conventions to resolve specific versioned bundles.
### Module Resolution
For example, the specifier of "chalk" (currently) resolves to the cached build as such:
`chalk` → `chalk@latest` → `[email protected]` → `/v132/[email protected]/es2021/chalk.bundle.mjs`.
## Development
`./test/mock-project/` has a simple `package.json` with a few package entries to test with.
`./test/test.sh` runs a simple test procedure and executes `./test/mock-project/index.js`.
## FAQ
**Does it work for all packages?**
Not likely. The dependency graphs for some "modern" tools are a mess and rely on a build step. `vendurl` does work well for simpler packages that aren't published in a way you'd like to consume -- e.g. the entire test suite and 17 dist versions are shipped to npmjs.org...
*If there's a package you think should work, but it doesn't, please open an issue.* 🙏🏻
**Just JavaScript?**
`vendurl` will optimistically download any URL and put it in "./vendor". A `.css` file would probably work, but at that point you're venturing into build pipeline territory 🐉
**ESBuild options, WASM, and other esm.sh features?**
Good idea! I can work on that or feel free to send a PR.
In the meantime: currently, search params on the specifier are not stripped, so you could try that!
**I'm getting esm.sh HTTP errors.**
You may want to check [esm.sh's status page](https://esm.instatus.com).