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:
Key | Type | Description |
---|---|---|
|
| An array of queries, which will be run in parallel. |
|
| Tells Pump to query the Draft API, plus subscribe changes in real time. |
|
| A render function which receives the results of the queries. When |
|
| Pump will infer your |
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:
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.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“