Get started with Next.js

Create either:

• pages/[[...catchall]].tsx if you want the / route to render the corresponding Plasmic page (you must remove any existing pages/index.tsx), or
• pages/[...catchall].tsx otherwise (your Plasmic project must not have a page whose route is /—change the route to something else if you do).

In all cases, the Plasmic page will only be there if there is no existing page for that route.

pages/[[...catchall]].tsx
Copy
import * as React from 'react';
import {
  PlasmicComponent,
  ComponentRenderData,
  PlasmicRootProvider,
  extractPlasmicQueryData
} from '@plasmicapp/loader-nextjs';
import { GetStaticPaths, GetStaticProps } from 'next';
import Error from 'next/error';
import { useRouter } from 'next/router';
import { PLASMIC } from '../plasmic-init';

/**
 * Use fetchPages() to fetch list of pages that have been created in Plasmic
 */
export const getStaticPaths: GetStaticPaths = async () => {
  const pages = await PLASMIC.fetchPages();
  return {
    paths: pages.map((page) => ({
      params: { catchall: page.path.substring(1).split('/') }
    })),
    fallback: 'blocking'
  };
};

/**
 * For each page, pre-fetch the data we need to render it
 */
export const getStaticProps: GetStaticProps = async (context) => {
  const { catchall } = context.params ?? {};

  // Convert the catchall param into a path string
  const plasmicPath =
    typeof catchall === 'string' ? catchall : Array.isArray(catchall) ? `/${catchall.join('/')}` : '/';
  const plasmicData = await PLASMIC.maybeFetchComponentData(plasmicPath);
  if (!plasmicData) {
    // This is some non-Plasmic catch-all page
    return {
      props: {}
    };
  }

  // This is a path that Plasmic knows about.
  const pageMeta = plasmicData.entryCompMetas[0];

  // Cache the necessary data fetched for the page.
  const queryCache = await extractPlasmicQueryData(
    <PlasmicRootProvider loader={PLASMIC} prefetchedData={plasmicData} pageParams={pageMeta.params}>
      <PlasmicComponent component={pageMeta.displayName} />
    </PlasmicRootProvider>
  );

  // Pass the data in as props.
  return {
    props: { plasmicData, queryCache },

    // Using incremental static regeneration, will invalidate this page
    // after 300s (no deploy webhooks needed)
    revalidate: 300
  };
};

/**
 * Actually render the page!
 */
export default function CatchallPage(props: { plasmicData?: ComponentRenderData; queryCache?: Record<string, any> }) {
  const { plasmicData, queryCache } = props;
  const router = useRouter();
  if (!plasmicData || plasmicData.entryCompMetas.length === 0) {
    return <Error statusCode={404} />;
  }
  const pageMeta = plasmicData.entryCompMetas[0];
  return (
    // Pass in the data fetched in getStaticProps as prefetchedData
    <PlasmicRootProvider
      loader={PLASMIC}
      prefetchedData={plasmicData}
      prefetchedQueryData={queryCache}
      pageParams={pageMeta.params}
      pageQuery={router.query}
    >
      {
        // pageMeta.displayName contains the name of the component you fetched.
      }
      <PlasmicComponent component={pageMeta.displayName} />
    </PlasmicRootProvider>
  );
}

Notes:

• You can use incremental static regeneration with getStaticProps.
• If your project has dynamic pages and you are using SSG, you will need to manually add your dynamic routes to getStaticPaths. Learn more about dynamic pages.

We use Next.js’s getStaticProps() to fetch the design statically.

For example, to render a page: add a file under pages/, named for your desired route, with the following code.

pages/mypage.tsx
Copy
// This page will show up at the route /mypage

import {
  PlasmicRootProvider,
  PlasmicComponent,
  ComponentRenderData,
  extractPlasmicQueryData
} from '@plasmicapp/loader-nextjs';
import { useRouter } from 'next/router';
import { PLASMIC } from '../plasmic-init';

