@jambaree/next-wordpress v2.0.0

@jambaree/next-wordpress

Project Update Notice: This project has been succeeded by @nextwp/core, which offers enhanced features and improved performance. For those looking to upgrade or migrate, detailed documentation and guidance can be found here: nextwp.org.

You can view and download the latest version of @nextwp/core on NPM: npmjs.com/package/@nextwp/core.

Please note, this project will no longer receive updates and is provided as-is for historical reference.

Since @nextwp/core supports mostly the same APIs, but with enhanced functionality, the migration should be seamless. Just replace all imports with @nextwp/core.

Welcome to @jambaree/next-wordpress v2. This package facilitates building Next.js sites using headless WordPress as the CMS.

It is built on the WP REST API and has additional functions designed to work with the Jambaree Headless WordPress plugin.

Features

• WP REST API Integration: Leverages WP REST API for optimized performance.
• Enhanced Caching: GET requests are cached at the WP server and in NextJS.
• Speedy Development: Reduces development time by eliminating the need for writing extensive queries.

Prerequisites

Before you begin, ensure you have the following WordPress plugins installed:

• Advanced Custom Fields PRO: Enables custom fields in WordPress.
• Yoast SEO: Provides SEO features for WordPress sites.
• Jambaree Next WP Plugin: Essential for CMS previews in NextJS. Plugin link

Installation

Install @jambaree/next-wordpress@beta via npm:

npm install @jambaree/next-wordpress@beta

Quick Start

Here's a basic example to get started:

// src/app/[[...paths]]/page.tsx
import { WordpressTemplate } from "@jambaree/next-wordpress";
import templates from "@/templates";

export default function PageTemplate(props) {
  return (
    <WordpressTemplate
      params={props.params}
      searchParams={props.searchParams}
      templates={templates}
    />
  );
}

export {
  generateMetadata,
  generateStaticParams,
} from "@jambaree/next-wordpress";

Configuration

Environment Variables

The following environment variables are required for configuring @jambaree/next-wordpress:

• NEXT_PUBLIC_WP_URL: The URL of your WordPress site.
• NEXT_SITE_URL: The URL of your Next.js site.
• REVALIDATE_SECRET_KEY: A secret key used for revalidation.
• WP_APPLICATION_PASSWORD: The application password for authenticating with WordPress.
• NEXT_PREVIEW_SECRET: The secret key for preview mode.

Make sure to set these environment variables in your project's configuration.

Usage

Importing Templates file

Import and define your page templates:

// Example templates file
import ContactPageTemplate from "./page/contact";
import DefaultPageTemplate from "./page/default";

const templates = {
  // post type slug in WP
  page: {
    // template name in WP
    default: DefaultPageTemplate,
    contact: ContactPageTemplate,
  },
};

export default templates;

Default page template example

This example uses the Flexible Content component to render blocks

// Default page template file
import { FlexibleContent } from "@jambaree/next-wordpress";
import * as blocks from "@/components/blocks";

export default function DefaultPageTemplate({ data }) {
  return <FlexibleContent blocks={blocks} rows={data?.acf?.flexible_content} />;
}

API Reference

This document provides detailed information about the functions and components available in the @jambaree/next-wordpress package.

Next.js App Functions

generateStaticParams

Generates static routes for a Next.js site based on WordPress REST API results.

See https://nextjs.org/docs/app/api-reference/functions/generate-static-params for more information.

• Parameters:
  • wpUrl: String - The WordPress URL (optional, default is NEXT_PUBLIC_WP_URL env variable).
  • postTypes: Array<String> - The post types to include in static generation (default: "pages", "posts").
• Returns: Promise<Array>

• Usage: This function should be used in your app/[[...paths]]/page.tsx file.

  // with default settings
  export { generateStaticParams } from "@jambaree/next-wordpress";
  
  // with additional post types
  const staticParams = generateStaticParams({
    postTypes: ["pages", "posts", "movie"],
  });
  export { staticParams as generateStaticParams };

generateSiteMap

Generates a sitemap.xml file for a site using the WordPress REST API.

• Parameters:
  • postTypes: Array<String> - The post types to include in the sitemap (default: "pages", "posts").
