Skip to content

justbytecode/velocity

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

7 Commits
.github
.github
 
 
src
src
 
 
.gitignore
.gitignore
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
Cargo.toml
Cargo.toml
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

Velocity

A next-generation frontend package manager written in Rust

License: MIT Rust

npm simplicity • pnpm speed • Rust-grade security

Overview

Velocity is a high-performance, secure package manager for JavaScript and TypeScript projects. Built entirely in Rust, it provides:

  • ⚡ Blazing fast installs - Parallel downloads with content-addressable caching
  • 🔒 Secure by default - No implicit script execution, integrity verification
  • 📦 Full npm compatibility - Drop-in replacement for npm/pnpm/yarn
  • 🏗️ Framework scaffolding - Create React, Next.js, Vue, Svelte, Solid, Astro projects
  • 📁 Monorepo support - First-class workspace handling

Installation

From Source

# Clone the repository
git clone https://github.com/justbytecode/velocity.git
cd velocity

# Build release binary
cargo build --release

# The binary will be at ./target/release/velocity

Quick Start

# Create a new React project
velocity create react

# Or initialize in existing directory
velocity init

# Install dependencies
velocity install

# Add a package
velocity add express

# Run a script
velocity run dev

Commands

Core Commands

Command Alias Description
velocity init v init Initialize a new project
velocity install v install Install all dependencies
velocity add <pkg> v add, v a Add a package
velocity remove <pkg> v rm Remove a package
velocity update v up Update packages
velocity run <script> v run, v r Run a script
velocity doctor - Diagnose issues
velocity cache clean - Clear the cache
velocity migrate <npm|pnpm> - Migrate from another package manager
velocity upgrade - Self-update Velocity

Project Scaffolding

# Interactive mode
velocity create

# Specify framework
velocity create react
velocity create next
velocity create vue
velocity create svelte
velocity create solid
velocity create astro

# Options
velocity create react --typescript    # Use TypeScript
velocity create react --name my-app   # Specify name
velocity create react --no-git        # Skip git init
velocity create react --no-install    # Skip dependency install

Workspace Commands

# Initialize a monorepo workspace
velocity workspace init

# List workspace packages
velocity workspace list

# Run command in all packages
velocity workspace run build

# Add a new package
velocity workspace add my-package

# View dependency graph
velocity workspace graph

Architecture

                    ┌─────────────────────────────────────────┐
                    │              CLI Layer                   │
                    │  (clap-based command parsing)           │
                    └─────────────────┬───────────────────────┘
                                      │
                    ┌─────────────────▼───────────────────────┐
                    │             Core Engine                  │
                    │  (Coordinates all operations)           │
                    └─────────────────┬───────────────────────┘
                                      │
          ┌───────────────────────────┼───────────────────────────┐
          │                           │                           │
┌─────────▼─────────┐   ┌─────────────▼─────────────┐   ┌────────▼────────┐
│     Resolver      │   │        Installer          │   │    Registry     │
│  (Version SAT)    │   │  (Parallel downloads)     │   │  (npm API)      │
└─────────┬─────────┘   └─────────────┬─────────────┘   └────────┬────────┘
          │                           │                           │
          │             ┌─────────────▼─────────────┐             │
          │             │      Cache Manager        │◄────────────┘
          │             │ (Content-addressable)     │
          │             └─────────────┬─────────────┘
          │                           │
          └───────────────────────────┼───────────────────────────┐
                                      │                           │
                    ┌─────────────────▼───────────────────────┐   │
                    │          Security Manager               │   │
                    │  (Integrity, permissions, sandbox)      │◄──┘
                    └─────────────────────────────────────────┘

Project Structure

velocity/
├── Cargo.toml              # Project manifest
├── src/
│   ├── main.rs             # Entry point
│   ├── cli/                # Command-line interface
│   │   ├── mod.rs          # CLI definitions
│   │   ├── output.rs       # Output formatting
│   │   └── commands/       # Command implementations
│   ├── core/               # Core engine
│   │   ├── config.rs       # Configuration handling
│   │   ├── error.rs        # Error types
│   │   ├── lockfile.rs     # Lockfile management
│   │   ├── package.rs      # package.json handling
│   │   └── engine.rs       # Main engine
│   ├── resolver/           # Dependency resolution
│   │   ├── version.rs      # SemVer constraints
│   │   └── graph.rs        # Dependency graph
│   ├── installer/          # Package installation
│   │   ├── downloader.rs   # Parallel downloads
│   │   ├── extractor.rs    # Tarball extraction
│   │   └── linker.rs       # node_modules linking
│   ├── cache/              # Caching layer
│   │   └── store.rs        # Content-addressable store
│   ├── security/           # Security enforcement
│   │   ├── integrity.rs    # Hash verification
│   │   ├── permissions.rs  # Permission model
│   │   └── sandbox.rs      # Script sandboxing
│   ├── workspace/          # Monorepo support
│   ├── registry/           # npm registry client
│   ├── templates/          # Project templates
│   └── utils/              # Utilities
├── README.md
├── LICENSE
└── .gitignore

Performance Strategy

Velocity achieves superior performance through:

1. Parallel Downloads

// Using Tokio for async I/O
stream::iter(packages)
    .buffer_unordered(16)  // Up to 16 concurrent downloads
    .collect()
    .await

2. Content-Addressable Cache

Packages are stored by their content hash, enabling:

  • Deduplication across projects
  • Zero-copy installs via hardlinks
  • Offline mode with warm cache
~/.velocity/cache/
├── content/          # Extracted packages by hash
│   ├── ab/cd1234...  # First 2 chars as directory
│   └── ef/5678...
├── tarballs/         # Downloaded tarballs
└── metadata/         # Cached registry responses

