Node.js Reference ยท Module Systems
Node.js module.enableCompileCache() method
Reference for module.enableCompileCache() in Node.js: cache compiled code on disk to speed up startup, status codes, directory choice, flushing and limits.
module.enableCompileCache() turns on the on-disk module compile cache. The first time Node loads a module it compiles the source and writes the compiled data to a cache directory; the next run reads that data instead of compiling again, which shortens startup for programs that load many or large modules (CLIs, build tools, test runners).
You call it once, early, before the modules you want cached are loaded. It reports what happened through a result object, because failing to enable a cache must never stop your program.
import module from 'node:module'; const result = module.enableCompileCache(); console.log(result.status === module.constants.compileCacheStatus.ENABLED);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
import module from 'node:module'; module.enableCompileCache(cacheDir?: string | { directory?: string, portable?: boolean }): { status: number, message?: string, directory?: string } module.getCompileCacheDir(): string | undefined module.flushCompileCache(): void module.constants.compileCacheStatus: { FAILED, ENABLED, ALREADY_ENABLED, DISABLED }
| Name | Description |
|---|---|
cacheDir |
Folder to store the cache in. If omitted, Node uses NODE_COMPILE_CACHE if set, otherwise a node-compile-cache folder inside the operating system's temp directory. |
portable |
When true, cached entries use relative paths so the cache keeps working if the project folder is moved. Added after the first release of the API, so check your Node version. |
status |
One of the compileCacheStatus values: ENABLED (turned on now), ALREADY_ENABLED (an earlier call won), FAILED (could not set up, see message), DISABLED (blocked by NODE_DISABLE_COMPILE_CACHE=1). |
directory |
The directory in use. On the first successful call it is the folder you passed; once the cache is active, getCompileCacheDir() returns the versioned subfolder where entries are stored. |
Returns: an object with status, plus message on failure and directory on success. It never throws for a cache problem.
Usage notes
- Call it before loading what you want cached. Modules already compiled are not retroactively cached. In a CLI, enable it at the top of the entry file, before the other imports run (use a tiny entry that calls it and then
await import()s the real program). - Only the first call counts. Later calls return
ALREADY_ENABLEDand keep the first directory (the second call in the first example passesother, which is ignored). - Environment variable alternative. Setting
NODE_COMPILE_CACHE=/some/dirwhen starting Node enables it with no code change, and also covers the very first module. This cannot be shown in the live examples. - Written at exit. The cache is saved when the process exits normally.
module.flushCompileCache()saves earlier, which matters for long-running programs and for crashes. - The cache is keyed by content, not trusted blindly. Entries are checked against the source (and Node and V8 versions), so edited files are recompiled. A cache from another Node version is ignored.
- Gains vary. The benefit grows with the amount of JavaScript loaded; tiny scripts see little change. Measure startup with and without it.
- Shared directories. Use a per-project or per-user folder with the right permissions. Anything that can write to the cache directory can influence what your process executes, so do not put it in a world-writable location.
- Related helpers:
module.getCompileCacheDir()returns the active folder orundefined.