Nub

https://nubjs.com/docs
Admin
Nub is an all-in-one Rust-written toolkit for Node.js that runs TypeScript files and scripts,...
Tokens:122,759
Snippets:1,165
Trust Score:6.8
Update:2 days ago
Show doc for...
Tokens:
Raw
### Verify build logs

Source: https://nubjs.com/docs/deployment/vercel

Example of the build log output showing the installed Nub version and the build process.

```text
Installed nub v0.9.6 (with nubx) to /vercel/.nub/bin/nub
Removing existing node_modules...
dependencies:
+ kleur@4.1.5
$ nub build.ts
Built with nub-on-node on v24.15.0
Build Completed in /vercel/output [4s]
```

--------------------------------

### Read and write individual config fields

Source: https://nubjs.com/docs/config

Shows the remaining config commands: set, get, delete, and path. Writes go to ./nub.jsonc by default. The get example shows the value for install.linker is 'hoisted'.

```shell
nub config set nodeCompat true                # writes ./nub.jsonc
nub config get install.linker                 # hoisted
nub config delete install.minimumReleaseAge
nub config path                               # the global file's location
```

--------------------------------

### Getting started with Nub commands

Source: https://nubjs.com/docs

Basic commands for installing Nub, running TypeScript files, installing dependencies, executing scripts, and running local CLI tools.

```bash
npm install -g @nubjs/nub
nub index.ts             # run a TypeScript file
nub install              # install dependencies (pnpm-compatible)
nub run dev              # run a package.json script
nubx prisma generate     # run a CLI from node_modules/.bin
```

--------------------------------

### Handle optional dependency build failures

Source: https://nubjs.com/docs/install

Example output when an optional dependency fails to build, allowing the install process to continue.

```bash
# captured: nub 0.7.5, optfail@1.0.0 postinstall exits 3, allowScripts set
$ nub install
WARN optfail@1.0.0 is an optional dependency and failed to build;
     continuing without it: lifecycle script postinstall failed for
     optfail@1.0.0: script `postinstall` exited with code 3
     code=WARN_NUB_OPTIONAL_BUILD_FAILED
optionalDependencies:
+ optfail@1.0.0
```

--------------------------------

### Configure platform-specific installation axes

Source: https://nubjs.com/docs/install

Examples of using repeatable flags to target specific platform variants for optional dependencies.

```bash
nub install --os linux                  # Linux binaries, host CPU
nub install --os current,linux          # this machine and Linux
nub install --os '*' --cpu '*'          # every platform variant
```

--------------------------------

### Install dependencies with bun.lock

Source: https://nubjs.com/docs/install/bun

Demonstrates installing packages in a project using the Bun 1.2+ text-based lockfile format.

```bash
# captured: nub 0.0.44 — install in a bun.lock project, then diff the lock
$ nub install
dependencies:
+ is-odd@3.0.1

nub 0.0.44 · ✓ installed 2 packages in 38ms

$ diff bun.lock bun.lock.orig    # ✓ byte-identical (no output)
$ ls pnpm-lock.yaml              # ✓ no foreign lockfile written
ls: pnpm-lock.yaml: No such file or directory
```

--------------------------------

### Handle name collisions during installation

Source: https://nubjs.com/docs/install

Example warning message displayed when an executable name already exists in the target directory and was not created by Nub.

```text
$ nub add -g cowsay
warning: not linking cowsay — /Users/you/.local/bin/cowsay already
exists and was not created by this tool; remove it to link cowsay
```

--------------------------------

### Adjust cooling window with flags

Source: https://nubjs.com/docs/install

Examples of handling installation failures due to version age by disabling or shortening the window, or excluding specific packages.

```bash
$ nub add some-tool
ERR_NUB_NO_MATURE_MATCHING_VERSION       # ❌ every version is too new

$ nub add some-tool --minimum-release-age=0                 # off, this run
$ nub add some-tool --minimum-release-age=2h                # or shorten it
$ nub add some-tool --minimum-release-age-exclude=some-tool # exempt one
```

