Next.js

Connecting BaseHub to Next.js is very simple. First of all, you’ll need to have the basehub SDK installed and configured. Refer to our guide to do so.

Fast Refresh with Pump

Pump is a React Server Component that enables a Fast Refresh-like experience for your content. When draft === true, Pump will subscribe to changes in real time from your Repo, and so keep your UI up-to-date. This is ideal for previewing content before pushing it to production. When draft === false, Pump will hit the Query API directly, without any production impact whatsoever. You can use it like this:

Pump receives the following props:

Querying Content Outside of JSX

While Pump works great for querying and rendering content in JSX, there are times when you need to query content outside of the context of a component. For example, in Next.js’ generateStaticParams, or in generateMetadata, or in any other place you need, you’ll want to use basehub() directly.

This is how you can do it:

Caching, and Revalidation

By default, Next.js will try to cache all of our requests made with fetch—and that includes BaseHub. While this makes subsequent requests to BaseHub much faster, it’ll essentially make your website’s content fully static, instead of reflecting the latest content changes from your BaseHub Repo.

Our recommendation is to use their time-based revalidate caching option, so that your data is cached and fast, but it also reacts to new content coming from BaseHub.

You can pass any fetch options that Next.js exposes, such as cache, and next to configure caching for your use case.

On-demand Revalidation

You can leverage BaseHub Webhooks and Next.js On-Demand Revalidation to update the cache of your Next.js Apps in a more fine-grained fashion. Instead of checking to see if something changed every n seconds, you can listen to the repo.commit event from BaseHub and use revalidateTag or revalidatePath to revalidate on demand.

Let’s set it up!

1. Set up API Endpoint that will revalidateTag

The BASEHUB_WEBHOOK_SECRET can be whatever you define it to be. Just make sure you pass it via the Authorization header. You can generate a random password using the 1Password generator.

2. Make sure your queries have the Cache Tag you want to revalidate

3. Create the Webhook

To do this final step, follow our guide on setting up Webhooks via the Webhook Portal.

Previewing Content

To set up a preview workflow with BaseHub and Next.js, you’ll need to first configure Draft Mode in Next.js. If you use Vercel, the Vercel Toolbar will come with Draft Mode already configured, which is great.

Using Pump (recommended)

To get draft content, we simply need to pass draft={true} to our Pump component. It’s recommended to do so conditionally, depending on the state of Next.js’ Draft Mode:

Using basehub().query()

If you’re using basehub() directly, you can also pass a draft param::

Example: Creating a Blog

Imagine you're creating a Blog. This would be a typical file structure:

app/
├── blog/
│   ├── page.tsx
│   └── [slug]/
│       └── page.tsx
next.config.js
package.json
... more files

This is how our app/blog/page.tsx could look like:

And then, our app/blog/[slug]/page.tsx could be something like the following:

Troubleshooting

“Error: type 'Query' does not have a field 'blogIndex' “

This error may pop up when using basehub or Pump sometimes, and it could be due to two reasons:

1. You altered your schema in BaseHub and didn’t run the generator again. Make sure to run basehub every time you alter your schema, so that we can re-infer it.

2. You already ran the generator, but Next.js cached the previous generated code in the .next directory (this is a directory Next.js uses to store compiled code while running the dev server). To fix this, just delete the .next directory and start your project again.

TypeScript not autocompleting after re-generating the schema

This gets fixed by restarting the TS server. In VSCode, you can do:

• Mac: Cmd + Shift + P + “Restart TS Server“

• Win: Ctrl + Shift + P + “Restart TS Server“