Everything Entirety can do.

A complete reference for installing, using, configuring, and understanding the package.

Install #

Entirety has zero runtime dependencies. Install it like any other package:

$ npm install entirety

Or with your preferred package manager:

$ pnpm add entirety
$ yarn add entirety
$ bun add entirety

You don't need to install lodash, axios, or any other library upfront. Entirety installs them automatically the first time you reach for them — see Auto-install.

Hello, world #

Create an ESM file and run it:

import Entirety from "entirety";

console.log(await Entirety.Lodash.camelCase("hello world"));
// → "helloWorld"

$ node index.js
[entirety] installing lodash via npm…
helloWorld

That's it. The first run is slower because lodash is being installed on your behalf. Every subsequent run is instant.

Requirements #

• Node.js 20 or later. Native ESM dynamic import() is required.
• An ESM project. Either set "type": "module" in your package.json or use the .mjs extension.
• A reachable package.json. Auto-install walks up from your process.cwd() looking for one. If none exists, Entirety still works for already-installed packages but can't install new ones.
• Network on first use of a missing package. Once installed, subsequent runs are offline.

Chained call #

The most common pattern. Property access is lazy; the await at the call site loads the package, walks the path, and invokes the function.

await Entirety.Lodash.camelCase("hello world");  // "helloWorld"
await Entirety.Lodash.range(5);                    // [0, 1, 2, 3, 4]
await Entirety.Axios.get("/api/user");          // { data: …, status: … }

Nothing is loaded, parsed, or instantiated until you await. Unused libraries cost zero.

Await then use #

If you need to call many methods on the same library, resolve it once and re-use it synchronously:

const _ = await Entirety.Lodash;

_.capitalize("entirety");   // "Entirety"
_.range(5);                 // [0, 1, 2, 3, 4]
_.isEqual([1], [1]);          // true

Function references #

If you only need one method, grab it directly:

const camelCase = await Entirety.Lodash.camelCase;

["hello world", "foo bar"].map(camelCase);
// ["helloWorld", "fooBar"]

Same idea works for components and constants:

const useState  = await Entirety.React.useState;
const Button    = await Entirety.MUI.Button;

Calling the module #

Some packages export a function as their main shape (axios, dayjs, ms). Call them directly:

await Entirety.Axios({ url: "/api/user", method: "POST" });
await Entirety.use("ms")("2 days");   // 172800000

Without aliases #

You aren't limited to the four built-in aliases. Reach any npm specifier with Entirety.use():

await Entirety.use("nanoid").nanoid();
await Entirety.use("@scope/some-pkg").helper();
await Entirety.use("node:crypto").randomUUID();

The Entirety() shorthand does the same thing:

await Entirety("zod").z.string();

Custom aliases #

Add aliases at runtime so you can reach a package as Entirety.MyName:

Entirety.register("Day", "dayjs");
Entirety.register({ Zod: "zod", Nano: "nanoid" });

await Entirety.Day().format("YYYY-MM-DD");
await Entirety.Nano.nanoid();

Entirety.extend() is an alias for register().

React & Bundlers #

If you're using React, Next.js, or any frontend bundler (Vite, Rollup, Webpack), dynamic resolution limits their ability to bundle. Entirety ships with a Vite / Rollup plugin that transforms Entirety calls into standard static imports at build time, resulting in perfect tree-shaking for your client builds.

import entiretyPlugin from "entirety/plugin";

export default {
  plugins: [
    entiretyPlugin()
  ]
};

Now, await Entirety.Lodash.camelCase() behaves magically during development but transforms into a strict import { camelCase } from "lodash" at build time.

Browser Support #

Entirety includes a drop-in adapter making it work universally without a Node resolver! Bundlers will resolve entirety/loader to the browser-safe variant using conditional exports, preventing child_process dependencies from creeping into your client code.

Alias Bundles #

Entirety ships with curated maps of popular dependencies to save you time. Import them from entirety/bundles:

import Entirety from "entirety";
import { ReactKit, DataScience } from "entirety/bundles";

Entirety.register(ReactKit);

const motion = await Entirety.Framer.motion;
const useState = await Entirety.React.useState;

TypeScript Autocomplete #

Get editor autocomplete for aliases without needing to install the individual packages beforehand by generating declarations!

$ npx entirety generate-dts

This generates an entirety-env.d.ts in your project root, unlocking full TypeScript support on your custom mappings!

How auto-install works #

When you reference a package that isn't in node_modules, Entirety:

1. Catches the ERR_MODULE_NOT_FOUND from import().
2. Walks up from process.cwd() looking for the nearest package.json.
3. Detects which package manager invoked Node by reading npm_config_user_agent; falls back to lockfile sniffing (bun.lockb, pnpm-lock.yaml, yarn.lock); else npm.
4. Spawns the appropriate install command (npm install <pkg>, pnpm add, yarn add, bun add).
5. Once it exits successfully, retries the original import().

The whole installer runs once per package per session, deduplicated through Entirety's Promise cache.

Configuration #

Most projects need no configuration. Override behaviour with Entirety.configure():

