RevoEngine Documentation

Custom Node.js components are intended for trusted tenant-authored workloads that need npm packages, multi-file source, or Node.js behavior unavailable in the managed low-code runtime.

Choose Custom Node.js deliberately

Requirement	Recommended surface
Normal platform calls, validation, orchestration, and reusable business rules	JavaScript or TypeScript low-code Component
Shared in-process logic for multiple low-code Components	Library Component
npm dependencies, a multi-file module, or Node.js-specific processing	Custom Node.js Component
Untrusted third-party code	Do not run it as a tenant Component; Custom Node.js is a trusted-code boundary

Custom Node.js does not replace Endpoints or Jobs. A Component defines the code; an Endpoint invokes its active runtime revision synchronously, while a Job provides durable background execution, history, retry controls, and a longer execution budget.

Required files

A component includes index.js, package.json, and any additional relative files. index.js exports a named init function. RevoEngine injects an execution-bound runtime; component code does not construct a client or receive an API key.

index.js                 required entrypoint
package.json             required ESM package manifest
src/normalize-order.js   optional relative module
templates/receipt.txt    optional application asset

Paths are relative POSIX paths. Empty segments, . or .., backslashes, control characters, absolute paths, and duplicate normalized paths are rejected. The platform also validates that package.json is a JSON object and that index.js is valid JavaScript with a named init export before a deployment is queued.

/** @param {import('@revoengine/sdk').RevoRuntime} runtime */
export async function init(runtime) {
  const { api, storage, utils } = runtime;
  const { data: rows } = await api.getDatabaseData('Sales', {
    fields: ['saleId', 'customerId', 'total'],
    take: 100,
  });

  const file = await storage.putObject({
    name: `sales-${utils.randomUUID()}.json`,
    data: JSON.stringify(rows),
    mimeType: 'application/json',
  });

  return { exportedRows: rows.length, storageEntryId: file.storageEntryId };
}

{
  "type": "module",
  "dependencies": {
    "@revoengine/sdk": "1.0.1"
  }
}

The platform selects and enforces its supported SDK release. Use the version generated by RevoEngine rather than replacing it with a range.

Runtime surface

The injected runtime exposes five governed capabilities:

Member	Purpose
`api`	Execution context, Databases, Secrets, HTTP, Jobs, Events, and other platform operations
`storage`	Folders, objects, upload sessions, retention, downloads, and metadata
`utils`	Local validation, identifiers, encoding, hashing, signatures, and cryptography
`agents`	Authorized Assistant, Agent, run, inbox, and plugin operations
`batch`	Request batching limits and failure behavior for bridge-backed calls

Snapshot context calls such as api.input() and api.getExecutionId() are synchronous. Platform-backed reads and writes return promises and must be awaited. Use runtime.execute() when Custom Node.js must run a bounded low-code fragment against the active lib.Category.Name.ElementKey.X library surface.

Runtime types describe callable operations; they do not grant access. The execution principal still needs the applicable role, Group membership, resource ACL, Secret access, and instance entitlement.

Deployment lifecycle

Saving source creates an immutable runtime revision and a deployment attempt. The component reports build and readiness state separately from source versioning. In automatic activation mode, a verified ready revision can become active; manual mode lets an operator choose a ready revision for rollout or rollback. Endpoints execute only the selected ready runtime revision. If no active revision exists, the request fails explicitly rather than using newly saved or failed code. Each attempt moves through customer-visible deployment states:

State	Meaning	Operator action
`QUEUED`	The immutable source revision is waiting for deployment.	Wait or inspect queue health if it remains unchanged.
`DEPLOYING`	The platform is preparing, building, verifying, or promoting the revision.	Follow the stage and deployment timestamps.
`READY`	A verified runtime artifact can be selected for execution.	Smoke-test before broader traffic.
`FAILED`	The attempt did not produce a usable artifact.	Read the sanitized error, correct source or dependencies, and retry or save a new revision.
`SUPERSEDED`	A newer deployment replaced this attempt.	Keep it for history; select only an eligible ready revision.
`CANCELED` or `EXPIRED`	Work ended before readiness.	Confirm no active pointer changed, then retry if still required.

Deployment progress is separate from Component source versioning. A failed new deployment does not make unverified code executable and does not silently replace the previous active revision.

Activation and rollback

In automatic activation mode, a successfully verified desired revision can become active. In manual mode, an operator selects a ready revision explicitly. Activation updates use the current runtime generation so that two administrators cannot unknowingly overwrite each other’s selection. For a rollback:

Open the Component runtime and deployment history.
Confirm the previous revision is still READY.
In manual mode, select that revision using the current generation.
Invoke a representative Sandbox or Endpoint request.
Verify the Execution ID, Logs, Trace, output contract, and downstream state.

Custom Node.js Endpoints always follow the Component’s active runtime revision; they cannot pin an independent low-code componentVersion.

Package boundary

Use ESM and export init.
Keep paths relative and portable; absolute paths and traversal are rejected.
Package installation does not run npm lifecycle scripts.
Use prebuilt or script-free dependencies.
Keep large file transfer in Storage upload sessions instead of buffering it in the worker.

Native dependencies must be compatible with the managed runtime. Prefer small, maintained, script-free packages and commit a reviewed lock file when the editor workflow supports it. Treat every dependency update as an application change: save a new immutable revision, observe deployment, test it, and only then activate it.

Failure and recovery

Failure	Expected behavior
Source or manifest validation fails	The save is rejected and no deployment is queued.
Dependency installation or build fails	The deployment becomes `FAILED`; the previous active revision remains available.
No active ready revision exists	Endpoint or Job execution fails explicitly as not ready.
The execution deadline is reached	The caller receives a timeout; remote effects accepted before cancellation may still exist.
A bridge-backed API call is unauthorized	The operation fails under the runtime principal; changing source cannot bypass the policy.
A client disconnects	Cancellation is requested, but external and durable mutations must be verified before retry.

Do not retry a payment, notification, or provider write only because the caller saw a timeout. Persist an idempotency key, inspect platform evidence and the remote system, then retry through a controlled Job or operator action.

Production checklist

Keep init(runtime) small and move cohesive logic into reviewed relative modules.
Bound Database reads and memory use; stream large payloads through Storage.
Resolve Secrets immediately before the target call and never log their values.
Add idempotency around every retryable external side effect.
Inspect deployment readiness separately from source-save success.
Use manual activation when a release requires an explicit promotion decision.
Test the exact Endpoint or Job principal, not only an editor session.
Capture Execution ID and operation ID in application-safe diagnostics.
Keep the previous ready revision available until the new one passes production verification.

This runtime separates customer code from credential handling, but it is not an adversarial-code sandbox. Review tenant code and dependencies before deployment.

See Hosted Node.js SDK for the complete injected runtime contract, Component configuration for common fields, and Jobs for durable background execution.

​Choose Custom Node.js deliberately

​Required files

​Runtime surface

​Deployment lifecycle

​Activation and rollback

​Package boundary

​Failure and recovery

​Production checklist

Choose Custom Node.js deliberately

Required files

Runtime surface

Deployment lifecycle

Activation and rollback

Package boundary

Failure and recovery

Production checklist