Home

Awesome

Functions Framework for Node.js

npm version npm downloads

Node unit CI Node lint CI Node conformace CI Security Scorecard

An open source FaaS (Function as a Service) framework based on Express for writing portable Node.js functions -- brought to you by the Google Cloud Functions team.

The Functions Framework lets you write lightweight functions that run in many different environments, including:

The framework allows you to go from:

/**
 * Send "Hello, World!"
 * @param req https://expressjs.com/en/api.html#req
 * @param res https://expressjs.com/en/api.html#res
 */
exports.helloWorld = (req, res) => {
  res.send('Hello, World!');
};

To:

curl http://my-url
# Output: Hello, World!

All without needing to worry about writing an HTTP server or complicated request handling logic.

Watch this video to learn more about the Node Functions Framework.

Features

Installation

Add the Functions Framework to your package.json file using npm.

npm install @google-cloud/functions-framework

Quickstarts

Quickstart: Hello, World on your local machine

  1. Create an index.js file with the following contents:

    exports.helloWorld = (req, res) => {
      res.send('Hello, World');
    };
    
  2. Run the following command:

    npx @google-cloud/functions-framework --target=helloWorld
    
  3. Open http://localhost:8080/ in your browser and see Hello, World.

Quickstart: Set up a new project

  1. Create a package.json file using npm init:

    npm init
    
  2. Create an index.js file with the following contents:

    const functions = require('@google-cloud/functions-framework');
    
    functions.http('helloWorld', (req, res) => {
      res.send('Hello, World');
    });
    
  3. Now install the Functions Framework:

    npm install @google-cloud/functions-framework
    
  4. Add a start script to package.json, with configuration passed via command-line arguments:

      "scripts": {
        "start": "functions-framework --target=helloWorld"
      }
    
  5. Use npm start to start the built-in local development server:

    npm start
    ...
    Serving function...
    Function: helloWorld
    URL: http://localhost:8080/
    
  6. Send requests to this function using curl from another terminal window:

    curl localhost:8080
    # Output: Hello, World
    

Quickstart: Build a Deployable Container

  1. Install Docker and the pack tool.

  2. Build a container from your function using the Functions buildpacks:

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

    docker run --rm -p 8080:8080 my-first-function
    # Output: Serving function...
    
  4. Send requests to this function using curl from another terminal window:

    curl localhost:8080
    # Output: Hello, World!
    

Run your function on serverless platforms

Google Cloud Functions

The Node.js 10 runtime on Google Cloud Functions is based on the Functions Framework. On Cloud Functions, the Functions Framework is completely optional: if you don't add it to your package.json, it will be installed automatically.

After you've written your function, you can simply deploy it from your local machine using the gcloud command-line tool. Check out the Cloud Functions quickstart.

Cloud Run / Cloud Run for Anthos

After you've written your function, added the Functions Framework and updated your start script in package.json, deploy it to Cloud Run with gcloud run deploy. Check out the Cloud Run quickstart for Node.js.

If you want even more control over the environment, you can deploy to Cloud Run for Anthos. With Cloud Run for Anthos, you can run your function on a GKE cluster, which gives you additional control over the environment (including use of GPU-based instances, longer timeouts and more).

Container environments based on Knative

Cloud Run and Cloud Run for Anthos both implement the Knative Serving API. The Functions Framework is designed to be compatible with Knative environments. Just build and deploy your container to a Knative environment.

Configure the Functions Framework

You can configure the Functions Framework using command-line flags or environment variables. If you specify both, the environment variable will be ignored.

Command-line flagEnvironment variableDescription
--portPORTThe port on which the Functions Framework listens for requests. Default: 8080
--targetFUNCTION_TARGETThe name of the exported function to be invoked in response to requests. Default: function
--signature-typeFUNCTION_SIGNATURE_TYPEThe signature used when writing your function. Controls unmarshalling rules and determines which arguments are used to invoke your function. Default: http; accepted values: http or event or cloudevent
--sourceFUNCTION_SOURCEThe path to the directory of your function. Default: cwd (the current working directory)
--log-execution-idLOG_EXECUTION_IDEnables execution IDs in logs, either true or false. When not specified, default to disable. Requires Node.js 13.0.0 or later.

You can set command-line flags in your package.json via the start script. For example:

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

Enable Google Cloud Functions Events

The Functions Framework can unmarshall incoming Google Cloud Functions event payloads to data and context objects. These will be passed as arguments to your function when it receives a request. Note that your function must use the event-style function signature:

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

To enable automatic unmarshalling, set the function signature type to event using a command-line flag or an environment variable. By default, the HTTP signature will be used and automatic event unmarshalling will be disabled.

For more details on this signature type, check out the Google Cloud Functions documentation on background functions.

Enable CloudEvents

The Functions Framework can unmarshall incoming CloudEvents payloads to a cloudevent object. It will be passed as an argument to your function when it receives a request. Note that your function must use the cloudevent-style function signature:

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);
});

Advanced Docs

More advanced guides and docs can be found in the docs/ folder.

Contributing

Contributions to this library are welcome and encouraged. See CONTRIBUTING for more information on how to get started.