Runtime

Enonic XP runs on top of the Java Virtual Machine. Your app’s TypeScript and JavaScript files are executed by an embedded JavaScript engine, with full access to the JVM through the Java bridge. There is no Node.js, no separate JS process, and no inter-process bridge — server-side JS runs inside the same JVM as the platform itself.

Two engines are available:

An app declares its engine in build.gradle; see Choosing an engine.

Each .ts or .js file in your app is a module under the CommonJS module specification. Modules export values via exports, and consume other modules via require() — import and export statements are not supported at runtime, on either engine, see ECMAScript modules. Paths are rooted at the app bundle, not the filesystem — require('/lib/greet') loads src/main/resources/lib/greet.ts from the same app.

Platform libraries are referenced by name (for example, require('/lib/xp/content')). See Functions: Modules and the bundle for the full path-resolution rules and bundle boundaries.

TypeScript is supported as the authoring language; the build step transpiles to JavaScript before deployment. See TypeScript Definitions.

XP loads each module once per app deploy and caches it. Subsequent require() calls and subsequent triggers reuse the cached module — the file is not re-read or re-parsed. Top-level code in a module therefore runs exactly once per deploy.

This makes module top-level a natural place for one-time setup (requiring libraries, computing constants), but a poor place for mutable state. Treat anything declared outside a function body as immutable after load. For state that must survive between invocations, use a repo node, the cache library, or another explicit persistence mechanism.

See Functions: Loading and caching for the implications on each function type.

The runtime is multithreaded. The platform serves requests, dispatches events, and runs background tasks concurrently across multiple threads, taking advantage of multi-core CPU architectures. There is no single event loop — each request, task, or event listener runs on a worker thread from a managed pool.

Two consequences for your code:

XP can run as a single node or as a cluster of nodes sharing the same data. The runtime is cluster-aware out of the box:

Apps deployed to a cluster are installed and started on every node. The runtime guarantees the same module-loading and caching semantics on each node — your app sees a consistent execution environment regardless of which node serves a given request.

Apps run inside a fully equipped platform. The runtime gives you, without extra setup:

This section documents the parts of an app that are not tied to a specific HTTP service or background mechanism. The sections above describe how your code executes; the pages below cover the building blocks in detail.

Setting up TypeScript for the build is covered under Tooling, and the shared types every library uses under Types.

The runtime is the foundation: a JVM-based execution environment with a CommonJS module system, multithreading, clustering, and a platform’s worth of services attached. Functions are the units of code the runtime invokes — most of what you write is regular module code, with a smaller subset bound to framework contracts. main.ts is the lifecycle contract. Events are the cluster-wide pub/sub primitive, available from any function. Globals, TypeScript, the Java bridge, and localization are tools you reach for inside any function, regardless of which contract called it.

For HTTP-bound contracts (request handlers, filters, error handlers, websockets, SSE, ID providers), see Web. For asynchronous background execution (tasks, scheduled jobs), see Background.