Packages and bundling

Node action modules can use npm packages through a staged package pipeline. Package support is explicit so the runtime stays deterministic. Codegen resolves and stages dependencies. The runtime never fetches or installs them during invocation.

The package reference is the support matrix for packages. It separates positive in-process support from packages that require service or microVM routing.

Externalize packages

Use node.externalPackages in convex.json to make codegen treat package imports as external Node packages:

{
  "node": {
    "nodeVersion": "24",
    "externalPackages": ["@aws-sdk/client-s3", "sharp"]
  }
}

Convex-style wildcard externalization is also supported for packages imported by "use node" action modules. "*" must appear by itself:

{
  "node": {
    "externalPackages": ["*"]
  }
}

Packages must resolve locally

Externalized packages must resolve from your local node_modules during codegen. Nimbus stages the resolved package roots under .nimbus/convex/node_modules/ and records package metadata in .nimbus/convex/node_external_packages.json.

Runtime invocation does not:

• run npm install
• fetch packages from the network
• discover packages outside the generated bundle metadata
• silently bundle unresolved package imports

If a module externalizes a package that is not resolvable from local node_modules, codegen fails with a diagnostic naming the importing module and the missing package.

Current limits

Nimbus records Convex cloud-style package size references in the package metadata. The references are 45 MiB zipped and 240 MiB unzipped. Nimbus does not yet enforce those thresholds as deployment limits. Unsupported or unresolved package imports fail with precise diagnostics instead of ambiguous runtime errors.

Native addons, package-owned binaries, child-process tooling, raw server listeners, and persistent host filesystem assumptions are not in-process support claims. They require a service or microVM route unless the package reference says otherwise for a specific package.

What canary tests verify

Canary tests exercise real packages against the supported Node versions. They cover application networking packages, common HTTP and SaaS SDKs, and real Convex-compatible "use node" actions. They also cover host-heavy diagnostic boundaries. See the package reference for the current matrix and the compatibility contract for what the support statuses mean.