--------------------------------

### Global configuration absolute path example

Source: https://nubjs.com/docs/config

Example of setting an absolute or home-relative path in the global configuration file.

```jsonc
{
  // ...
  "envFile": ["~/secrets/.env"]
}
```

--------------------------------

### Configure install.minimumReleaseAge

Source: https://nubjs.com/docs/config

Example of setting a minimum release age for dependencies in nub.jsonc.

```json
{
  // ...
  "install": {
    "minimumReleaseAge": "3d"
  }
}
```

--------------------------------

### Run install with hoisted linker

Source: https://nubjs.com/docs/install/virtual-store

Use the --node-linker hoisted flag to perform a single installation with a flat layout without modifying your configuration file.

```bash
nub install --node-linker hoisted
```

--------------------------------

### Configure install.publicHoist

Source: https://nubjs.com/docs/config

Example of hoisting specific packages to the project's top-level node_modules.

```json
{
  // ...
  "install": {
    "publicHoist": ["@types/*", "*eslint*"]
  }
}
```

--------------------------------

### Install and run build command

Source: https://nubjs.com/docs/deployment/cloudflare

Command to install dependencies and run the build when skipping Cloudflare's default install.

```bash
nub install && nub run build
```

--------------------------------

### Install optional dependencies for specific platforms

Source: https://nubjs.com/docs/install

Use --os and --cpu flags to install specific prebuilt binaries for cross-platform builds.

```bash
nub install --os linux --cpu x64
```

--------------------------------

### Configure install.linker with hoisted strategy

Source: https://nubjs.com/docs/config

Example of setting the linker strategy to hoisted in nub.jsonc.

```json
{
  // ...
  "install": {
    "linker": "hoisted"
  }
}
```

--------------------------------

### Automatic build script execution for curated packages

Source: https://nubjs.com/docs/install

Example of a successful install where esbuild meets all three gates and runs its build scripts.

```bash
# captured: nub 0.0.44, pnpm, esbuild@0.21.5 — no allowScripts entry
$ nub install
WARN defaultTrust: running build scripts for esbuild@0.21.5  # ✓ gates ok
dependencies:
+ esbuild@0.21.5
```

--------------------------------

### Installing a plugin package with nub add

Source: https://nubjs.com/docs/plugins

Install a plugin package that ships a nub-<verb> bin using `nub add -D`. After installation, the verb resolves and runs the plugin.

```bash
nub add -D nub-changeset   # ships a nub-changeset bin
nub changeset              # now resolves and runs it
```

--------------------------------

### Install Canary Build

Source: https://nubjs.com/docs

Install the nightly canary build of NubJS using the provided install script.

```bash
curl -fsSL https://nubjs.com/install.sh | bash -s canary
```

--------------------------------

### nub.jsonc envFile configuration example

Source: https://nubjs.com/docs/runtime/env

Example nub.jsonc configuration setting envFile to an array of files. Later files win. This applies to every run from the project root.

```jsonc
{
  // ...
  "envFile": [".env", ".env.local"]  // later files win
}
```

--------------------------------

### Using nubjs/nub/install for dependency installation

Source: https://nubjs.com/docs/deployment/github-action

Replaces standard package manager install commands to handle installation and caching automatically.

```yaml
  - uses: actions/setup-node@v4
    with:
      node-version: 22
      cache: npm
- run: npm ci
- uses: nubjs/nub/install@v0
  - run: npm test
```

--------------------------------

### Enable npm install routing

Source: https://nubjs.com/docs/pm/pm-shim

Run this command to opt-in to routing npm install and ci commands through the Nub engine.

```bash
nub pm shim --route-installs
```

--------------------------------

### Global configuration relative path example

Source: https://nubjs.com/docs/config

Example of setting a relative path in the global configuration file, which resolves relative to the config directory.

```jsonc
{
  // ...
  "envFile": [".env.shared"]   // resolves to ~/.config/nub/.env.shared
}
```

