Node.js Runtime Images

Node.js runtime images represent a major evolution in how you run custom code within Basis Theory. Built with developer experience and security in mind, they give you full control over dependencies, compute resources, and runtime configuration.

Supported Images

Runtime image	Node.js version
`node22`	22
`node24`	24

All listed images support the same runtime options, provisioning states, code contracts, and security controls documented on this page. The examples use node24; select another supported image by changing only runtime.image.

Why Use a Node.js Runtime Image?

Manage your own dependencies: Install any npm package directly in your reactor. No more requesting packages or working around version limitations.
Modern Node.js runtimes: Choose an actively supported Node.js version with modern JavaScript features and active security updates.
Configurable resources: Configure timeout and resources to match your workload requirements.
Warm concurrency: Keep your functions warm and customize how many instances stay ready to handle requests.
Simplified code contract: A streamlined request/response pattern with enhanced logging support and full HTTP response control.
Fine-grained permissions: Specify exactly which Basis Theory permissions your code needs without requiring a separate Application.

Getting Started

To create a Reactor or Proxy code transform, set runtime.image to a supported image. For API details, see:

For Proxy code contracts, see the request transform contract and response transform contract.

Reactors using a Node.js runtime image can run synchronously or asynchronously. Proxy transforms always run synchronously.

Runtime Options

Use the runtime object to configure dependencies, resolutions, timeout, resources, warm concurrency, and permissions. Reactors can also be configured for asynchronous execution.

Runtime Image

Set runtime.image to one of the supported images to select the Node.js version that runs your code.

Dependencies

Specify npm packages to install in your runtime environment via runtime.dependencies. Packages are installed at build time when the resource is created or updated.

{
  "runtime": {
    "image": "node24",
    "dependencies": {
      "stripe": "22.4.0",
      "lodash": "4.18.1",
      "axios": "1.19.0"
    }
  }
}

Pinned versions are required. Do not use version ranges like "^22.4.0" or "~22.4.0". Specify exact versions (e.g., "22.4.0").

Vulnerability Scanning

Dependencies for Node.js runtime images are scanned during deployment, and deployed runtime artifacts are scanned continuously after deployment.

If HIGH or CRITICAL vulnerabilities are detected during deployment, provisioning fails until dependencies are remediated.

See Runtime Vulnerability Scanning for scan behavior, failure details, notification cadence, and webhook events.

It is still recommended to run dependency scans in your own CI process (for example npm audit and Trivy) before deploying.

Resolutions

Use runtime.resolutions to override versions of dependencies installed indirectly through other packages. Overrides are applied at build time when the resource is created or updated.

{
  "runtime": {
    "image": "node24",
    "dependencies": {
      "maskdata": "1.3.4"
    },
    "resolutions": {
      "lodash": "4.18.1"
    }
  }
}

Pinned versions are required. Do not use version ranges like "^4.18.1" or "~4.18.1". Specify exact versions (e.g., "4.18.1").

Use runtime.resolutions when a dependency in runtime.dependencies installs a transitive dependency version you need to replace, such as for a security patch or compatibility fix.

Timeout

Maximum execution time for your code in seconds. The supported range depends on how the runtime is used.

Execution mode	Supported range	Default
Synchronous Reactor or Proxy transform	10 to 30 seconds	10 seconds
Asynchronous Reactor	10 to 900 seconds	10 seconds

Resources

Control the compute resources allocated to your runtime.

Value	Memory (MB)	When to use
`standard`	`256`	Most workloads, typical operations, standard processing needs
`large`	`1024`	Operations that need more resources than standard, heavier workloads
`xlarge`	`2048`	Operations requiring maximum resources, mainly for resource-intensive workloads

CPU capacity scales proportionally with memory. Larger resource sizes receive proportionally more CPU capacity.

Warm Concurrency

runtime.warm_concurrency controls how many pre-initialized instances of your reactor are kept ready to handle requests immediately, without initialization delay. It defaults to 0 for all tenants.

Warm instances are already initialized and can start handling requests right away. This helps reduce latency for workloads that are sensitive to startup time.

Tenant Type	Default quota	Description
Test	`0`	Warm concurrency is unavailable unless increased.
Production	`1`	Up to one warm instance unless the quota is increased.

