# Nub

> Nub is a Rust CLI that augments your installed Node: a fast script runner and a TypeScript-just-works runtime. This file indexes the documentation as Markdown for LLMs.

## Docs

- [Introduction](https://nubjs.com/llms/docs.mdx): Nub is an all-in-one Rust toolkit for Node.js. Run TypeScript files and scripts, install dependencies, and manage Node itself — all on stock Node, with no lock-in.
- [Runtime](https://nubjs.com/llms/docs/runtime.mdx): What Nub adds when it runs your code on stock Node — TypeScript and JSX with no build step, editor-style resolution, automatic .env loading, data-file imports, and modern globals — plus the plain-Node escape hatch that turns it all off.
- [TypeScript](https://nubjs.com/llms/docs/runtime/typescript.mdx): How Nub runs the full TypeScript surface on stock Node — non-erasable syntax, resource-management downleveling, and source maps — none of which plain Node does.
- [JSX](https://nubjs.com/llms/docs/runtime/jsx.mdx): How Nub runs JSX on stock Node — automatic-runtime defaults, tsconfig-driven configuration, and the per-file import-source pragma for mixing runtimes.
- [Decorators](https://nubjs.com/llms/docs/runtime/decorators.mdx): How Nub runs legacy TypeScript decorators and their emitted design-type metadata on stock Node — the form the NestJS, TypeORM, and Angular dependency-injection ecosystem is written against.
- [Module resolution](https://nubjs.com/llms/docs/runtime/resolution.mdx): The TypeScript-aware resolution Nub layers on top of Node — tsconfig path aliases and base URL, extends chains, extensionless imports, and the JavaScript-to-TypeScript extension swap.
- [Environment files](https://nubjs.com/llms/docs/runtime/env.mdx): Automatic environment-file loading — the file set, precedence, variable expansion, the skip under the test environment, and how an explicit env-file flag disables auto-discovery.
- [Loaders](https://nubjs.com/llms/docs/runtime/loaders.mdx): Import JSON, JSONC, JSON5, TOML, YAML, and plain-text files directly as default exports, via an extension-keyed load hook.
- [Web Workers](https://nubjs.com/llms/docs/runtime/workers.mdx): A browser-style Worker global on stock Node — its constructor, messaging, transferables, and event surface.
- [Web Storage](https://nubjs.com/llms/docs/runtime/web-storage.mdx): Session storage works out of the box; persistent local storage turns on once you point it at a backing file.
- [Watch mode](https://nubjs.com/llms/docs/watch.mdx): Restart-on-change for files and scripts, driven by the resolved dependency graph plus your environment files, tsconfig, and package manifest — no glob hygiene required.
- [Runner](https://nubjs.com/llms/docs/runner.mdx): One command to run whatever a name points to — a file, a script, a local CLI, or a package off the registry. Local resolution first, and a registry fetch only with your consent, never silently in CI.
- [Script runner](https://nubjs.com/llms/docs/runner/run.mdx): A drop-in for pnpm run and npm run — every flag carries over with the same spelling and semantics, 24× faster on the cold path, with the full workspace and lifecycle-hook surface preserved.
- [Local bin runner](https://nubjs.com/llms/docs/runner/exec.mdx): Run a CLI installed in the project by name, straight from node_modules — an order of magnitude faster than npx, and never reaching the registry.
- [Remote bin runner](https://nubjs.com/llms/docs/runner/dlx.mdx): Fetch a package from the registry and run its bin, explicitly — the deliberate download gesture, with consent by invocation.
- [Package manager](https://nubjs.com/llms/docs/install.mdx): Nub ships its own installer with a pnpm-shaped CLI and lockfile-compatibility with whatever your project already uses — npm, pnpm, and Bun round-trip, Yarn read-only.
- [pnpm](https://nubjs.com/llms/docs/install/pnpm.mdx): Nub mirrors pnpm most closely — native version-9 lockfile read and write, the full dependency-verb surface, workspace selectors, an isolated dependency tree, and pnpm-owned config, all gated on pnpm being the incumbent.
- [npm](https://nubjs.com/llms/docs/install/npm.mdx): Nub speaks npm's on-disk formats — the version-2 and version-3 lockfile round-trips byte-for-byte, npm workspaces and overrides are honored, and npm config is read across the builtin, global, user, and project scopes. The CLI is pnpm-shaped; the files are npm's.
- [Bun](https://nubjs.com/llms/docs/install/bun.mdx): When Bun is the incumbent, Nub installs against it — Bun's text lockfile round-trips byte-for-byte, its trusted-dependencies list gates build scripts, and overrides, resolutions, patches, and catalogs all resolve Bun's way.
- [Yarn](https://nubjs.com/llms/docs/install/yarn.mdx): Yarn is supported read-only — Nub reads the Yarn lockfile (Classic v1 and Berry v2+) to install and run a project, but never writes it. Treat a Yarn project as something Nub consumes, not maintains.
- [Node manager](https://nubjs.com/llms/docs/node.mdx): Manage the Node versions Nub provisions — pin a version and it's fetched automatically, or drive the cache explicitly with the install, list, uninstall, and pin subcommands.
- [Package meta-manager](https://nubjs.com/llms/docs/pm.mdx): Provision and run the package manager your project pins — corepack's job, in native Rust. The exact pnpm, npm, or yarn release is fetched, verified, cached, and run on the project's Node.
- [Package-manager shims](https://nubjs.com/llms/docs/pm-shim.mdx): An opt-in for muscle memory. Install the shims and a bare pnpm, npm, or yarn command routes through Nub to the package manager your project pins, with no extra Node process in front.
- [Plugins](https://nubjs.com/llms/docs/plugins.mdx): Extend the nub CLI with your own subcommands — an unknown verb resolves to an executable named after it and runs, the same convention git and cargo use for their plugins.
- [FAQ](https://nubjs.com/llms/docs/faq.mdx): The short, indexed answers to common questions about Nub — what it is, how it works, and what it deliberately is not.
- [GitHub Action](https://nubjs.com/llms/docs/setup-nub.mdx): A drop-in replacement for the official setup-node action. Swap one line in your workflow and Nub installs itself, provisions the project's pinned Node, and fronts it on PATH so every step keeps working unchanged.
- [Docker](https://nubjs.com/llms/docs/docker.mdx): Official Nub Docker images, and how to add Nub to your own image. The images install Nub onto an official Node base, so Node is present and the runtime is augmented out of the box.

## Guides

- [Migrating from Bun to Nub](https://nubjs.com/llms/guides/bun-to-nub.mdx): A practical, code-first guide to moving a Bun project onto Node + Nub — runtime, scripts, env files, a complete map of every Bun-specific API to its Node or npm-ecosystem replacement, Dependabot, and the gotchas that actually bite.
- [Guides](https://nubjs.com/llms/guides.mdx): Practical, code-first walkthroughs for common Nub setups and migrations.
- [Using Nub with Turborepo](https://nubjs.com/llms/guides/turborepo.mdx): How Nub and Turborepo coexist in a monorepo today — Turborepo owns the task graph and cache, Nub is the runtime and package manager underneath. You keep your existing packageManager field and lockfile, run Turborepo under Nub, and TypeScript and .env files just work inside every task.

## Blog

- [Introducing Nub: an all-in-one toolkit for Node.js](https://nubjs.com/llms/blog/introducing-nub.mdx): A Rust CLI that augments stock Node — TypeScript that just runs, a faster script runner, and a fast bin runner. It augments Node.js instead of trying to replace it.