--------------------------------

### Example tsconfig.runtime.json

Source: https://nubjs.com/docs/runtime/typescript

A sample configuration file defining compiler options like path aliases.

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  }
}
```

--------------------------------

### nub node install skip behavior

Source: https://nubjs.com/docs/node

Demonstrates that if a version is already available on the PATH, the installation is skipped.

```bash
$ nub node install 26.12.0
Node 26.12.0 is already available on PATH — skipped
```

--------------------------------

### Install NubJS via mise

Source: https://nubjs.com/docs

Use mise to manage and add NubJS to your PATH.

```bash
mise use -g nub
```

--------------------------------

### Install canary build on Windows with PowerShell

Source: https://nubjs.com/docs/faq

Installs the rolling canary release of Nub on Windows. Use this command in PowerShell to get the latest canary version.

```powershell
iex "& { $(irm https://nubjs.com/install.ps1) } canary"
```

--------------------------------

### Configure install.linker with global-virtual-store

Source: https://nubjs.com/docs/config

Example of using the object form for the global-virtual-store strategy, including an eject list for specific packages.

```json
{
  // ...
  "install": {
    "linker": {
      "strategy": "global-virtual-store",
      "eject": ["electron", "@company/native-*"]
    }
  }
}
```

--------------------------------

### TypeScript setup for loaders

Source: https://nubjs.com/docs/runtime/loaders

Install the required type definitions and update tsconfig.json to support Nub's loaders.

```bash
# install the package
npm i -D @nubjs/types @types/node@25