For many workloads, keeping at least one warm instance can improve tail latency by reducing cold starts during normal traffic.

To request higher warm concurrency limits, visit Settings > Quotas in the Portal.

Cold Starts

A cold start happens when a request arrives and no warm instance is available to handle it. In that case, Basis Theory initializes a new instance before running your reactor.

If a warm instance is available, the request executes immediately. If all warm instances are busy (or none are configured), the request waits for a new instance to initialize.

What to expect:

Cold start duration depends on your reactor's dependencies and code size. More or larger dependencies generally increase initialization time.
For latency-sensitive workloads, set warm_concurrency to at least 1 to reduce cold starts.
The first invocation after a reactor is provisioned or updated may experience a cold start.

Permissions

Grant Basis Theory Application permissions to your runtime via runtime.permissions. These permissions determine what operations the code can perform when it executes.

{
  "runtime": {
    "image": "node24",
    "permissions": ["token:create"]
  }
}

Common permissions include token:create for creating new tokens. See the full permissions reference for all available options.

States

Resources using a Node.js runtime image use a state machine to track provisioning and runtime status. Understanding these states helps you build integrations that handle asynchronous operations correctly.

State	Description
`creating`	Initial provisioning in progress
`active`	Ready to invoke
`updating`	Modification in progress
`failed`	Provisioning or update failed
`outdated`	Update failed, but previous version is still functional

State Diagram

State Transitions

Transition	Trigger
creating → active	Successful provisioning
creating → failed	Provisioning error (e.g., invalid dependencies, syntax error in code)
active → updating	Update initiated via PUT or PATCH
updating → active	Successful update
updating → outdated	Update failed (previous version remains active and can still be invoked)
outdated → updating	New update initiated via PUT or PATCH

Operation Behavior

The following table shows which operations are allowed based on the current state of a Reactor or Proxy using a Node.js runtime image:

State	Invoke	Update	Delete
`creating`	❌	❌	❌
`active`	✅	✅	✅
`updating`	✅^*	❌	❌
`failed`	❌	✅	✅
`outdated`	✅	✅	✅

^* During an update, invocation uses the previous active configuration when one exists. A resource that has never completed provisioning remains unavailable. In outdated state, invocation executes the previous working version.

Asynchronous Reactors

See Asynchronous Reactors for the shared submit-and-retrieve workflow.

Set runtime.async to true to configure a Reactor using a Node.js runtime image for asynchronous execution. This option applies only to Reactors and is not supported for Proxy transforms.

{
  "runtime": {
    "image": "node24",
    "async": true,
    "timeout": 900
  }
}

Invoke an asynchronous Reactor through the asynchronous Reactor endpoint, then poll for its result.

Partial Results

During an asynchronous invocation using a Node.js runtime image, the Reactor handler receives asyncRecords. Call asyncRecords.write(recordId, value) to preserve intermediate results before the Reactor finishes:

module.exports = async function (event) {
  const { req, asyncRecords } = event;

  await asyncRecords.write("customer-myCustomerId1234", {
    customer_id: req.customer_id,
    status: "processed"
  });

  return {
    res: {
      body: { processed: true },
      statusCode: 200
    }
  };
};

Await each write so your Reactor can handle a failed record upload. Each invocation supports:

Up to 25 records.
Serialized values up to 256 KiB per record.
Record IDs from 1 to 64 characters using letters, numbers, underscores, and hyphens. The first character must be a letter or number.

Record IDs must be unique within an invocation, and record values must be JSON-serializable. Use each record's id instead of depending on array order.

If the Reactor fails or times out after writing records, successfully written records remain available in the final result.

Migrating from node-bt

For the code, dependency, permission, testing, and rollout changes required to move an existing resource, see Migrate from node-bt.

Supported Images​

Why Use a Node.js Runtime Image?​

Getting Started​

Runtime Options​

Runtime Image​

Dependencies​

Vulnerability Scanning​

Resolutions​

Timeout​

Resources​

Warm Concurrency​

Cold Starts​

Permissions​

States​

State Diagram​

State Transitions​

Operation Behavior​

Asynchronous Reactors​

Partial Results​

Migrating from node-bt​