mdcms/velox-docs/pages/installation.md

title	sort	section-id	keywords	description	language
Installation	110	getting-started	install, setup, npm, yarn, pnpm, bun, node, requirements	How to install Velox and set up your development environment	en

Installation

This page covers everything you need to install Velox and get your development environment ready to build production applications.

System Requirements

Before installing Velox, ensure your system meets the following requirements:

Requirement	Minimum Version	Recommended
Node.js	20.0.0	22.x LTS
npm	9.0.0	10.x
Operating system	macOS 12, Ubuntu 22.04, Windows 10	Latest stable
RAM	2 GB	8 GB+
Disk space	500 MB	2 GB (for caches)

Velox's Rust-based build system (Velocitor) ships as a pre-compiled binary for macOS (arm64 + x86_64), Linux (x86_64 + aarch64), and Windows (x86_64). You do not need a Rust toolchain installed on your machine.

Installing the Velox CLI

The Velox CLI (velox) is the primary tool for scaffolding projects, running the development server, and triggering builds. Install it globally with your preferred package manager:

# npm
npm install -g velox-cli

# yarn
yarn global add velox-cli

# pnpm
pnpm add -g velox-cli

# bun
bun add -g velox-cli

After installation, verify the CLI is available:

velox --version
# velox-cli v1.4.0

Creating a New Project

Using create-velox (Recommended)

The easiest way to start a new Velox project is through the create-velox initialiser. It interactively walks you through project setup:

npm create velox@latest

You will be asked:

1. Project name — used as the directory name and initial package name
2. Template — choose from minimal, blog, docs, dashboard, or e-commerce
3. TypeScript or JavaScript — TypeScript is strongly recommended
4. Package manager — the scaffolder will use this for the initial install

For non-interactive use, pass flags directly:

npm create velox@latest my-app -- --template minimal --ts --pm pnpm

Manual Installation

If you prefer to configure everything from scratch:

mkdir my-app && cd my-app
npm init -y
npm install velox
npm install -D velox-cli typescript @types/node

Create a minimal velox.config.ts:

import { defineConfig } from 'velox';

export default defineConfig({
  app: {
    name: 'my-app',
  },
});

Installing Dependencies in an Existing Project

If you are adding Velox to an existing TypeScript project:

npm install velox
npm install -D velox-cli

Then add the following scripts to your package.json:

{
  "scripts": {
    "dev": "velox dev",
    "build": "velox build",
    "start": "velox start",
    "preview": "velox preview"
  }
}

Node Version Management

We recommend using a Node version manager to ensure you always have the correct version. Popular options:

# nvm (macOS/Linux)
nvm install 22
nvm use 22

# fnm (fast, cross-platform)
fnm install 22
fnm use 22

# volta (pins versions per project)
volta install node@22

You can also pin the Node version for your project by adding a .nvmrc or .node-version file:

22

Environment Variables

Velox reads environment variables from .env files at the project root. The following files are loaded in order (later files override earlier ones):

File	Loaded in	Committed to git?
.env	All environments	Usually yes (no secrets)
.env.local	All environments	No (gitignored)
.env.development	velox dev only	Usually yes
.env.production	velox build / velox start	Usually yes
.env.test	Test runs	Usually yes

Variables prefixed with PUBLIC_ are exposed to the browser. All other variables remain server-side only.

# .env
PUBLIC_APP_NAME=My Velox App
DATABASE_URL=postgres://localhost:5432/mydb
SECRET_API_KEY=do-not-expose-this

Updating Velox

To update Velox to the latest version within your project:

npm install velox@latest
npm install -D velox-cli@latest

To check whether updates are available without applying them:

velox upgrade --check

Troubleshooting Installation

velox command not found after global install Ensure your package manager's global bin directory is in your PATH. For npm, run npm config get prefix and add the bin subdirectory to your shell profile.

Velocitor binary fails to run on Linux Some minimal Linux environments (e.g., Alpine Linux) may be missing the glibc version Velocitor requires. Install glibc compatibility libraries or use the musl build:

npm install velox@latest --velox-binary-variant=musl

Windows Defender flags the Velocitor binary This is a false positive. Add an exclusion for your project's node_modules/.velox-bin/ directory.

Next, follow the Quick Start guide to build your first Velox application.