getPages

An instance method that provides data about the pages you’ve created within Makeswift

Options

Return Type

1
type MakeswiftPage = {
2
  id: string,
3
  path: string,
4
  title: string | null,
5
  description: string | null,
6
  canonicalUrl: string | null,
7
  socialImageUrl: string | null,
8
  sitemapPriority: number | null,
9
  sitemapFrequency: string | null,
10
  createdAt: string,
11
  updatedAt: string,
12
  publishedAt: string | null,
13
  isOnline: boolean | null,
14
  excludedFromSearch: boolean | null,
15
  locale: string,
16
  localizedVariants: {
17
    locale: string,
18
    path: string
19
  }[]
20
}
21
22
// Final return type
23
type MakeswiftGetPagesResult = {
24
  data: MakeswiftPage[],
25
  hasMore: boolean
26
}

Concepts

Pagination & Async Iterables

The requests made by getPages are paginated. A paginated request will only retrieve a portion of the total pages per request. If you have a large number of pages, you may need to paginate through the results to retrieve all of them.

To make this easier, the returned value of getPages is an extension of a Promise and an AsyncIterable. This abstraction enables you to consume the pages in multiple ways, allowing you to easily retrieve all pages without worrying about the implementation details of pagination:

1
import { MakeswiftPage } from "@makeswift/runtime/next"
2
import { client } from "../../../../../makeswift/client"
3
4
export async function getAllPages() {
5
  // The `toArray` method on the iterable will return all pages as an array
6
  const pagesFromToArray = await client.getPages().toArray()
7
8
  // You can also get all pages with a `for await` loop
9
  const pagesFromForAwait: MakeswiftPage[] = []
10
  for await (const page of client.getPages()) {
11
    pagesFromForAwait.push(page)
12
  }
13
14
  // Get a single paginated result set 
15
  const { data: pagesFromPagination } = await client.getPages({ limit: 5 })
16
}

The custom async iterable returned by getPages includes the following methods:

• toArray(): Promise<T[]>: Consumes all pages in the iterable and returns them as an array.

• map(callback: (item: T) => U): Maps over each page in the iterable to yield a new data type. Returns another async iterable.

• filter(predicate: (item: T) => Boolean): Selectively yields pages based on a predicate function. Returns another async iterable.

Because .map and .filter return another iterable, you can chain these methods together:

1
const pages = await client.getPages()
2
  .filter((page) => !page.excludedFromSearch)
3
  .map((page) => ({ id: page.id, title: page.title }))
4
  .toArray()

For more details on async iterables, see the MDN documentation.

The pagination for this method is cursor based, meaning that you can pass an id of a page to the after option to retrieve the next set of pages after that page. This can be used to manually implement paginating through all pages:

1
import { MakeswiftPage } from "@makeswift/runtime/next"
2
import { client } from "../../../../../makeswift/client"
3
4
export async function getAllPages() {
5
  const pages: MakeswiftPages[] = []
6
  let cursor: string | undefined = undefined
7
  let hasMorePages = true
8
9
  do {
10
    const paginatedResults = await client.getPages({ limit: 5, after: cursor })
11
    pages.push(...paginatedResults.data)
12
    hasMorePages = paginatedResults.hasMore
13
    cursor = paginatedResults.data.at(-1)?.id
14
  } while (hasMorePages)
15
16
  return pages
17
}

Site Versions

By default, getPages will return data reflecting the state of published Makeswift pages. To specify which variant of your pages you want to retrieve, you can pass a value to the siteVersion option. If your site is using pages router, use the getSiteVersion method to retrieve the current site version. If your site is using app router, use the getSiteVersion function.

Note that the publishedAt field of a page will always be null when retrieving non-live versions of the site. This is because the page data has not been published yet.

Similarly, if you need to retrieve information on pages that are not currently online (even if they have been published), you can pass includeOffline: true to the getPages method. By default, offline pages are excluded from results.

Usage

Path Prefix Filtering

Path prefix filtering allows you to selectively retrieve your Makeswift pages based on if they start with a specific path. For example, suppose you have many pages organized under the path /blog/. You can use the pathPrefix option to retrieve all pages that start with /blog/:

1
import { client } from '../../../../../makeswift/client'
2
3
async function getBlogPages() {
4
  return await client.getPages({ pathPrefix: '/blog/' }).toArray()
5
}

Static Path Generation

Since Makeswift pages use dynamic routes with Next.js, you may want to statically generate paths for your pages at build time. In pages router, this can be done by defining getStaticPaths on your catch-all page:

1
import { GetStaticPathsResult } from 'next'
2
import { Makeswift } from '@makeswift/runtime/next'
3
import { client } from '../../../../../makeswift/client'
4
5
type ParsedUrlQuery = { path?: string[] }
6
7
export async function getStaticPaths(): Promise<
8
  GetStaticPathsResult<ParsedUrlQuery>