Entirety.configure({
  autoInstall: true,        // default true
  packageManager: "pnpm",    // force pnpm regardless of detection
  installCwd: "/srv/app",    // install into a different directory
  silent: false,            // hide installer output
});

Read the current effective settings:

console.log(Entirety.config);
// { autoInstall: true, packageManager: null, installCwd: null, silent: false }

Environment variables #

Useful for CI, Docker, and one-off invocations without code changes.

Disabling #

For CI pipelines, locked-down builds, or read-only filesystems, disable auto-install:

$ ENTIRETY_NO_INSTALL=1 node app.js

Missing packages now produce an actionable error instead:

Error: Entirety: package 'lodash' is not installed.
  Install it with:  npm install lodash
  Or enable auto-install (remove ENTIRETY_NO_INSTALL from the env).

Entirety.<Alias> #

Returns a chainable, awaitable, callable handle bound to the package mapped to Alias. Built-in aliases:

Add more with Entirety.register().

Entirety.use(name) #

Reach a package by raw npm specifier (or alias name). If name matches a registered alias the alias is used; otherwise the string is passed straight to import().

Entirety.use("lodash");             // alias-resolved
Entirety.use("nanoid");             // not aliased — used as-is
Entirety.use("@radix-ui/react-dropdown-menu");
Entirety.use("node:crypto");       // works for built-ins too

Entirety(name) #

Identical to Entirety.use(name), available for terser sites:

await Entirety("zod").z.string().parse(x);

Entirety.register() #

Adds (or overwrites) aliases in the runtime alias map. Two call shapes — single pair, or a record.

Entirety.register("Day", "dayjs");

Entirety.register({
  Zod:    "zod",
  Crypto: "node:crypto",
});

Entirety.extend() is the same function under a different name.

Entirety.aliases #

Returns a snapshot of the current alias map. Mutations to the returned object don't affect Entirety — use register() for that.

> Entirety.aliases
{ Lodash: 'lodash', Axios: 'axios', React: 'react', MUI: '@mui/material' }

Entirety.configure() #

Merges the partial options object into the live config. Returns the new effective config.

Entirety.config #

Read-only snapshot of the current effective config. Useful for diagnostics.

Entirety.clearCache() #

Drops every cached import() Promise. Mostly useful in tests where you need to re-trigger module loading.

Limitations #

• Async everywhere. ESM import() is asynchronous, so top-level access must be awaited. Sync use is possible after one initial await.
• Side-effect ordering. Packages whose import side-effects you rely on will execute at first access, not at import "entirety". Usually what you want, occasionally not.
• First-use install latency. The first access to a missing package blocks on npm install (seconds). Cached thereafter. Pre-install the common ones if this matters, or ship with a warm node_modules.
• Network required for first use. Offline CI that touches a missing package will fail; pin deps ahead of time or use ENTIRETY_NO_INSTALL=1.

Troubleshooting #

"Entirety package alias 'X' is not configured"

You used a property name that isn't in the alias map. Either register it, or use Entirety.use("real-pkg-name"):

Entirety.register("X", "actual-package-name");
// or
await Entirety.use("actual-package-name").method();

"<path> is not a function (property not found)"

The chained property doesn't exist on the module. Two common causes:

1. Typo in the method name. Try Object.keys(await Entirety.X).
2. The method is an instance method, not a module export — e.g. dayjs().format(). Resolve the module first, instantiate, then call.

Auto-install fails with "no package.json found"

You're running Node from a directory without a package.json in the parent tree. Create one:

$ npm init -y

Or override the install location:

$ ENTIRETY_CWD=/path/to/project node app.js

Auto-install fails with "<pm> exited with code N"

The detected package manager isn't on PATH, or it failed for project-specific reasons (lockfile conflicts, registry unreachable, permission errors). Try the install manually to surface the real error:

$ npm install <package-name>

Or force a different package manager: ENTIRETY_PM=npm node app.js.

Workspaces / monorepos

Auto-install runs <pm> install <pkg> in the directory containing the nearest package.json. In a workspace package, that's the package directory — exactly right. From a workspace root, that's the root. If you need a different target, set ENTIRETY_CWD.

Read-only filesystems / containers

Set ENTIRETY_NO_INSTALL=1 and pre-install all packages at image build time.

FAQ #

Will this work in the browser?

Not in v0.3. The auto-install path is Node-specific (it spawns npm). A CDN loader plugin (esm.sh / jspm) is planned for v2.

What about TypeScript?

The default export is typed as any for now — runtime dispatch is intrinsically untyped. v2 ships generated .d.ts from the alias map and each package's declarations.

Does Entirety bundle every npm package?

No. Entirety itself ships ~10 KB of source and zero dependencies. The libraries you reach for are installed on demand into your own node_modules.

What happens if I use this in production?

It's perfectly fine for server-side Node where node_modules is part of the deployable artifact. Pre-install everything at build time (or use ENTIRETY_NO_INSTALL=1) so production never spawns installs at runtime.

Can I use Entirety alongside regular imports?

Yes. They're independent. Use Entirety for prototyping speed and explicit imports where you want bundler tree-shaking and TS types.