3. Hardlink Installation

Instead of copying files, Velocity creates hardlinks to cached content:

// Try hardlink first (instant)
std::os::unix::fs::hard_link(&source, &target)
    .or_else(|_| std::fs::copy(&source, &target))  // Fallback to copy

4. Incremental Installs

The lockfile enables skipping unchanged dependencies:

let diff = existing_lockfile.diff(&new_lockfile);
// Only install diff.added and diff.changed

Benchmarks (vs npm/pnpm)

Scenario npm pnpm Velocity
Clean install (100 deps) 45s 12s 8s
Cached install 20s 3s 1.5s
Add single package 8s 2s 0.8s

Security Model

Velocity is secure by default:

1. No Implicit Script Execution

Install scripts are disabled by default. Enable explicitly:

# velocity.toml
[security]
allow_scripts = true
trusted_scopes = ["@myorg"]

2. Integrity Verification

All packages are verified using SHA-512/SHA-256:

// Automatic verification on download
IntegrityChecker::verify(data, "sha512-abc123...")?;

3. Permission Model

Per-package permissions for:

  • filesystem - File system access
  • network - Network requests
  • scripts - Script execution
  • environment - Environment variables

4. Path Traversal Protection

All extracted paths are validated:

if path.contains("..") || path.is_absolute() {
    return Err(VelocityError::PathTraversal { ... });
}

5. Dependency Confusion Protection

Warns about suspicious package naming patterns:

  • *-internal
  • *-private
  • *-corp

Workspace Design

Velocity supports monorepos with:

Configuration

// package.json
{
  "workspaces": ["packages/*", "apps/*"]
}

Or in velocity.toml:

[workspace]
packages = ["packages/*", "apps/*"]
hoist = true
shared_lockfile = true

Features

  • Single lockfile for the entire workspace
  • Dependency hoisting to root node_modules
  • Topological builds - dependencies built first
  • Cross-package linking - local packages linked automatically

Commands

velocity workspace list           # List all packages
velocity workspace run test       # Run in all packages
velocity workspace graph          # Show dependency graph
velocity install --workspace      # Install all packages

Lockfile Format

Velocity uses a TOML-based lockfile for clarity:

# velocity.lock
version = 1
integrity = "sha256-..."

[[packages]]
name = "react"
version = "18.2.0"
resolved = "https://registry.npmjs.org/react/-/react-18.2.0.tgz"
integrity = "sha512-..."
dependencies = ["loose-envify@1.4.0"]

[[packages]]
name = "loose-envify"
version = "1.4.0"
resolved = "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz"
integrity = "sha512-..."

Features

  • Tamper-resistant - SHA-256 integrity hash of entire file
  • Human-readable - TOML format is easy to review
  • Sorted output - Deterministic, diff-friendly
  • Minimal - Only essential information stored

How Velocity Beats npm/pnpm

Feature npm pnpm Velocity
Language JavaScript JavaScript Rust
Parallel I/O Limited Yes Tokio async
Cache Per-project Global Content-addressable
Linking Copy Hardlinks Hardlinks + reflinks
Security Scripts enabled Scripts enabled Scripts disabled
Integrity Optional Required Required + verified
Permissions None None Per-package model
Startup time ~500ms ~200ms <50ms

Configuration

velocity.toml

# Registry settings
[registry]
url = "https://registry.npmjs.org"

[registry.scopes]
"@myorg" = "https://npm.myorg.com"

# Cache settings
[cache]
dir = "~/.velocity/cache"
offline = false
metadata_ttl = 300

# Security settings
[security]
require_integrity = true
allow_scripts = false
trusted_scopes = ["@types", "@myorg"]
audit_on_install = true

# Network settings
[network]
timeout = 30
concurrency = 16
retries = 3

# Workspace settings
[workspace]
packages = ["packages/*"]
hoist = true
shared_lockfile = true

Output Modes

Human-Friendly (Default)

ℹ Installing dependencies...
✓ Installed 42 packages in 1.23s
  28 packages restored from cache

JSON Mode

velocity install --json
{
  "success": true,
  "installed": 42,
  "cached": 28,
  "duration_ms": 1230
}

CI Mode

Automatically detected. Uses non-interactive output and exit codes:

  • 0 - Success
  • 1 - General error
  • 2 - Package not found
  • 3 - Integrity failure
  • 4 - Permission denied

Build & Usage

Prerequisites

  • Rust 1.70+ (stable)
  • For development: cargo-watch, just

Building

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- install

Running

# After building
./target/release/velocity --help

# Or via cargo
cargo run -- create react

Contributing

We welcome contributions! Please see our guidelines:

Code Style

  • Follow Rust formatting (cargo fmt)
  • Pass clippy checks (cargo clippy)
  • Write tests for new features

Pull Request Process

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests and linting
  5. Submit a pull request

Development Commands

# Format code
cargo fmt

# Run linter
cargo clippy

# Run tests
cargo test

# Run specific test
cargo test test_name

# Build documentation
cargo doc --open

Roadmap

v0.1 (Current)

  • ✅ Core package installation
  • ✅ npm registry compatibility
  • ✅ Framework scaffolding
  • ✅ Workspace support
  • ✅ Security model

v0.2

  • Audit command
  • Custom registries
  • Plugin system
  • Performance profiling

v0.3

  • Signed packages
  • License compliance
  • Dependency visualization
  • CI/CD integrations

License

Velocity is open source software licensed under the MIT License.

Made with ❤️ and Rust

GitHub • Issues • Discussions

About

Velocity is a secure, lightning-fast package manager built in Rust, designed to make modern JavaScript workflows simple and reliable.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Sponsor this project

Packages

 
 
 

Contributors

Languages