# tsconfig.json
{ "compilerOptions": { "types": ["node", "@nubjs/types"] } }
```

--------------------------------

### Initialize project config file

Source: https://nubjs.com/docs/config

Creates a commented project file with every supported field at the workspace root. Only the schema URL is active. Run from anywhere in the workspace.

```shell
nub config init
```

--------------------------------

### Yarn Plug'n'Play Error

Source: https://nubjs.com/docs/install/virtual-store

Example of the error message displayed when attempting to run nub install in a project configured for Yarn Plug'n'Play.

```text
$ nub install                                                    # ❌
Error: nub: this project is configured for Yarn Plug'n'Play (nodeLinker:
pnp, or Yarn Berry's default) — nub installs a node_modules tree and
doesn't support PnP yet, so the result would diverge from yarn's. Install
with yarn, or set `nodeLinker: node-modules` in .yarnrc.yml.
[ERR_NUB_PNP_UNSUPPORTED]
```

--------------------------------

### Trust downgrade warning during installation

Source: https://nubjs.com/docs/install

Example of Nub skipping a version that lacks expected trust evidence and resolving to a safer version instead.

```bash
# captured: fast-glob → @nodelib/fs.walk → fastq; 1.20.2 hand-published
$ nub install
WARN skipped fastq@1.20.2 (trustPolicy=no-downgrade): earlier published
     version 1.20.0 had trusted publisher but this version has no trust
     evidence; resolved to fastq@1.20.1 instead
     code=WARN_NUB_TRUST_DOWNGRADE_SKIPPED
```

--------------------------------

### Render CLI deployment from prebuilt image

Source: https://nubjs.com/docs/deployment/render

Command to create a web service using an existing image from a container registry.

```bash
render services create \
  --name nub-app \
  --type web_service \
  --image ghcr.io/OWNER/nub-app:COMMIT_SHA \
  --plan free \
  --region oregon \
  --health-check-path /alive \
  --confirm \
  --output json
```

--------------------------------

### Blocked build scripts due to cooling window

Source: https://nubjs.com/docs/install

Example of an install where the cooling gate is closed because the package version is too new, requiring manual approval.

```bash
# captured: nub 0.0.44, esbuild — minimumReleaseAge set past every release
$ nub install
WARN ignored build scripts for 1 package(s): esbuild@0.21.5.
     Run `nub approve-builds` to review and enable them.
     code=WARN_NUB_IGNORED_BUILD_SCRIPTS   # ❌ cooling gate closed
dependencies:
+ esbuild@0.21.5
```

--------------------------------

### Example .env.schema file

Source: https://nubjs.com/docs/runtime/varlock

A declarative schema file defining required environment variables, types, and sensitivity settings.

```text
# @defaultSensitive=false
# @generateTypes(lang="ts", path="env.d.ts")
# ---

# @required @type=port
PORT=3000

# @required @type=enum(development, staging, production)
APP_ENV=development

# @required @sensitive @type=url
DATABASE_URL=

# @required @sensitive @type=string(startsWith=sk-)
STRIPE_SECRET_KEY=
```

--------------------------------

### Nub installation output with ignored overrides

Source: https://nubjs.com/docs/install

Example output showing Nub ignoring an unsupported 'overrides' block in a pnpm project and suggesting the use of 'resolutions' instead.

```bash
# captured: nub 0.7.2, pnpm project with a top-level overrides block
$ nub install
nub: `overrides` ignored — this project uses pnpm, which doesn't apply
it. move these pins to `resolutions`.
dependencies:
+ is-odd@3.0.1
```

--------------------------------

### Example pnpm-workspace.yaml configuration

Source: https://nubjs.com/docs/install/pnpm

A sample configuration file defining packages, catalogs, and named registries.

```yaml
packages:
  - 'packages/*'
catalog:
  lodash.merge: 4.6.2
namedRegistries:
  work: https://npm.example.com/
```

--------------------------------

### Configure install.minimumReleaseAge with exclusions

Source: https://nubjs.com/docs/config

Example of setting a minimum release age while excluding specific packages from the gate.

```json
{
  // ...
  "install": {
    "minimumReleaseAge": "3d",
    "minimumReleaseAgeExclude": [
      "@company/*",
      "typescript"
    ]
  }
}
```

--------------------------------

### Web service Dockerfile with EXPOSE

Source: https://nubjs.com/docs/deployment/docker

Dockerfile for a web service using the official Nub image. Copies manifests before source to keep dependency installation cached, exposes port 8080, and runs the start command.

```dockerfile
FROM ghcr.io/nubjs/nub:0.9.6

COPY --chown=node:node package.json package-lock.json ./
RUN nub ci

COPY --chown=node:node . .
EXPOSE 8080
CMD ["nub", "run", "start"]
```

--------------------------------

### Official Nub Dockerfile

Source: https://nubjs.com/docs/deployment/docker

Base Dockerfile for running a Nub project using the official image. Copies package files, installs dependencies with nub ci, copies source, and runs the start command. The image runs as the non-root node user, so files are copied with --chown=node:node.

```dockerfile
FROM ghcr.io/nubjs/nub:0.9.6
COPY --chown=node:node package.json package-lock.json ./
RUN nub ci
COPY --chown=node:node . .
CMD ["nub", "run", "start"]
```

--------------------------------

### Install via nub installer

Source: https://nubjs.com/docs/standalone

Install the nubr command globally using the shell script installer, which provisions Node automatically if missing.

```bash
curl -fsSL https://nubjs.com/install.sh | bash   # macOS / Linux
irm https://nubjs.com/install.ps1 | iex           # Windows (PowerShell)
```

--------------------------------

### List available install flags

Source: https://nubjs.com/docs/install

Common flags supported by the nub install command for controlling installation behavior.

```bash
--frozen-lockfile / --no-frozen-lockfile / --prefer-frozen-lockfile
--prod, -P            # production install
--dev, -D
--ignore-scripts
--pnpmfile <path>     # run this one instead of the project's
--global-pnpmfile <path>
--ignore-pnpmfile
--no-optional
--offline / --prefer-offline
--lockfile-only
--force
--node-linker
--registry
--dir, -C             # pnpm's spelling, not npm's --prefix
--reporter <name>     # default, append-only, silent
--silent, -s          # alias for --reporter=silent
--loglevel <level>    # debug, info, warn, error, silent
--os <os>             # which platforms' optional deps to install
--cpu <arch>
--libc <libc>
```

--------------------------------

### Configure install.linker with isolated strategy

Source: https://nubjs.com/docs/config

Example of using the object form for the isolated strategy, including a hoist list for fallback dependency resolution.

```json
{
  // ...
  "install": {
    "linker": {
      "strategy": "isolated",
      "hoist": ["*eslint*", "@types/*"]
    }
  }
}
```

--------------------------------

### Provisioning a pinned Node.js version

Source: https://nubjs.com/docs/node

Demonstrates pinning a Node.js version using a .node-version file and running a script with nub.

```bash
$ echo 26.12.0 > .node-version
$ nub index.ts
Using Node.js 26.12.0 (resolved from .node-version)
Installing from nodejs.org... (24 MB)
Installed in 8.0s
# ...your script runs, on exactly the Node you pinned
```

--------------------------------

### Configure install.publicHoist with wildcard

Source: https://nubjs.com/docs/config

Example of hoisting all packages to the project's top-level node_modules using a wildcard.

```json
{
  // ...
  "install": {
    "publicHoist": ["*"]
  }
}
```

--------------------------------

### Using nubjs/nub/setup-node

Source: https://nubjs.com/docs/deployment/github-action

This action integrates with actions/setup-node to install nub and enable package-manager shims by default. It automatically manages Node.js versions based on project pins.

```yaml
- uses: actions/checkout@v4
- uses: nubjs/nub/setup-node@v0
- run: npm ci
- run: npm test
```

--------------------------------

### Running localStorage with a backing file

Source: https://nubjs.com/docs/runtime/web-storage

Example CLI usage for persisting localStorage data to a file named app.db.

```bash
$ nub --localstorage-file=./app.db write.ts
abc123
$ nub --localstorage-file=./app.db read.ts
abc123
```

--------------------------------

### Install NubJS via npm

Source: https://nubjs.com/docs

Install the NubJS package globally using npm.

```bash
npm install -g @nubjs/nub
```

--------------------------------

### Varlock installation error

Source: https://nubjs.com/docs/runtime/varlock

Error message displayed when a .env.schema file is detected but Varlock is not installed in the project or PATH.

```bash
$ nub index.ts
Error: .env.schema needs varlock, which isn't installed.
Run `nub add -D varlock`.
```

--------------------------------

### Configuring setup-nub with actions/setup-node

Source: https://nubjs.com/docs/deployment/github-action

Use this configuration to run nubjs/setup-nub after actions/setup-node. Setting provision-node to false ensures the Node.js version provided by setup-node is preserved.

```yaml
  - uses: actions/setup-node@v4
    with:
      node-version: 22
      cache: npm
- uses: nubjs/setup-nub@v0
  with:
    provision-node: false
- run: npm ci
- run: nub install --frozen-lockfile
  - run: npm test
```

--------------------------------

### Install NubJS via Homebrew

Source: https://nubjs.com/docs

Install the NubJS binary using the Homebrew package manager on macOS or Linux.

```bash
brew install nub
```

--------------------------------

### Example package-lock.json structure

Source: https://nubjs.com/docs/install/npm

A sample package-lock.json file demonstrating the structure Nub reads and maintains.

```json
{
  "name": "app",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "app",
      "version": "1.0.0",
      "dependencies": { "is-odd": "3.0.1" }
    },
    "node_modules/is-odd": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/is-odd/-/is-odd-3.0.1.tgz",
      "integrity": "sha512-CQpnWPrD…CBaXgWMA==",
      "license": "MIT",
      "dependencies": { "is-number": "^6.0.0" },
      "engines": { "node": ">=4" }
    }
  }
}
```

--------------------------------

### Provisioning output for pinned Nub install

Source: https://nubjs.com/docs/pm

Shows the terminal output when running nub install with a pinned Nub version. Nub provisions the pinned release (darwin-arm64) and then runs the install. The release is checksum-verified; corrupt or wrong-version builds are hard errors.

```bash
$ nub install
nub: provisioning pinned nub@0.2.9 (darwin-arm64)...
nub: provisioned nub@0.2.9
```

--------------------------------

### Install shims with nub pm shim

Source: https://nubjs.com/docs/pm/pm-shim

Run `nub pm shim` to create shims for pnpm, npm, and yarn in the shim directory and add it to PATH. The output shows 6 entries created and the PATH addition. After installation, `which pnpm` points to the shim, and `pnpm --version` provisions the pinned pnpm on a cold cache, printing the version and 'via nub shim' on stderr.

```bash
$ nub pm shim
nub pm shim: 6 entries in ~/.nub/shims (6 created)
  PATH: added ~/.nub/shims to PATH (~/.zshrc) — restart your shell