// Statically fetch the data needed to render Plasmic pages or components.
export const getStaticProps = async () => {
  // You can pass in multiple page paths or component names.
  const plasmicData = await PLASMIC.fetchComponentData('COMPONENT_OR_PAGEROUTE');
  if (!plasmicData) {
    throw new Error('No Plasmic design found');
  }

  const compMeta = plasmicData.entryCompMetas[0];

  // Cache the necessary data fetched for the page
  const queryCache = await extractPlasmicQueryData(
    <PlasmicRootProvider loader={PLASMIC} prefetchedData={plasmicData} pageParams={compMeta.params}>
      <PlasmicComponent component={compMeta.displayName} />
    </PlasmicRootProvider>
  );
  return {
    props: {
      plasmicData,
      queryCache
      // ...
    },

    // Using incremental static regeneration, will invalidate this page
    // after 300s (no deploy webhooks needed)
    revalidate: 300
  };
};

// Render the page or component from Plasmic.
export default function MyPage(props: { plasmicData: ComponentRenderData; queryCache?: Record<string, any> }) {
  const router = useRouter();
  const compMeta = props.plasmicData.entryCompMetas[0];
  return (
    <PlasmicRootProvider
      loader={PLASMIC}
      prefetchedData={props.plasmicData}
      prefetchedQueryData={props.queryCache}
      pageParams={compMeta.params}
      pageQuery={router.query}
    >
      <PlasmicComponent component={compMeta.displayName} />
    </PlasmicRootProvider>
  );
}

Notes:

• You can skip getStaticProps to fetch dynamically at runtime.
• Use getServerSideProps instead of getStaticProps for SSR.
• Here we are using incremental static regeneration with getStaticProps, so no deploy webhooks needed.

Add the following to your plasmic-init.ts to register it:

plasmic-init.ts
Copy
import { HelloWorld } from './components/HelloWorld';

// ...

PLASMIC.registerComponent(HelloWorld, {
  name: 'HelloWorld',
  props: {
    verbose: 'boolean',
    children: 'slot'
  }
});

pages/plasmic-host.tsx
Copy
import * as React from 'react';
import { PlasmicCanvasHost } from '@plasmicapp/loader-nextjs';
import { PLASMIC } from '../plasmic-init';

export default function PlasmicHost() {
  return PLASMIC && <PlasmicCanvasHost />;
}

Shared layouts can be defined in pages/_app.js, called a custom app component. Here’s what you need to do:

1. Move <PlasmicRootProvider> from each page to _app.js,
2. In each page’s getStaticProps, fetch Plasmic data, including components used by the shared layout.
3. In _app.js, pass the Plasmic data to <PlasmicRootProvider>.

Example with NavHeader component:

pages/_app.tsx
Copy
import { PlasmicRootProvider } from '@plasmicapp/loader-nextjs';
import { PLASMIC } from '../plasmic-init';

export default function CustomApp({ Component, pageProps }) {
  return (
    // The data from each page's `getStaticProps` are in `pageProps`.
    <PlasmicRootProvider loader={PLASMIC} prefetchedData={pageProps.plasmicData}>
      <PlasmicComponent component="NavHeader" />
      <Component {...pageProps} />
    </PlasmicRootProvider>
  );
}

pages/some-page.tsx
Copy
import { useRouter } from 'next/router';
import { PageParamsProvider } from '@plasmicapp/loader-nextjs';
import { PLASMIC } from '../plasmic-init';

export function getStaticProps() {
  // Be sure to also fetch data for `NavHeader`
  const plasmicData = await PLASMIC.fetchComponentData('SomePage', 'NavHeader');
  return {
    props: {
      plasmicData
    }
  };
}

export default function SomePage() {
  const router = useRouter();
  // no need for <PlasmicRootProvider />
  return (
    <PageParamsProvider params={router.query} query={router.query}>
      <PlasmicComponent component="SomePage" />
    </PageParamsProvider>
  );
}