node22

The node22 runtime image represents a major evolution in how you run custom code within Basis Theory. Built with developer experience and security in mind, node22 gives you unprecedented control over your serverless functions.

Why node22?

• Manage your own dependencies: Install any npm package directly in your reactor. No more requesting packages or working around version limitations.

• Modern Node.js runtime: Run on Node.js 22 with the latest JavaScript features, better performance, 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 use this runtime, specify runtime.image: "node22" when creating your resource. For API details, see:

• Reactors API
• Pre-Configured Proxies API

The node22 runtime currently supports synchronous Reactor invocations. Support for asynchronous invocations will be available soon.

Runtime Options

The node22 runtime is enabled by specifying a runtime object with image: "node22". Within the runtime object, you can configure dependencies, timeout, resources, warm concurrency, and permissions.

Runtime Image

The runtime.image property specifies which runtime image to use. See available runtimes for details on each option.

Value	Description
node-bt	Default runtime with curated dependencies
node22	Modern Node.js 22 with custom npm packages and configurable resources

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": "node22",
    "dependencies": {
      "stripe": "18.4.0",
      "lodash": "4.17.21",
      "axios": "1.7.9"
    }
  }
}

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

Evaluating Dependencies

While Basis Theory scans dependencies for vulnerabilities at deployment, proactively evaluating packages before including them can help avoid deployment issues and future alerts. Consider the following criteria:

• Maintainability: Verify the package is actively maintained. Look for recent commits, responses to issues, and regular releases. Avoid packages that appear abandoned.
• Popularity: Consider the package's adoption relative to its purpose. While download counts aren't everything, widely-used packages tend to receive more security scrutiny.
• Security: Check for known vulnerabilities using tools such as npm audit and Trivy. Avoid packages with unresolved HIGH or CRITICAL vulnerabilities.

Timeout

Maximum execution time for your code in seconds. Configurable from 1 to 30 seconds.

Value	Description
Minimum	1 second
Default	10 seconds
Maximum	30 seconds

Resources

Control the compute resources allocated to your runtime.

Value	Description	When to use
standard	Default resource allocation	Most workloads, typical operations, standard processing needs
large	Increased resources	Operations that need more resources than standard, heavier workloads
xlarge	Maximum resource allocation	Operations requiring maximum resources, mainly for resource-intensive workloads

Warm Concurrency

Maintain warm instances to reduce cold start latency.

Tenant Type	Default	Description
Test	0	No warm instances
Production	1	One warm instance maintained

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

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": "node22",
    "permissions": ["token:reveal", "token:create"]
  }
}

Common permissions include token:reveal (detokenize values) and token:create (create new tokens). See the full permissions reference for all available options.

States

The node22 runtime uses a state machine to track provisioning and runtime status. Understanding these states helps you build robust 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 the node22 runtime:

State	Invoke	Update	Delete
creating	❌	❌	❌
active	✅	✅	✅
updating	❌	❌	❌
failed	❌	✅	✅
outdated	✅	✅	✅

Note: In outdated state, Invoke executes the previous working version.

Comparison with node-bt

For a detailed comparison between node22 and node-bt, see the Runtime comparison table.