$ which pnpm
~/.nub/shims/pnpm

$ pnpm --version
pnpm@9.5.0 (via nub shim)
Installing... (4 MB)
Installed in 0.8s
9.5.0
```

--------------------------------

### Build and push for Apple Silicon

Source: https://nubjs.com/docs/deployment/google-cloud-run

Commands to build a linux/amd64 image on Apple Silicon and deploy it to Cloud Run.

```bash
docker build --platform linux/amd64 -t IMAGE_URL .
docker push IMAGE_URL
gcloud run deploy nub-app --image IMAGE_URL --region us-west1
```

--------------------------------

### Install and remove global packages

Source: https://nubjs.com/docs/install

Use the -g flag to install a package globally, making its executables available in your shell.

```bash
nub add -g cowsay          # or: nub install -g cowsay
cowsay hello

nub remove -g cowsay
```

--------------------------------

### Add Nub to a node:26-alpine image

Source: https://nubjs.com/docs/deployment/docker

Installs Nub on Alpine, adding libgcc and libstdc++ for the native addon before installing the package.

```dockerfile
FROM node:26-alpine
RUN apk add --no-cache libgcc libstdc++ && npm install -g @nubjs/nub
```

--------------------------------

### Render CLI deployment commands

Source: https://nubjs.com/docs/deployment/render

Commands to authenticate, create a web service, and verify the deployment via the Render CLI.

```bash
render login
render workspace set WORKSPACE_ID
render services create \
  --name nub-app \
  --type web_service \
  --repo https://github.com/OWNER/REPOSITORY \
  --branch main \
  --runtime docker \
  --plan free \
  --region oregon \
  --health-check-path /alive \
  --confirm \
  --output json

