Response Helpers

next-runtime includes a few convenient helpers to increase the readability of your return statements. Usage is recommended, but entirely optional.

#

json

Returns the provided data as response in case of JSON api requests. For standard HTML requests, the prop are wrapped with { props: { ... } } and handed over to Next.js.

import { handle, json } from 'next-runtime';

export const getServerSideProps = handle({
  async get() {
    // { props: { hello: 'world' } }
    return json({ hello: 'world' }, options);
  },
});

Options

As second argument a status code, or response initialization object can be provided.

• statusCode json(data, statusCode)

  If you just need a status code other than 200, you might want to call it like json(data, number). In that case, the statusCode will be applied to the response stream.

• ResponseInit json(data, ResponseInit)

  Use this if you need more control over the response. For example if you need a custom statusText or need to send additional headers. See response options for more.

#

redirect

In case of JSON api requests, redirect sets the location header to forward the requests. For standard HTML requests, the input is mapped to the { redirect: { destination } } format and handed over to Next.js.

import { handle, redirect } from 'next-runtime';

export const getServerSideProps = handle({
  async get() {
    // { redirect: { destination: '/other-page', permanent: false } }
    return redirect('/other-page', options);
  },
});

Options

As second argument, a status code, next-like options, or response initialization object can be provided. The options are optional, and the redirect defaults to a temporary redirect (status: 302).

• statusCode redirect(data, statusCode)

  If you prefer specifying the status code like 301 or 302, you might want to call it like redirect('/destination', number). In that case, the statusCode will be applied to the response stream.

• options redirect(destination, { permanent: boolean })

  A more next-like signature. Specify { permanent: true } to mark it as a permanent redirect, or { permanent: false } to mark the redirect as temporary.

• ResponseInit json(data, ResponseInit)

  Use this if you need more control over the response. For example if you need a custom statusText or need to send additional headers. See response options for more.

#

notFound

Return this statement when you want to show the user that this page doesn't exist. Either because it really doesn't, or they shouldn't know it does because they lack permissions.

import { handle, notFound } from 'next-runtime';

export const getServerSideProps = handle({
  async get() {
    // { notFound: true }
    return notFound(options);
  },
});

Options

As first argument, a status code, or response initialization object can be provided. The options are optional, and the statusCode defaults to 404.

• statusCode notFound(statusCode)

  If you need a more specific (sub) status, you might want to call it like notFound(number). In that case, the statusCode will be applied to the response stream.

• ResponseInit notFound(ResponseInit)

  Use this if you need more control over the response. For example if you need a custom statusText or need to send additional headers. See response options for more.

#

Response Options

Every response helper accepts ResponseInit as optional argument. ResponseInit is based on the Response interface of the Fetch API

The following options are supported:

• status number

  The status code of the response. (e.g., 200 for a success, and 401 for unauthorized).

• statusText string

  The status message corresponding to the status code. (e.g., OK for 200);

• headers Headers | { [key: string]: string }

  Any headers that you want to add to your response, contained within a Headers object, or object literal of string key/value pairs.

Example

import { handle, json } from 'next-runtime';

export const getServerSideProps = handle({
  async get() {
    return json(
      { hello: 'world' },
      {
        status: 200,
        statusText: 'OK',
        headers: {
          'x-server-time': Date.now(),
        },
      },
    );
  },
});

#

Common mistakes

These response helpers return an extended object based on the Response object. Thereby, they won't function with standard getServerSideProps functions. If you're getting a serialization error, or additional keys error, like below, then you're probably using these out of the context of next-runtime/handle.

Server Error
Error: Error serializing props returned from `getServerSideProps` in "...".
Reason: Props must be returned as a plain object from getServerSideProps: `{ props: { ... } }` (received: `[object Undefined]`).

Server Error
Error: Additional keys were returned from `getServerSideProps`. Properties intended for your component must be nested under the `props` key, e.g.: