nextjs

Examples for Next.js

The examples in this directory illustrate the use of GRIP using a Next.js application as the backend.

• http-stream/ - HTTP streaming using GRIP.
• websocket/ - WebSocket-over-HTTP using GRIP.

For details on each example, view the README file in its respective directory.

Running the examples locally

Each example can be run locally by running it alongside an instance of Pushpin.

To run the examples locally, you'll need:

• Node.js (v18 or newer)
• Pushpin - installation instructions

NOTE: Instead of local Pushpin, you can also run the examples using Fastly Fanout for the GRIP proxy. See Running the examples on Fastly Fanout below.

1. Set up Pushpin by modifying the routes file with the following content (See this page for details on Pushpin configuration):

* 127.0.0.1:3000

2. Start Pushpin.

pushpin

By default, it will listen on port 7999, with a publishing endpoint open on port 5561. Leave Pushpin running in that terminal window.

3. In a new terminal window, switch to the example's directory, and install dependencies:

npm install

4. Start the example:

npm run start

This will invoke next dev to start the local server to run the example application.

5. Go on to follow the steps under each example's README file.

Description of common code between the examples

Each example has the same general structure in an src/ directory that contains:

• app/api/ to define the API endpoints
  • Checking GRIP status
  • Handling (specific to the example)
• utils/ directory
  • Configuring GRIP and instantiating the Publisher

API Routes

Following the format of Route Handlers in Next.js applications, these examples declare files in the app/api/ directory.

Configuration of GRIP

Each example interfaces with GRIP using the Publisher class. The code for this exists in the src/utils/publisher.ts file.

To configure Publisher, a GRIP configuration object gripConfig is used. The example applications give it a default value of http://127.0.0.1:5561/ to point to local Pushpin.

let gripConfig: string | IGripConfig = 'http://127.0.0.1:5561/';

It may be overridden using a GRIP_URL, which in the Next.js backend application is set as an environment variable. Additionally, in the example, the utility function parseGripUri is used to merge in the GRIP_VERIFY_KEY if it's required by the proxy.

let gripConfig: string | IGripConfig = 'http://127.0.0.1:5561/';
const gripUrl = process.env.GRIP_URL;
if (gripUrl) {
    gripConfig = parseGripUri(gripUrl, { 'verify-key': process.env.GRIP_VERIFY_KEY });
}

Alternatively, the values for FANOUT_SERVICE_ID and FANOUT_API_TOKEN are checked, and if present, they are used with the buildFanoutGripConfig() function to build the gripConfig.

const fanoutServiceId = process.env.FANOUT_SERVICE_ID;
const fanoutApiToken = process.env.FANOUT_API_TOKEN;
if (fanoutServiceId != null && fanoutApiToken != null) {
    gripConfig = buildFanoutGripConfig({
        serviceId: fanoutServiceId,
        apiToken: fanoutApiToken,
    });
}

Finally, this gripConfig is used to instantiate Publisher.

const publisher = new Publisher(gripConfig);

In the Next.js example, this initialization happens in the src/utils/publisher.ts file, and that single instance is reused among incoming requests.

GRIP status

The backend application is intended to be called via a GRIP proxy. When the handler runs, a GRIP proxy will have inserted a Grip-Sig header into the request, which it has signed with a secret or key.

Route handlers that issue GRIP instructions call publisher.validateGripSig to validate this header, storing the result in the gripStatus variable.

const gripStatus = await publisher.validateGripSig(request.headers.get('grip-sig'));

This result can be checked for three fields: gripStatus.isProxied - When true, indicates that the current request is behind a GRIP proxy. If needsSigned is true, then this will only be true if the signature validation has also succeeded. gripStatus.needsSigned - When true, indicates that the GRIP proxy specified in the configuration signs incoming requests. gripStatus.isSigned - When true, indicates that the signature validation was successful.

Handling Routes

The route handlers in each example handle requests in their respective ways. Refer to the README in each project for details.

Running the examples with Fastly Fanout as the GRIP proxy

By publishing these examples publicly, they can also be run behind Fastly Fanout to benefit from a global network and holding client connections at the edge.