9
> {
10
  return {
11
    paths: await client
12
      .getPages()
13
      .map((page) => ({
14
        params: {
15
          path: page.path.split("/").filter((segment) => segment !== ""),
16
        },
17
      }))
18
      .toArray(),
19
    fallback: "blocking",
20
  };
21
}

Similarly for app router, static generation is done by defining generateStaticParams on your dynamically routed page:

1
import { client } from '../../../../../makeswift/client'
2
3
type ParsedUrlQuery = { path?: string[] }
4
5
export async function generateStaticParams() {
6
  return await client.getPages().map(page => ({
7
      path: page.path.split('/').filter(segment => segment !== '')
8
    }))
9
    .toArray()
10
}

Generating a Sitemap

The data from getPages can be used to generate a sitemap.xml file for your site, allowing search engines to index your pages.

Here’s an example of how to use getPages with the next-sitemap library to generate a sitemap:

1
import { getServerSideSitemapLegacy } from 'next-sitemap'
2
import { MakeswiftPage } from '@makeswift/runtime/next'
3
import { client } from '../../../../../makeswift/client'
4
5
const DOMAIN = 'https://example.com'
6
const DEFAULT_PRIORITY = 0.75
7
const DEFAULT_FREQUENCY = 'hourly'
8
9
function pageToSitemapItem(page: MakeswiftPage) {
10
  const pageUrl = new URL(page.path, DOMAIN)
11
  return {
12
    loc: pageUrl.href,
13
    lastmod: page.createdAt,
14
    changefreq: page.sitemapFrequency ?? DEFAULT_FREQUENCY,
15
    priority: page.sitemapPriority ?? DEFAULT_PRIORITY,
16
    alternateRefs: page.localizedVariants.map(variant => {
17
      const localizedPath = `/${variant.locale}/${variant.path}`
18
      const localizedPageUrl = new URL(localizedPath, DOMAIN)
19
      return {
20
        hreflang: variant.locale,
21
        href: localizedPageUrl.href,
22
      }
23
    }),
24
  }
25
}
26
27
export async function getServerSideProps(context) {
28
  const sitemap = client
29
    .getPages()
30
    .filter(page => !page.excludedFromSearch)
31
    .map(page => pageToSitemapItem(page))
32
    .toArray()
33
34
  return getServerSideSitemapLegacy(context, sitemap)
35
}
36
37
export default function Sitemap() {}

Next.js app router also has built-in support for generating sitemaps. We can use getPages to retrieve pages and map them to the format expected by Next.js:

1
import { MetadataRoute } from 'next'
2
import { MakeswiftPage } from '@makeswift/runtime/dist/types/next'
3
import { client } from '../../../../../makeswift/client'
4
5
type NextSitemapItem = MetadataRoute.Sitemap[number]
6
7
const DOMAIN = 'https://example.com'
8
const DEFAULT_PRIORITY = 0.75
9
const DEFAULT_FREQUENCY = 'hourly'
10
11
function pageToSitemapEntry(page: MakeswiftPage): NextSitemapItem {
12
  const pageUrl = new URL(page.path, DOMAIN)
13
  return {
14
    url: pageUrl.href,
15
    lastModified: page.createdAt,
16
    changeFrequency: page.sitemapFrequency ?? DEFAULT_FREQUENCY,
17
    priority: page.sitemapPriority ?? DEFAULT_PRIORITY,
18
  }
19
}
20
21
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
22
  return client
23
    .getPages()
24
    .filter(page => !page.excludedFromSearch)
25
    .map(page => pageToSitemapEntry(page))
26
    .toArray()
27
}

A few things to note:

• By default, getPages will return pages that are excluded from search. You can filter these pages out while constructing your sitemap based on the excludedFromSearch property.

• getPages will return the path of the page, which is relative to the root of the site. Depending on whether your host is using path-based or domain-based routing for localization, you may need to prepend the domain or locale to the path.

• If you did not explicitly set a sitemapPriority or sitemapFrequency for a page in the Makeswift builder, these attributes will be null in the response. You can specify default values for these fields in your sitemap generation logic.

Localization

To retrieve pages that you’ve created in one of your registered locales, you can pass the locale option to the getPages method. Each returned page will include any of its localized alternates in the localizedVariants field.

1
import { client } from '../../../../../makeswift/client'
2
3
async function getFrenchPages() {
4
  return await client.getPages({ locale: 'fr-FR' }).toArray()
5
}

If you do not pass a locale option, pages from your site’s default locale will be returned. Each page will include any of its localized alternates in the localizedVariants field.

For an example of how to use getPages with localization to statically generate paths in Next.js app router, see here.

Changelog