Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vltpkg/vsr
a minimal npm-compatible package registry
https://github.com/vltpkg/vsr
bun cloudflare javascript nodejs npm pnpm registry serverless-framework vlt yarn
Last synced: about 9 hours ago
JSON representation
a minimal npm-compatible package registry
- Host: GitHub
- URL: https://github.com/vltpkg/vsr
- Owner: vltpkg
- License: other
- Created: 2024-08-19T19:59:05.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-01-10T17:24:15.000Z (16 days ago)
- Last Synced: 2025-01-19T06:06:23.250Z (7 days ago)
- Topics: bun, cloudflare, javascript, nodejs, npm, pnpm, registry, serverless-framework, vlt, yarn
- Language: JavaScript
- Homepage: https://www.vlt.sh/serverless-registry
- Size: 474 KB
- Stars: 202
- Watchers: 3
- Forks: 11
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-repositories - vltpkg/vsr - a minimal npm-compatible package registry (JavaScript)
README
# **vlt** serverless registry (`vsr`)
`vsr` aims to be a minimal "npm-compatible" registry which replicates the core features found in `registry.npmjs.org` as well as adding net-new capabilities.
**Table of Contents:**
- [Quick Starts](#quick-starts)
- [Requirements](#requirements)
- [API](#api)
- [Compatibility](#compatibility)
- [Comparisons](#comparisons)
- [Roadmap](#roadmap)
- [License](#license)
### Quick Starts
#### Local
You can quickly get started by installing/executing `vsr` with the following command:
```bash
npx -y vltpkg/vsr
```
#### Production
You can deploy `vsr` to [Cloudflare](https://www.cloudflare.com/) in under 5 minutes, for free, with a single click (coming soon).
Alternatively, you can deploy to production using [`wrangler`](https://www.npmjs.com/package/wrangler) after following the **Development** quick start steps.
#### Development
```bash
# clone the repo
git clone https://github.com/vltpkg/vsr.git
# navigate to the repository directory
cd ./vsr
# install the project's dependencies
npm install
# run tbe development script
npm run dev
```
### Requirements
#### Production
- [Cloudflare (free account at minimum)](https://www.cloudflare.com/en-ca/plans/developer-platform/)
- Workers (free: 100k requests /day)
- D1 Database (free: 100k writes, 5M reads /day & 5GB Storage /mo)
- R2 Bucket (free: 1M writes, 10M reads & 10GB /mo)
> Note: all usage numbers & pricing documented is as of **October 24th, 2024**. Plans & metering is subject to change at Cloudflare's discretion.
#### Development
- `git`
- `node`
- `npm`
### Granular Access Tokens
All tokens are considered "granular access tokens" (GATs). Token entries in the database consist of 3 parts:
- `token` the unique token value
- `uuid` associative value representing a single user/scope
- `scope` value representing the granular access/privileges
#### `scope` as a JSON `Object`
A `scope` contains an array of privileges that define both the type(s) of & access value(s) for a token.
> [!NOTE]
> Tokens can be associated with multiple "types" of access
- `type(s)`:
- `pkg:read` read associated packages
- `pkg:read+write` write associated packages (requires read access)
- `user:read` read associated user
- `user:read+write` write associated user (requires read access)
- `value(s)`:
- `*` an ANY selector for `user:` or `pkg:` access types
- `~` user selector for the `user:` access type
- `@/` package specific selector for the `pkg:` access type
- `@/*` glob scope selector for `pkg:` access types
> [!NOTE]
> - user/org/team management via `@` is not supported at the moment
Scope Examples
##### End-user/Subscriber Persona
- specific package read access
- individual user read+write access
```json
[
{
"values": ["@organization/package-name"],
"types": {
"pkg": {
"read": true,
}
}
},
{
"values": ["~johnsmith"],
"types": {
"user": {
"read": true,
"write": true,
}
}
}
]
```
##### Team Member/Maintainer Persona
- scoped package read+write access
- individual user read+write access
```json
[
{
"values": ["@organization/*"],
"types": {
"pkg": {
"read": true
}
}
},
{
"values": ["~johnsmith"],
"types": {
"user": {
"read": true,
"write": true,
}
}
}
]
```
##### Package Publish CI Persona
- organization scoped packages read+write access
- individual user read+write access
```json
[
{
"values": ["@organization/package-name"],
"types": {
"pkg": {
"read": true
}
}
},
{
"values": ["~johnsmith"],
"types": {
"user": {
"read": true,
"write": true,
}
}
}
]
```
##### Organization Admin Persona
- organization scoped package read+write access
- organization users read+write access
```json
[
{
"values": ["@company/*"],
"types": {
"pkg": {
"read": true,
"write": true
},
"user": {
"read": true,
"write": true
}
}
}
]
```
##### Registry Owner/Admin Persona
```json
[
{
"values": ["*"],
"types": {
"pkg": {
"read": true,
"write": true
},
{
"user": {
"read": true,
"write": true
}
}
}
}
]
```
### API
We have rich, interactive API docs out-of-the-box with the help of our friends [Scalar](https://scalar.com/). The docs can be found at the registry root when running `vsr` locally (ex. run `npx -y vltpkg/vsr` &/or check out this repo & run `npm run dev`)
### `npm` Client Compatibility
The following commands should work out-of-the-box with `npm` & any other `npm` "compatible" clients although their specific commands & arguments may vary (ex. `vlt`, `yarn`, `pnpm` & `bun`)
#### Configuration
To use `vsr` as your registry you must either pass a registry config through a client-specific flag (ex. `--registry=...` for `npm`) or define client-specific configuration which stores the reference to your registry (ex. `.npmrc` for `npm`). Access to the registry & packages is private by default although an `"admin"` user is created during setup locally (for development purposes) with a default auth token of `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`.
```ini
; .npmrc
registry=http://localhost:1337
//localhost:1337/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
#### Supported `npm` Commands
- ✅ implemented
- ⏳ in progress
- 🕤 planned to support
| Support | Commannd |
| :--: | :-- |
| ✅ | `access` |
| ✅ | `access list packages` |
| ✅ | `access get status` |
| ❌ | `access set status` |
| ❌ | `access set mfa` |
| ❌ | `access grant` |
| ❌ | `access revoke` |
| 🕤 | `adduser` - `PUT /-/org/@/`: Adds/updates a user (requires admin privileges) |
| ❌ | `audit` |
| ✅ | `bugs` |
| ❌ | `dist-tag add` |
| ❌ | `dist-tag rm` |
| ❌ | `dist-tag ls` |
| ✅ | `deprecate` |
| ✅ | `docs` |
| ✅ | `exec` |
| ❌ | `hook` |
| ✅ | `install` |
| ❌ | `login` |
| ❌ | `logout` |
| ❌ | `org` |
| ✅ | `outdated` |
| ❌ | `owner add` |
| ❌ | `owner rm` |
| ❌ | `owner ls` |
| ✅ | `ping` |
| ❌ | `profile enable-2fa` |
| ❌ | `profile disable-2fa` |
| ✅ | `profile get` |
| 🕤 | `profile set` - `PUT /-/npm/v1/user`: Updates a user (requires auth) |
| ✅ | `publish` |
| ✅ | `repo` |
| ❌ | `search` |
| ❌ | `star` |
| ❌ | `team` |
| ✅ | `view` |
| ✅ | `whoami` |
- ✅ supported
- ❌ unsupported
### Comparisons
| Feature | `vsr` | `verdaccio` | `jsr` |
| -- | :-: | :-: | :-: |
| Serverless | ✅ | ❌ | ❌ |
| JavaScript Backend | ✅ | ✅ | ❌ |
| Granular Access/Permissions | ✅ | ✅ | ❌ |
| Proxy Upstream Registries | ⏳ | ✅ | ❌ |
| Unscoped Package Names | ✅ | ✅ | ❌ |
| npm Package Publishing | ✅ | ✅ | ❌ |
| npm Package Installation | ✅ | ✅ | ✅* |
| CDN | 🕤 | ❌ | ✅ |
| ESM | 🕤 | ❌ | ✅ |
| Manifest Validation | ✅ | ❌ | ❌ |
| Plugins | ⏳ | ✅ | ❌ |
| Events/Hooks | 🕤 | ✅ | ❌ |
| Programmatic API | ❌ | ✅ | ❌ |
| Web Interface | 🕤 | ✅ | ✅ |
| Search | 🕤 | ✅ | ✅ |
| First-Class Typescript | ❌ | ❌ | ✅ |
| API Documentation Generation | ❌ | ❌ | ✅ |
| Multi-Cloud | 🕤 | ✅ | ✅ |
| **Azure DevOps Artifacts** Upstream | ✅ | ✅ | ✅ |
| **JFrog Artifactory** Upstream | ✅ | ✅ | ❌ |
| **Google Artifact Registry** Upstream | ✅ | ✅ | ❌ |
> `*` requires `jsr`-specific tooling or use a modified package name when using traditional npm clients (ref. https://jsr.io/docs/npm-compatibility)
### Roadmap
| Status | Feature |
| :--: | :-- |
| ✅ | api: minimal package metadata |
| ✅ | api: full package manifests |
| ✅ | api: publishing private, scoped packages |
| ✅ | api: package manifest validation |
| ✅ | api: admin user management (add/update/remove users) |
| ✅ | api: user token management (add/update/remove tokens) |
| ✅ | web: docs portal |
| ✅ | api: unscoped packages |
| ⏳ | web & api: custom dist-tags (`latest` is supported) |
| ⏳ | web & api: token rate-limiting |
| 🕤 | web & api: search |
| 🕤 | web & api: staging |
| 🕤 | web: admin user management |
| 🕤 | web: user registration |
| 🕤 | web: user login (ex. `npm login` / `--auth-type=web`) |
| 🕤 | web: user account management |
### License
This project is licensed under the [Functional Source License](https://fsl.software) ([**FSL-1.1-MIT**](LICENSE.md)).