Aside from your backend application running publicly on the internet, you will need a separate Fastly Compute service with Fanout enabled. This Fastly service runs a small program at the edge that examines each request and performs a "handoff" to Fanout for relevant requests, allowing Fanout to hold client connections and interpret GRIP messages.

The Fastly Fanout Forwarding Starter Kit (JavaScript) can be used for this purpose. In many cases it can be used as is, or as a starting point for further customization.

One simple way to do this is to host the example backend in a free "Hobby" Vercel account, and then set up a Fastly service with a free trial of Fanout.

Setting up Fastly and the Fanout Forwarding starter kit

The following steps describe the process of setting up the Fastly Fanout Forwarding Starter Kit (JavaScript) on your Fastly account.

1. If you don't already have a Fastly account, sign up for a free developer account.

2. Create a new API token (personal access token) that has global scope for your account.

3. If you haven't already installed the Fastly CLI, install it.

4. Set up the Fastly CLI with a user profile, using your API token from above.

5. Create a new directory where you will set up Fastly Fanout Forwarding, and switch to the directory.

mkdir fastly-fanout-forward
cd fastly-fanout-forward

6. Initialize the directory as a Fastly Compute application. Provide a name for the application, a description, and author info.

fastly compute init --from=https://github.com/fastly/compute-starter-kit-javascript-fanout-forward

7. Deploy the application to your Fastly account.

fastly compute publish --status-check-off

• You will be asked whether you want to create a new service. Reply y. Provide the following values:
  • Service name: Use the default value, or provide a name that you like.
  • Domain: Use the default value, or choose a subdomain of edgecompute.app that you like.
  • Backend: For now, do not specify any backends.
• Your service will be packaged and deployed to a new service.
  • Make a note of the new service's ID (You'll need it to configure the publisher in the next section).

8. You'll come back to Fastly to set up Fanout and origin host later.

Setting up the example (backend) code

Follow the steps provided by Vercel to set up your code to be deployed to Vercel's platform.

You'll want to deploy and keep in mind the following:

• You need to set up environment variables for your Vercel application to set up the environment variables needed to configure the Publisher.

  You may either provide FANOUT_SERVICE_ID and FANOUT_API_TOKEN, or GRIP_URL and GRIP_VERIFY_KEY.

  1. Using FANOUT_SERVICE_ID and FANOUT_API_TOKEN:
     • FANOUT_SERVICE_ID - Set this to your Fastly service ID.
     • FANOUT_API_TOKEN - Set this to your Fastly API token.
  2. Using GRIP_URL:
     • GRIP_URL - Set this to 'https://api.fastly.com/service/<SERVICE_ID>?key=<FASTLY_API_TOKEN>&verify-iss=fastly:<SERVICE_ID>'.
       • Replace both instances of <SERVICE_ID> in the URL with your Fastly service ID.
       • Replace <FASTLY_API_TOKEN> in the URL with your Fastly API token.
       • Don't forget to put single quotes around the whole thing, so that Glitch can treat the colon and ampersand literally.
     • GRIP_VERIFY_KEY - Set this to the value {\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"CKo5A1ebyFcnmVV8SE5On-8G81JyBjSvcrx4VLetWCg\",\"y\":\"7gwJqaU6N8TP88--twjkwoB36f-pT3QsmI46nPhjO7M\"}

• You'll need to note the Public domain name of your Vercel application. Public domain names given by Vercel may look something like this: <name>.vercel.app.

Enable Fanout on your Fastly service, and point it at your backend

1. Switch back to the terminal window where you deployed your Fastly Fanout Forwarding service.

2. Type the following command to add the example application to your Fastly service as a backend with the name origin. Insert the public hostname of your example backend in the command below.

fastly backend create --autoclone --version=active --name=origin --address=<example public hostname>    

3. Activate the newly created version.

fastly service-version activate --version=latest

4. Enable Fanout on your service.

fastly products --enable=fanout

5. Wait a moment for the updates to deploy across Fastly's network.

6. Go on to follow the steps under each example's README file.

When you do this, access the application at your Fastly service's domain name (e.g., https://<something>.edgecompute.app/) instead of your local Pushpin address.

Back to examples