Functions Framework for Node.js

To process Google Cloud Functions events, you must use the event-style signature where the function accepts data and context arguments. You must also set the signature type to event via the --signature-type flag or FUNCTION_SIGNATURE_TYPE environment variable to enable automatic unmarshalling.

exports.helloEvents = (data, context) => {
  console.log(data);
  console.log(context);
};

The framework supports the CloudEvents spec. To use it, use the functions.cloudEvent registration method. The function receives a single cloudevent object containing the event metadata (like id, source, type, etc.).

const functions = require('@google-cloud/functions-framework');

functions.cloudEvent('helloCloudEvents', (cloudevent) => {
  console.log(cloudevent.specversion);
  console.log(cloudevent.type);
  console.log(cloudevent.source);
  console.log(cloudevent.subject);
  console.log(cloudevent.id);
  console.log(cloudevent.time);
  console.log(cloudevent.datacontenttype);
});

For a standard project setup, use the @google-cloud/functions-framework programmatic API to register your function and use an npm start script for local development.

// index.js
const functions = require('@google-cloud/functions-framework');

functions.http('helloWorld', (req, res) => {
  res.send('Hello, World');
});

In your package.json:

"scripts": {
  "start": "functions-framework --target=helloWorld"
}

Then run:

npm start

To quickly test a function without setting up a full project, create an index.js file and use npx to run the framework directly, specifying the exported function name with the --target flag.

// index.js
exports.helloWorld = (req, res) => {
  res.send('Hello, World');
};

npx @google-cloud/functions-framework --target=helloWorld

You can package your function into a container image using the pack tool and Google Cloud buildpacks. This is useful for deploying to Knative-based environments or Cloud Run.

pack build \
  --builder gcr.io/buildpacks/builder:v1 \
  --env GOOGLE_FUNCTION_SIGNATURE_TYPE=http \
  --env GOOGLE_FUNCTION_TARGET=helloWorld \
  my-first-function

# To run the container locally:
docker run --rm -p 8080:8080 my-first-function

To test functions that expect event-driven signatures (like CloudEvents), you must configure the functions-framework with the --signature-type=event flag.

When this mode is enabled, the function is no longer accessible via standard HTTP GET requests from a browser. Instead, it expects POST requests where the body conforms to the expected event schema (e.g., a Pub/Sub push subscription payload).

{
  "scripts": {
    "start": "functions-framework --target=helloPubSub --signature-type=event"
  }
}

To deploy your container to Cloud Run, build the image with a tag pointing to your Google Container Registry (gcr.io/$GOOGLE_CLOUD_PROJECT/image-name), push the image, and then use gcloud run deploy to launch it. Replace $GOOGLE_CLOUD_PROJECT with your actual project ID.

docker build -t gcr.io/$GOOGLE_CLOUD_PROJECT/helloworld .
docker push gcr.io/$GOOGLE_CLOUD_PROJECT/helloworld
gcloud run deploy helloworld --image gcr.io/$GOOGLE_CLOUD_PROJECT/helloworld --region us-central1

You can debug your functions using standard Node.js debugging tools by running the Functions Framework through the node executable with the --inspect flag. This allows you to attach an IDE (like VS Code) or Chrome DevTools to the running process.

To debug, you must run the symlinked executable located in node_modules/.bin/functions-framework directly via node --inspect rather than using the functions-framework command directly. This ensures the debugger attaches to the correct entrypoint.

If your package.json is correctly configured with the main field pointing to the compiled code and a gcp-build script, you can deploy your TypeScript function using the standard gcloud functions deploy command.

gcloud functions deploy TypescriptFunction \
--runtime nodejs16 \
--trigger-http

You can locally test a Pub/Sub-triggered function by sending a POST request containing a JSON payload that mimics a Pub/Sub push subscription.

1. Create a JSON file (e.g., mockPubsub.json) containing the message and subscription keys.
2. Use curl to send the file as the request body.
3. You must include specific CloudEvent headers to ensure the framework processes the request correctly as an event.

{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
    "messageId": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}