diff --git a/doc/api/cli.md b/doc/api/cli.md index 27a539e6de8819..af1ca0bfe64887 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -100,6 +100,62 @@ If this flag is passed, the behavior can still be set to not abort through [`process.setUncaughtExceptionCaptureCallback()`][] (and through usage of the `node:domain` module that uses it). +### `--build-snapshot` + + + +> Stability: 1 - Experimental + +Generates a snapshot blob when the process exits and writes it to +disk, which can be loaded later with `--snapshot-blob`. + +When building the snapshot, if `--snapshot-blob` is not specified, +the generated blob will be written, by default, to `snapshot.blob` +in the current working directory. Otherwise it will be written to +the path specified by `--snapshot-blob`. + +```console +$ echo "globalThis.foo = 'I am from the snapshot'" > snapshot.js + +# Run snapshot.js to intialize the application and snapshot the +# state of it into snapshot.blob. +$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js + +$ echo "console.log(globalThis.foo)" > index.js + +# Load the generated snapshot and start the application from index.js. +$ node --snapshot-blob snapshot.blob index.js +I am from the snapshot +``` + +The [`v8.startupSnapshot` API][] can be used to specify an entry point at +snapshot building time, thus avoiding the need of an additional entry +script at deserialization time: + +```console +$ echo "require('v8').startupSnapshot.setDeserializeMainFunction(() => console.log('I am from the snapshot'))" > snapshot.js +$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js +$ node --snapshot-blob snapshot.blob +I am from the snapshot +``` + +For more information, check out the [`v8.startupSnapshot` API][] documentation. + +Currently the support for run-time snapshot is experimental in that: + +1. User-land modules are not yet supported in the snapshot, so only + one single file can be snapshotted. Users can bundle their applications + into a single script with their bundler of choice before building + a snapshot, however. +2. Only a subset of the built-in modules work in the snapshot, though the + Node.js core test suite checks that a few fairly complex applications + can be snapshotted. Support for more modules are being added. If any + crashes or buggy behaviors occur when building a snapshot, please file + a report in the [Node.js issue tracker][] and link to it in the + [tracking issue for user-land snapshots][]. + ### `--completion-bash` + +> Stability: 1 - Experimental + +When used with `--build-snapshot`, `--snapshot-blob` specifies the path +where the generated snapshot blob will be written to. If not specified, +the generated blob will be written, by default, to `snapshot.blob` +in the current working directory. + +When used without `--build-snapshot`, `--snapshot-blob` specifies the +path to the blob that will be used to restore the application state. + ### `--test`