Nokkio Documentation: Page Module API

Any file added to a Nokkio application’s pages/ directory becomes a "page module" and must adhere to the Page Module API.

Page component

Page modules have one hard requirement: a module must contain a React component as its default export. That component will be invoked when a route matching this page's path is loaded.

pages/about.js

export default function About() {
  return <h1>About me</h1>;
}

If the route contains a parameter, it will be provided to the component in the params prop:

pages/about/[name].js

export default function TeamMember({ params }) {
  return <h1>About: {params.name}</h1>;
}

Page data

Page modules that depend on data may define a getPageData function to begin loading the data as early as possible. In the following example, a post detail page loads the post as part of the page data contract, then accesses that data in the page's component with theusePageData hook.

pages/posts/[id].js

import { Post } from '@nokkio/magic';
import { usePageData } from '@nokkio/router';

export async function getPageData({ params }) {
  return {
    post: await Post.findById(params.id),
  }
}

export default function PostPage() {
  const { post } = usePageData();

  return <h1>{post.title}</h1>;
}

The getPageData function must return a promise and can either provide a single value directly or a flat object of key / values.

Page metadata

A page module may also set metadata intended for the HTML page’s <head> element. The getPageMetadata function is called after getPageData has resolved, and is provided the resolved page data as part of the function’s first argument.

Extending the previous post page example, the following will set the page’s title to the post’s title:

pages/posts/[id].js

import { Post } from '@nokkio/magic';
import { usePageData } from '@nokkio/router';

export async function getPageData({ params }) {
  return {
    post: await Post.findById(params.id),
  }
}

export function getPageMetadata({ pageData }) {
  return { title: pageData.post.title };
}

export default function PostPage() {
  const { post } = usePageData();

  return <h1>{post.title}</h1>;
}

The getPageMetadata function also receives the route’s resolved parameters and the currently authenticated user, if the Nokkio application is set up to use authentication:

export function getPageMetadata({ params, pageData, auth }) {
  // any parameterized routes segments
  console.log(params);
  // resolved page data, if applicable
  console.log(pageData);
  // the authenticated user, if applicable
  console.log(auth);
}

Metadata defined at the page module level overrides any defaults defined in your root document.

HTTP status code

By default, pages return HTTP 200 as their status when the route is loaded. In some cases, it is desirable to change this to signal a different type of response. Continuing with the post page example, this change returns a 404 when the post cannot be found:

pages/posts/[id].js

import { Post } from '@nokkio/magic';
import { usePageData } from '@nokkio/router';

export async function getPageData({ params }) {
  return {
    // findById returns null when no post is found
    post: await Post.findById(params.id),
  }
}

export function getPageMetadata({ pageData }) {
  const { post } = pageData;

  if (!post) {
    return {
      http: { status: 404 },
      title: "Not found",
    };
  }

  return { title: post.title };
}

export default function PostPage() {
  const { post } = usePageData();

  if (!post) {
    return <h1>Post not found.</h1>;
  }

  return <h1>{post.title}</h1>;
}