From 1fbe842d6402d58b1f589e5504cfb7ac9952e9b2 Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Mon, 8 Dec 2025 16:08:11 +0100 Subject: [PATCH] module: mark module compile cache as stable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The feature set has been stable without any breaking changes in the past year, and it's been depended enough in the wild by popular packages that we'll likely need to treat any breakages as semver-major in the future anyway. The future TODOs are likely all non-breaking. Potential subtle breakages in implementation details that should not be relied upon (such as the cache layout) are explicitly excluded from the contract. We'll investigate whether it can be enabled by default as a different topic, which can be potentially semver-major. PR-URL: https://github.com/nodejs/node/pull/60971 Reviewed-By: Vinícius Lourenço Claro Cardoso Reviewed-By: Marco Ippolito --- doc/api/cli.md | 6 ++++-- doc/api/module.md | 28 ++++++++++++++++++++-------- 2 files changed, 24 insertions(+), 10 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index d5b6dc1db2c..4e2a44e868f 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -3403,10 +3403,12 @@ Any other value will result in colorized output being disabled. -> Stability: 1.1 - Active Development - Enable the [module compile cache][] for the Node.js instance. See the documentation of [module compile cache][] for details. diff --git a/doc/api/module.md b/doc/api/module.md index d9a12895244..efb85efc4c9 100644 --- a/doc/api/module.md +++ b/doc/api/module.md @@ -410,6 +410,11 @@ to disk when the Node.js instance is about to exit. This is subject to change. T is flushed to disk in case the application wants to spawn other Node.js instances and let them share the cache long before the parent exits. +The compile cache layout on disk is an implementation detail and should not be +relied upon. The compile cache generated is typically only reusable in the same +version of Node.js, and should be not assumed to be compatible across different +versions of Node.js. + ### Portability of the compile cache By default, caches are invalidated when the absolute paths of the modules being @@ -449,10 +454,12 @@ separately if the same base directory is used to persist the cache, so they can -> Stability: 1.1 - Active Development - The following constants are returned as the `status` field in the object returned by [`module.enableCompileCache()`][] to indicate the result of the attempt to enable the [module compile cache][]. @@ -503,6 +510,9 @@ The following constants are returned as the `status` field in the object returne -> Stability: 1.1 - Active Development - * `options` {string|Object} Optional. If a string is passed, it is considered to be `options.directory`. * `directory` {string} Optional. Directory to store the compile cache. If not specified, the directory specified by the [`NODE_COMPILE_CACHE=dir`][] environment variable @@ -557,10 +565,12 @@ be inherited into the child workers. The directory can be obtained either from t added: - v23.0.0 - v22.10.0 +changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/60971 + description: This feature is no longer experimental. --> -> Stability: 1.1 - Active Development - Flush the [module compile cache][] accumulated from modules already loaded in the current Node.js instance to disk. This returns after all the flushing file system operations come to an end, no matter they succeed or not. If there @@ -571,10 +581,12 @@ interfere with the actual operation of the application. -> Stability: 1.1 - Active Development - * Returns: {string|undefined} Path to the [module compile cache][] directory if it is enabled, or `undefined` otherwise.