SERVICE_URL=$(render services --output json \
  | jq -r '.[] | select(.service.name == "nub-app")
                 | .service.serviceDetails.url')
curl --fail "$SERVICE_URL/alive"
# {"alive":true,"runtime":"nub-on-node"}
```

--------------------------------

### Install and run with @nubjs/runner

Source: https://nubjs.com/docs/standalone

Use the npm package to run TypeScript files on plain Node environments where installing a binary is not feasible.

```bash
npm install --save-dev @nubjs/runner
nubr app.ts
```

--------------------------------

### Configure UV_THREADPOOL_SIZE with Nub

Source: https://nubjs.com/docs/runtime/threadpool

Examples showing how Nub sizes the threadpool compared to standard Node.js and how to manually override the size.

```bash
nub server.ts                        # sized to the cores: 16 on 16 vCPUs
node server.ts                       # pool of 4
UV_THREADPOOL_SIZE=6 nub server.ts   # your value, used as is
```

--------------------------------

### Customize installation script with environment variables

Source: https://nubjs.com/docs/faq

Demonstrates how to set NUB_INSTALL_DIR and NUB_NO_MODIFY_PATH when running the curl installation script on macOS or Linux.

```bash
curl -fsSL https://nubjs.com/install.sh \
  | NUB_INSTALL_DIR="$HOME/.local/nub" NUB_NO_MODIFY_PATH=1 bash
```
Tokens:
Raw