Writing Your Web Service with Node.js

This guide shows how to write a Node.js web service to run in the App Engine standard environment. To learn more about the Node.js runtime and how it works, see Node.js Runtime Environment.

Before you begin

Key points

  • You can use dependencies by listing them in your package.json file. See Specifying Dependencies for more information.
  • App Engine starts your application by running npm start.
  • Your server must listen to the port specified by the process.env.PORT environment variable.
  • You need an app.yaml file to deploy your service to App Engine.

Creating a server to listen for HTTP requests

The core of your web service is the HTTP server. The sample code in this guide uses the Express.js framework to handle HTTP requests, but you are free to use a web framework of your choice.

  1. Create a new folder called my-nodejs-service for your Node.js service.

  2. Navigate to the folder in your terminal, and create a package.json file by running npm init.

  3. Add Express as a dependency by running:

    npm install express
    

    Confirm that Express appears in your package.json file's dependencies field. Here's an example:

    {
      ...
      "dependencies": {
        "express": "^4.16.3"
      }
      ...
    }
    
  4. Add a start script to your package.json file:

    "scripts": {
      "start": "node server.js"
    }
    
  5. Create a file called server.js in the same folder and add the following code:

    const express = require('express');
    const app = express();
    
    app.get('/', (req, res) => {
      res.send('Hello from App Engine!');
    });
    
    // Listen to the App Engine-specified port, or 8080 otherwise
    const PORT = process.env.PORT || 8080;
    app.listen(PORT, () => {
      console.log(`Server listening on port ${PORT}...`);
    });

This is a very basic web server - it responds to all GET requests to the root path ('/') with the text "Hello from App Engine!" The most important part of this code is on the last four lines, where the server is set to listen to the port specified by process.env.PORT, an environment variable set by the App Engine runtime. If your server isn't set to listen to this port, it will not receive requests.

Notice that if process.env.PORT is not set, port 8080 is used as a default. This is necessary for testing your app locally, because process.env.PORT doesn't get set during local runs - it is only set when your app is running on App Engine. You can use whichever port you prefer for testing, but this guide uses 8080.

Running the server locally

To run the server locally:

  1. Run npm start in your terminal. This will run your server.js file.

  2. Point your web browser to http://localhost:8080.

You should see a page with the text "Hello from App Engine!"

Creating the app.yaml file

The most important configuration file for a web service running on App Engine is the app.yaml file, which specifies your service's runtime environment settings. Your service will not deploy without this file.

  1. In your my-nodejs-service folder, create a file called app.yaml.

  2. Add the following contents:

    runtime: nodejs8

This is the most basic configuration possible. It indicates to App Engine that you're using the Node.js 8 runtime. The app.yaml file can also specify network settings, scaling settings, and more. For more information, see the app.yaml reference.

At this point, you should have a file structure like the following:

my-nodejs-service/
  app.yaml
  package.json
  server.js

Next steps

Now that you've created a simple Node.js web server that listens to the correct port and you've specified the runtime in an app.yaml file, you're ready to deploy your service on App Engine.

Was this page helpful? Let us know how we did:

Send feedback about...

App Engine standard environment for Node.js docs