Achieve Backend Module Loading and Caching
Created November 6, 2026 · Updated November 6, 2026 · Achieve 3.1.0 · Qualified runtime: Node.js 24.22.2
Achieve provides two backend loading facilities with different resolution contexts. session.load() loads files relative to the current servlet. achieve.loadModule() resolves an installed CommonJS package from the application startup environment.
Servlet-relative session.load()
const helper = session.load("./helper.jss.cjs");
const module = await session.load("./helper.jss.mjs");
Relative names are joined to the current servlet directory. Supported forms are .js, .jss, .jss.cjs, and .jss.mjs; an extensionless name selects the corresponding legacy .js file. CommonJS forms return their exports synchronously. The ESM form uses dynamic import and returns a Promise.
This loader is for backend code, not HTTP routing. Its files execute with the Node.js process's permissions, and loading a module does not make that module public.
Development reload behavior
In development mode, CommonJS helper loading checks the file modification time. When that time advances, Achieve removes the Node require cache entry before loading. Development ESM imports include the observed modification time in the module URL so a changed file can be imported as a new module instance.
The check is metadata-based: it does not hash helper content, and it does not establish a reload when a change preserves or moves the recorded modification time backward. Application modules imported directly without session.load() retain ordinary Node caching behavior.
Production caching
Production mode stores the first successful CommonJS export or ESM-loading Promise by full helper path and returns that reference on later calls without per-request modification checks. Resetting the configured application path clears Achieve's production helper cache. Restarting the process also obtains the current files.
A failed ESM loading Promise is removed from Achieve's production helper cache, although the underlying runtime can retain a failed ESM module record for the same module URL. Tests therefore avoid promising recovery from every production ESM evaluation failure without a changed URL or restarted process.
Application-local achieve.loadModule()
const packageApi = achieve.loadModule("application-package");
achieve.loadModule() uses a CommonJS resolver anchored at the server entry file, allowing a package installed for the application to be found even when Achieve itself is installed elsewhere. It resolves and inspects the package entry on each call, removes the Node require cache entry when the recorded modification time advances, and returns the CommonJS export. It is not the ESM helper loader and does not use the production helper-reference cache described above.
Errors and responsibility
An unsupported session.load() suffix throws a type error. CommonJS and ESM loading or evaluation errors propagate through the servlet and can be caught by application code; otherwise Achieve's managed servlet error handling reports them. Error rendering removes internal Achieve frames and avoids exposing the configured application root in the verified client diagnostics.
achieve.loadModule() catches resolution or loading failure, reports a server-side diagnostic, and returns undefined. The caller must check the result when failure is possible. Package behavior, module side effects, and dependency lifecycle remain application responsibilities.
Verification and limits
Servlet-module and helper-cache suites verify supported CommonJS and ESM names, synchronous and asynchronous results, development changes, production reference reuse, failed loads, recovery cases, unsupported suffixes, and sanitized diagnostics. The dedicated load-module suite verifies application-local package resolution from both CommonJS and ESM startup files and the missing-package result.
See Servlet Session API, JavaScript Servlet Lifecycle, and Development Mode.