• Returns: Promise<MetadataRoute.Sitemap>

• Usage: This function should be used in your app/sitemap.ts file.

  // with default settings
  export { generateSiteMap as default } from "@jambaree/next-wordpress";

  // with additional post types
  import { generateSiteMap } from "@jambaree/next-wordpress";
  import { MetadataRoute } from "next";
  
  export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
    const sitemap = await generateSiteMap({
      postTypes: ["pages", "posts", "movie"],
    });
  
    return sitemap;
  }

revalidate

Triggers revalidation of specified paths in a Next.js app.

• Parameters:
• request: Request - Contains the paths to be revalidated.
• Returns: Promise<Response>
• Usage:

// app/api/revalidate/route.ts
export { revalidate as PUT } from "@jambaree/next-wordpress";

Using Next.js Draft Mode with WordPress Preview

NextWordPressPreview

Handles preview routes in Next.js draft mode to preview changes to WordPress content instantly.

⚠ This draft mode function is used with the Jambaree Headless WordPress plugin to replace the default WordPress preview with an iframe of the Next.js preview route.

• Parameters:
  • request: Request - The request object.
  • context: RouteHandlerContext - The response context.
  • options: PreviewOptions - Options for the preview.
    • toolbar: Boolean - Whether to display draft mode toolbar (default: false).
• Returns: Function or Response

• Usage:

  // app/api/draft/[...preview]/route.ts
  export { NextWordPressPreview as GET };

  With additional options:

  // app/api/draft/[...preview]/route.ts
  import { NextWordPressPreview } from "@jambaree/next-wordpress";
  
  const previewOptions = {
    toolbar: true,
  };
  
  const previewHandler = NextWordPressPreview(previewOptions);
  
  export { previewHandler as GET };

REST API Functions

getPageData

Fetches data for a specific page from a WordPress REST API endpoint.

This function is used by the WordpressTemplate component, so you don't need to use it directly in your code but it is available if you need it.

• Parameters:
  • uri: String - The URI of the page.
• Returns: Promise<Object>
• Usage:

  const pageData = await getPageData("/about");

getMenuItems

Retrieves menu items from a WordPress site.

• Parameters:
  • slug: String - The slug of the menu.
• Returns: Promise<Array>
• Usage:

  const menuItems = await getMenuItems({ slug: "main-menu" });

Custom REST API Functions

getOptionsPage

Fetches data from an options page created in WordPress.

⚠ This function requires the Jambaree Headless WordPress plugin to register the REST API endpoint for fetching options pages.

• Parameters:
  • slug: String - The slug of the options page.
• Returns: Promise<Object>
• Usage:

  const options = await getOptionsPage({ slug: "theme-options" });

React Components

FlexibleContent

A React component for rendering ACF flexible content blocks.

• Props:
  • blocks: Object - Map of React components to be rendered for each ACF flexible content layout.
  • rows: Array - Array of row data from an acf flexible content field.
  • data: Object - Extra data passed to each component (optional).

• Usage:

  import { FlexibleContent } from "@jambaree/next-wordpress";

  import * as blocks from "@/components/blocks";
  
  export default async function DefaultPageTemplate({ data }) {
    return <FlexibleContent rows={data?.acf?.modules} blocks={blocks} />;
  }

WordpressTemplate

A component for rendering WordPress templates in a Next.js app.

• Props:
  • params: Object - Routing parameters.
  • templates: Object - Map of page templates.
  • searchParams: Object - Search parameters (optional).

• Usage:

  // src/app/[[...paths]]/page.tsx
  import { WordpressTemplate } from "@jambaree/next-wordpress";
  import templates from "@/templates";
  
  export default async function PageRoute(props: {
    params: { paths: string[] };
    searchParams?: { [key: string]: string | string[] | undefined };
  }) {
    return (
      <WordpressTemplate
        templates={templates}
        params={props?.params}
        searchParams={props?.searchParams}
      />
    );
  }
  
  export {
    generateMetadata,
    generateStaticParams,
  } from "@jambaree/next-wordpress";

Deprecated Functions

getData and getSeedData

These functions have been deprecated and removed in v2. Please use getPageData instead. They were removed due to the migration to REST API from GraphQL.