Your Cloud Run function runs in an environment consisting of anoperating system version with add-on packages, language support, and theNode.js Functions Frameworklibrary that supports and invokes your function. This environment isidentified by the language version, and is known as the runtime ID.

Function preparation

You can prepare a function directly from the Google Cloud console or write it onyour local machine and upload it. To prepare your local machine for Node.jsdevelopment, seeSet up a Node.js development environment.

Supported Node.js runtimes and base images

Select your runtime

You can select one of the supported Node.js runtimes for your function duringdeployment.

You can select a runtime version using the Google Cloud console, or thegcloud CLI. Click the tab for instructions on using the tool ofyour choice:

gcloud run deployFUNCTION \    --source . \    --functionFUNCTION_ENTRYPOINT \    --base-image nodejs22

Source code structure

For Cloud Run functions to find your function's definition, yoursource code must follow a specific structure. SeeWrite Cloud Run functions formore information.

Specify dependencies

You can specify dependencies for your functions by listing them in apackage.json file. For more information, seeSpecify dependencies in Node.js.

NPM build script

By default, the Node.js runtime executesnpm run build if abuild scriptis detected inpackage.json. If you require additional control over your buildsteps before starting your application, you can provide acustom build stepby adding agcp-build script to yourpackage.json file.

You can prevent your build from running thenpm run build script by either:

• Adding agcp-build script with an empty value in yourpackage.json file:"gcp-build":"".

• Setting the build environment variableGOOGLE_NODE_RUN_SCRIPTS to the empty string to prevent all scripts from running.

Asynchronous function completion

When working with asynchronous tasks that involve callbacks orPromiseobjects, you must explicitly inform the runtime that your function has finishedexecuting these tasks. You can do this in several different ways, as shown inthe following samples. The key is that your code must wait for theasynchronous task orPromise to complete before returning; otherwise theasynchronous component of your function may be terminated before it completes.

Event-driven functions

Implicit return

exports.implicitlyReturning=async(event,context)=>{returnawaitasyncFunctionThatReturnsAPromise();};

Explicit return

exports.explicitlyReturning=function(event,context){returnasyncFunctionThatReturnsAPromise();};

HTTP functions

// OK: await-ing a Promise before sending an HTTP responseawaitPromise.resolve();// WRONG: HTTP functions should send an// HTTP response instead of returning.returnPromise.resolve();// HTTP functions should signal termination by returning an HTTP response.// This should not be done until all background tasks are complete.res.send(200);res.end();// WRONG: this may not execute since an// HTTP response has already been sent.returnPromise.resolve();

Node.js HTTP functions providerequest andresponseobjects that are compatible withExpressJSto make consuming HTTP requests simpler. Cloud Run functionsautomatically reads the request body, so you will always receive the body of arequest independent of the media type. This means that HTTP requests should beconsidered to have been fully read by the time your code is executed. Thenesting of ExpressJS apps should be used with this caveat—specifically,middleware that expects the body of a request to be unread might not behave asexpected.

Use ES Modules

ECMAScript modules (ES modules or ESM) are a TC39 standard, unflagged featurein Node version 14+ for loading JavaScript modules. Unlike CommonJS, ESMprovides an asynchronous API for loading modules. It also provides a popularsyntax improvement withimport andexport statements that can be used withina Cloud Run function (instead ofrequire statements).

To use ESM within a Cloud Run function, you mustdeclare"type": "module" within yourpackage.json.

{..."type":"module",...}

Then you can useimport andexport statements.

Learn more about usingES modules.