Welcome to BaseHub Docs. Throughout this site, you’ll find instructions on how to connect BaseHub to your website using our SDKs, and you’ll learn more about our platform and features.

Popular Sections

Jump straight into one of our most popular sections.

Next.js Integration

Get started with Next.js

API Reference

Know how our APIs work

Help

Have a specific question or support request? These are our support channels:

• X: https://x.com/basehub_ai

• Discord: https://discord.gg/6Gk4qfuqHK

• Help Center (live chat): https://basehub.com/help?chat=true

BaseHub has three main properties:

1. The Dashboard, basehub.com, where you create teams, repositories, collaborate on content, etc

2. The GraphQ: API, api.basehub.com, where you interact with your repository programmatically, either to query data in your repo, or to mutate data in your repo

3. The SDK, which you install and run within your website: pnpm i basehub

As you use BaseHub, you—or your team as a whole—will interact with all of these parts, and that’s why having a good understanding of the whole is important.

Creating a Block

Every piece of content you create in BaseHub is a Block. Similar to Lego, Blocks can have different types and functions. You can nest Blocks, reference Blocks, and more.

In the Editor, you’ll create Blocks by typing / and choosing one Block type from the Block selector.

Read more about Blocks in our Blocks Reference:

Committing

A Commit stores a snapshot of your Repo at that specific point in time. Inspired by Git, each commit is immutable, and it’s a core of how version control works in BaseHub.

Once you’re happy with your changes, you can create a Commit. The API will now use the latest commit (the Head Commit) to resolve your queries.

Exploring the GraphQL API

A great way to explore the GraphQL API is to use the Explorer. You can find it in the README:

Set Up basehub

Our official JavaScript/TypeScript library exposes a CLI generator that, when run, will generate a type-safe GraphQL client. Check out our API Reference for more information.

npm i basehub

pnpm i basehub

yarn add basehub

BASEHUB_TOKEN="<your-token>"

# Remember to also add this ^ env var in your deployment platform

"scripts": {
  "dev": "basehub dev & next dev",
  "build": "basehub && next build",
  "start": "next start",
  "lint": "next lint"
},

npm run dev

pnpm dev

yarn dev

Now, let’s go ahead and query some content!

Your First Query

The recommended way to query content from BaseHub is with <Pump />, a React Server Component that enables a Fast Refresh-like experience.

import { Pump } from "basehub/react-pump"
import { draftMode } from "next/headers"

const Page = () => {
  return (
    <Pump
      queries={[{ _sys: { id: true } }]}
      draft={draftMode().isEnabled}
      next={{ revalidate: 30 }}
    >
      {async ([data]) => {
        "use server"

        return (
          <pre>
            <code>{JSON.stringify(data, null, 2)}</code>
          </pre>
        )
      }}
    </Pump>
  )
}

export default Page

Notice we’re using Next.js’ draftMode and passing it down to Pump. You’ll learn more in the next section, but put briefly: 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.

When you run basehub, you’ll be generating a GraphQL Client. What’s unique about this GraphQL client is that you’ll be defining the queries within your .{js,ts} files, instead of within .graphql ones. Most importantly, the output of your queries will be fully type safe.

basehub()

This function let’s you fire off a single, direct query. Because of this, it’s perfect for querying content that you don’t need to render, like when defining generateStaticParams within a dynamic Next.js page.

import { basehub } from "basehub"

export const generateStaticParams = async () => {
  const { posts } = await basehub({ cache: "no-store" }).query({
    posts: { items: { _slug: true } },
  })

  return posts.items.map((p) => {
    return { slug: p._slug }
  })
}

<Pump />

Pump can subscribe to realtime changes from your dashboard, and re-compute the JSX so that you can have a Fast Refresh-like experience. Because of this, Pump is ideal for querying content that you’ll want to render—for example, titles, images, rich texts, etc.

import { Pump } from "basehub/react-pump"
import { draftMode } from "next/headers"

const Page = () => {
  return (
    <Pump
      queries={[{ _sys: { id: true } }]}
      draft={draftMode().isEnabled}
      next={{ revalidate: 30 }}
    >
      {async ([data]) => {
        "use server"

        return (
          <pre>
            <code>{JSON.stringify(data, null, 2)}</code>
          </pre>
        )
      }}
    </Pump>
  )
}

export default Page

With these two ways of querying in mind, let’s explore how to build our queries.

Anatomy of a Query

Queries are JavaScript objects, where each key represents a key in the GraphQL schema, and the value is a boolean which decides weather you want to retrieve that key or not. Let’s take this query as an example:

import { basehub } from "basehub"

basehub().query({
  _sys: {
    id: true,
  },
  homepage: {
    title: true,
  },
  posts: {
    items: {
      _id: true,
      _slug: true,
      _title: true,
      publishedAt: true,
    },
  },
})

This query above will return the following result:

query {
  _sys {
    id
  }
  homepage {
    title
  }
  posts {
    items {
      _id
      _slug
      _title
      publishedAt
    }
  }
}

type Result = {
  _sys: {
    id: string
  }
  homepage: {
    title: string
  }
  posts: {
    items: Array<{
      _id: string
      _slug: string
      _title: string
      publishedAt: string
    }>
  }
}

As you can see, GraphQL and TypeScript are not that different, and this is what our client is taking advantage of.

Passing arguments

You can pass down arguments with __args:

import { basehub } from "basehub"

basehub().query({
  posts: {
    __args: { 
      filter: { 
        _sys_slug: { eq: "my-post-slug" },
      },
    },
    items: {
      _id: true,
      _slug: true,
      _title: true,
      publishedAt: true,
    },
  },
})

Fragmenting

Fragments are very useful to define data dependencies inside your application. To define a fragment with our SDK, you’ll use fragmentOn:

import { basehub, fragmentOn } from "basehub"

export const PostFragment = fragmentOn("PostItem", {
  _id: true,
  _slug: true,
  _title: true,
  publishedAt: true,
})

// you can use it as a type as well
export type PostFragment = fragmentOn.infer<typeof PostFragment>

basehub().query({
  posts: {
    __args: {
      filter: {
        _sys_slug: { eq: "my-post-slug" },
      },
    },
    items: {
      _id: true,
      _slug: true,
      _title: true,
      publishedAt: true,
      ...PostFragment
    },
  },
})

Co-Locating Components with Their Data Dependency

A common pattern we enjoy using revolves around components defining thier own data dependencies. This works great with fragments, as we can easily define a fragment alongside a component and have it all be type safe.

// Let's imagine a Callout component:

import { fragmentOn } from ".basehub"
import { RichText } from ".basehub/react-rich-text"

export const CalloutFragment = fragmentOn("CalloutComponent", {
  _id: true,
  emoji: true,
  body: { json: { content: true } },
})

export const Callout = ({
  data,
}: {
  data: fragmentOn.infer<typeof CalloutFragment>
}) => {
  return (
    <div>
      <span>{data.emoji}</span>
      <RichText>{data.body.json.content}</RichText>
    </div>
  )
}

Then you could use this CalloutFragment paired with <Callout /> , all type safe and with the data dependency co-located. If you update your Callout component and require more data from BaseHub, you can update the fragment and you’ll instantly get the data coming via props.

Not Supported: Aliases

Aliases are a very useful GraphQL feature, which unfortunately is not currently supported. If you need this feature, contact us to help us prioritize.

The GraphQL API can return your Rich Text Blocks’ data in multiple formats:

1. Plain Text, will ignore all formatting, media, and custom components, easy to render.

2. HTML, will ignore custom components, easy to render.

3. Markdown, will ignore custom components, needs a markdown to HTML parser to render.

4. JSON, comes with everything, but needs something that understand and processes it.

In the case of the JSON format, the response will be an AST based on the TipTap editor spec. Because of the complexities associated with processing this JSON format, we’ve built a React Component called <RichText /> that will help us render our Rich Text content. This is how it works:

import { Pump } from "basehub/react-pump"
import { RichText } from "basehub/react-rich-text"

const Page = async () => {
  return (
    <Pump
      draft={draftMode().isEnabled}
      next={{ revalidate: 60 }}
      queries={[
        {
          homepage: {
            subtitle: { 
              json: { 
                content: true,
              },
            },
          },
        },
      ]}
    >
      {async ([{ homepage }]) => {
        "use server"
        return <RichText>{homepage.subtitle.json.content}</RichText>
      }}
    </Pump>
  )
}

export default Page

Component Overrides

When using the <RichText /> component, you can simply pass the JSON content into it via children, and it’ll get rendered. If you want to use a custom handler for a certain HTML node (imagine using Next.js’ <Image /> to render images), you’d use the components prop.

import { Pump } from "basehub/react-pump"
import { RichText } from "basehub/react-rich-text"
import Image from "next/image"

const Page = async () => {
  return (
    <Pump
      draft={draftMode().isEnabled}
      next={{ revalidate: 60 }}
      queries={[
        {
          homepage: {
            subtitle: {
              json: {
                content: true,
              },
            },
          },
        },
      ]}
    >
      {async ([{ homepage }]) => {
        "use server"
        return (
          <RichText
            components={{ 
              img: (props) => <Image {...props} />,
            }} 
          >
            {homepage.subtitle.json.content}
          </RichText>
        )
      }}
    </Pump>
  )
}

export default Page

Custom Components

If you are using Custom Blocks in your Rich Text, you’ll need to add them to your query, and pass them via the blocks prop. Then, you’ll be able to set up the custom renderers for them (in a type-safe manner, by the way):

import { Pump } from "basehub/react-pump"
import { RichText } from "basehub/react-rich-text"
import Image from "next/image"
import { Callout, CodeSnippet } from './path-to/components'

const Page = async () => {
  return (
    <Pump
      draft={draftMode().isEnabled}
      next={{ revalidate: 60 }}
      queries={[
        {
          homepage: {
            subtitle: {
              json: {
                content: true,
                blocks: { 
                  __typename: true,
                  on_CalloutComponent: { 
                    _id: true,
                    intent: true,
                    text: true,
                  },
                  on_CodeSnippetComponent: { 
                    _id: true,
                    code: { 
                      code: true,
                      language: true,
                    },
                    fileName: true,
                  },
                } 
              }
            },
          },
        },
      ]}
    >
      {async ([{ homepage }]) => {
        "use server"
        return (
          <RichText
            blocks={homepage.subtitle.json.blocks} 
            components={{
              img: (props) => <Image {...props} />,
              CalloutComponent: (props) => <Callout data={props}>,
              CodeSnippetComponent: (props) => <CodeSnippet data={props}>,
            }}
          >
            {homepage.subtitle.json.content}
          </RichText>
        )
      }}
    </Pump>
  )
}

export default Page

We hope this removes a bit of friction from the sill tough task of rendering Rich Text data.

Environments

Setting up your application so that it handles all of the environments in a seamless fashion is a very important part of integrating with BaseHub.

Local Environment

When developing in localhost, you’ll be writing new code and iterating over your content. This means adding new blocks, changing those blocks’ constraints, writing content and more—all at the same time.

In order to not break your flow, you’ll want two things:

1. For the schema in BaseHub to be in sync with your IDE, and

2. For the content to update as you write, without needing to commit it yet.

We bundled these two needs into one command:

basehub dev

This command generates the type-safe SDK and keeps it in sync with changes you make in basehub.com (this is called --watch mode); and also sets up the SDK so that it queries Draft content from your repository.

This is why we recommend you run it in parallel to next dev.

"scripts": {
  "dev": "basehub dev & next dev",
  "build": "basehub && next build",
  "start": "next start",
  "lint": "next lint"
},

Notice the single &.

Preview Environment

Setting up an easy way for editors to preview content before committing it into production is essential. We’ve designed our preview workflow with these three pillars in mind:

1. Content should render in real time, as you write.

2. Preview should be easy for developers to integrate.

3. The integration should never degrade production performance in any way.

We achieve this is by using a couple of BaseHub components, <Pump /> and <Toolbar />, in combination to Next.js’ draftMode. Additionally, to bridge the gap between basehub.com (the dashboard) and your website, you’ll need to set up the “Preview” Button.

This is how a simple code example can look like:

import { Toolbar } from 'basehub/next-toolbar'

export default function RootLayout({
  children,
}: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {/* Layout UI */}
        <main>{children}</main>
        <Toolbar />
      </body>
    </html>
  )
}

import { Pump } from "basehub/react-pump"
import { draftMode } from "next/headers"

const Page = () => {
  return (
    <Pump
      queries={[{ _sys: { id: true } }]}
      draft={draftMode().isEnabled} 
      next={{ revalidate: 30 }}
    >
      {async ([data]) => {
        "use server"

        return (
          <pre>
            <code>{JSON.stringify(data, null, 2)}</code>
          </pre>
        )
      }}
    </Pump>
  )
}

export default Page

Finally, we need to set up our Preview Buttons.

Production Environment

Once we’ve set up Local and Preview environments, most of the hard work is done. The only thing you need to make sure when going to production is for the SDK to be generated before the build step of your application.

"scripts": {
  "dev": "basehub dev & next dev",
  "build": "basehub && next build",
  "start": "next start",
  "lint": "next lint"
},

That should be it. You’re ready to deploy your website.

Caching

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.

This introduces a new task for the developer, which is to purge that cache when content from BaseHub changes. These are some of the options you have:

On-Demand Revalidation (Recommended)

The absolute best method of revalidation is “on-demand”. As its name implies, it consists of purging the cached data at the exact moment a change occurs. This provides the best experience for editors, as they won’t need to refresh the website for several seconds to see their content live; and also keeps server costs down, as the server itself won’t need to constantly check with our API to see if something has changed.

BaseHub provides automatic on-demand revalidation in a fine-grained manner.

• Automatic: without the need of constant developer setup.

• Fine-grained: with every query being revalidated individually—in contrast to an “all or nothing” approach.

This is how:

Mount the <Toolbar /> in layout.tsx1

This will add a Server Action to revalidate the specific tags basehub() will set to each query.

// app/layout.tsx
import { Toolbar } from "basehub/next-toolbar"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {/* Layout UI */}
        <main>{children}</main>
        <Toolbar />
      </body>
    </html>
  )
}

Fill in the Website URL input in BaseHub2

This will help our servers know where to go to to revalidate the queries.

Just use it3

That should be all! Make sure you don’t pass other cache-related props (such as revalidate or cache), as that will opt the query out of automatic on-demand revalidation.

As you may notice, we’re also not passing draftMode().isEnabled via props, as this is no longer required as of basehub@7.5.10—we now automatically infer draft mode for you.

import { Pump } from "basehub/react-pump"
import { basehub } from "basehub"

const Page = async () => {
  // works with basehub and with Pump
  const data = await basehub().query({ __typename: true })

  return (
    <Pump queries={[{ __typename: true }]}>
      {async ([data]) => {
        "use server"

        return <pre>{JSON.stringify(data, null, 2)}</pre>
      }}
    </Pump>
  )
}

export default Page

Time-Based Revalidation

Another conventional way to revalidate content is to use Next.js’ time-based revalidate caching option.

import { Pump } from "basehub/react-pump"

const Page = async () => {
  return (
    <Pump
      next={{ revalidate: 30 }} 
      queries={[{ __typename: true }]}
    >
      {async ([data]) => {
        "use server"
        // `data` will be stale after 30 seconds

        return <pre>{JSON.stringify(data, null, 2)}</pre>
      }}
    </Pump>
  )
}

export default Page

While this is very easy to set up, automatic on-demand revalidation is always better, as editors won’t need to refresh the website for several seconds to see their content live; will keep server costs down, as the server itself won’t need to constantly check with our API to see if something has changed; and will simply remove one task from developers’ hands.

BaseHub Search will help you create instant-search experiences ala Algolia inside your website. There are two steps into building an awesome search experience:

1. Indexing the content

2. Building the frontend

BaseHub helps you with both of these tasks.

Indexing the Content

BaseHub Search supports indexing blocks that are below Components. By default, blocks won’t be indexed. To index a block, you’ll go to over to its Properties Panel and click on the “Index block“ toggle.

Indexing Happens On Commit

In order for results to appear on your frontend, you’ll need to commit your changes. Toggling the “Index block” state is a “committable change.” Then, as you edit and add new content content, and commit, BaseHub Search will re-index and then your frontend will show the updated results.

Building the Frontend

There are a couple of ways in which BaseHub helps you build your search frontend. First, you’ll needit exposes a useSearch hook to make the queries and manage state. Second, it exposes a <SearchBox> component that provides good UX defaults for you to render your search input, your results, and your highlights.

In order for all of this to work, you’ll first need to get a _searchKey from the GraphQL API, which is scoped to a specific Collection or Component.

Let’s imagine you have a Posts Collection and you want to build a frontend so search through it.

import { Pump } from "basehub/react-pump"
import { draftMode } from "next/headers"

const Page = async () => {
  return (
    <Pump
      next={{ revalidate: 30 }}
      draft={draftMode().isEnabled}
      queries={[
        {
          posts: {
            _searchKey: true,
            items: {
              _id: true,
              _title: true,
              // more post stuff...
            },
          },
        },
      ]}
    >
      {async ([data]) => {
        "use server"
        return (
          <>
            <Search _searchKey={data.posts._searchKey} />
            ...
          </>
        )
      }}
    </Pump>
  )
}

export default Page

'use client'
import { useSearch, SearchBox } from "basehub/react-search"

export const Search = ({
  _searchKey,
}: {
  _searchKey: string
}) => {
  const search = useSearch({
    _searchKey,
    queryBy: ["_title", "body", "excerpt"],
  })

  return (
    <SearchBox.Root search={search}>
      <SearchBox.Input />

      <SearchBox.Placeholder>
        Start typing to search.
      </SearchBox.Placeholder>

      <SearchBox.Empty>
        Nothing found for <b>{search.query}</b>
      </SearchBox.Empty>

      <SearchBox.HitList>
        {search.result?.hits.map((hit) => {
          return (
            <SearchBox.HitItem
              key={hit._key}
              hit={hit}
              href={`/blog/${hit.document._slug}`}
            >
              <SearchBox.HitSnippet fieldPath="_title" />
              <SearchBox.HitSnippet
                fieldPath="body"
                fallbackFieldPaths={["excerpt"]}
              />
            </SearchBox.HitItem>
          )
        })}
      </SearchBox.HitList>
    </SearchBox.Root>
  )
}

Examples

1. Simple, non real-world example

   • GitHub Repo: https://github.com/basehub-ai/nextjs-simple-search-example

   • BaseHub Repo: https://basehub.com/basehub/simple-search-example

2. Advanced example (the search that powers these docs)

   • GitHub Repo: https://github.com/basehub-ai/nextjs-docs

   • BaseHub Repo: https://basehub.com/basehub/docs

BaseHub’s Event Block provides a powerful way to know more about how your content is performing. The unique thing about it is that Events that occur throughout your website can be tied directly to a Block—therefore keeping it in context.

The Event Block time-series can be used for tracking things like:

• Page views (internal and user facing)

• Button/Link Clicks

• Feedback forms

Or anything you want, really.

Set up an Event Block and start receiving events

First of all, you’ll need to add a new Event Block to your repo.

1. Create a new event block

2. Switch to Time-series layout

3. Commit your changes (not necessary if you’re working on draft mode)

4. Get your event’s ingestKey

Send an Event

In order to send an event, you’ll need to first get the ingestKey of an Event Block from the GraphQL API. Let's look at an example that tracks page views on the homepage. Once we get the page data and its ingestKey, we’ll import { sendEvent } from "basehub/events" and run it on mount:

import { Pump } from "basehub/react-pump"
import { draftMode } from "next/headers"

const Homepage = () => {
  return (
    <Pump
      next={{ revalidate: 30 }}
      draft={draftMode().isEnabled}
      queries={[
        {
          homepage: {
            _title: true,
            pageViews: {
              ingestKey: true,
            }
          },
        },
      ]}
    >
      {async ([{ homepage }]) => {
        "use server"

        return (
          <div>
            <PageView ingestKey={homepage.pageViews.ingestKey} />
            <h1>{homepage._title}</h1>
          </div>
        )
      }}
    </Pump>
  )
}

"use client"
import * as React from "react"
import type { PageViews as PageViewsType } from "~/.basehub/schema"
import { sendEvent } from "basehub/events"

export const PageView = ({
  ingestKey,
}: {
  ingestKey: PageViewsType['ingestKey']
}) => {

  // On mount, send the event
  React.useEffect(() => {
    sendEvent(ingestKey) 
  }, [])

  return <></>
}

Get an Event count

In case you want to show the Event Count in your website—for example, to render a “view count”—, well, you can! Following up from the <PageView /> component we built previously, we can update it so that it runs getEvents and renders it:

"use client"
import * as React from "react"
import type { PageViews as PageViewsType } from "~/.basehub/schema"
import { sendEvent, getEvents } from "basehub/events"

export const PageView = ({
  ingestKey,
  adminKey,
}: {
  ingestKey: PageViewsType["ingestKey"],
  adminKey: PageViewsType["adminKey"]
}) => {
  const [count, setCount] = React.useState() 

  // On mount, send the event
  React.useEffect(() => {
    sendEvent({ ingestKey, name: "page_view" })
  }, [])

  // We also get the event count so we can render it
  React.useEffect(() => { 
    getEvents(key, { 
      type: 'time-series',
      range: 'all-time'
    }).then( 
      (response) => { 
        if (response.success) { 
          setCount(response.data) 
        } 
      },
    ) 
  }, []) 

  return <div>Views: {count ?? "Loading..."}</div> 
}

Take our marketing website “Request a demo” page for example:

We can retrieve the fields from the schema and render them like this:

import { Button } from "@/common/button"
import {
  AuthLayout,
  RichTextFormWrapper,
  formWrapperFragment,
} from "../_components/auth-layout"
import { Pump } from "basehub/react-pump"
import { ArrowRightIcon } from "@radix-ui/react-icons"
import { BackToHomeButton } from "../_components/back-to-home-button"
import { DemoForm } from "./client-form"

export default function RequestDemo() {
  return (
    <Pump
      queries={[
        {
          site: {
            requestDemo: {
              wrapper: {
                title: true,
                subtitle: {
                  json: {
                    content: true,
                  },
                },
                cta: buttonFragment,
              },
              submissions: { 
                ingestKey: true,
                schema: true,
              },
            },
          },
        },
      ]}
    >
      {async ([{ site }]) => {
        "use server"

        return (
          <AuthLayout
            subtitle={
              site.requestDemo.wrapper.subtitle ? (
                <RichTextFormWrapper>
                  {
                    site.requestDemo.wrapper.subtitle.json
                      .content
                  }
                </RichTextFormWrapper>
              ) : null
            }
            title={site.requestDemo.wrapper.title}
          >
            <DemoForm
              ingestKey={site.requestDemo.submissions.ingestKey}
              schema={site.requestDemo.submissions.schema} 
            >
              <div className="mt-3 flex items-center justify-between">
                <Button
                  icon={<ArrowRightIcon className="size-5" />}
                  iconSide="right"
                  intent={site.requestDemo.wrapper.cta.type}
                  type="submit"
                >
                  {site.requestDemo.wrapper.cta.label}
                </Button>
                <BackToHomeButton />
              </div>
            </DemoForm>
          </AuthLayout>
        )
      }}
    </Pump>
  )
}

"use client"
import * as React from "react"
import { sendEvent } from "basehub/events"
import { LabeledInput } from "../_components/labeled-input"
import { Field } from "basehub/react-form"
import { LabeledTextarea } from "../_components/labeled-input"
import { Submissions } from ".basehub/schema"

export function DemoForm({
  children,
  ingestKey,
  schema,
}: {
  children: React.ReactNode
  ingestKey: Submissions["ingestKey"]
  schema: Field[]
}) {
  const handleSubmit = React.useCallback(
    async (e: React.FormEvent<HTMLFormElement>) => {
      e.preventDefault()
      const form = e.target as HTMLFormElement
      const formData = new FormData(form)

      await sendEvent(ingestKey, { 
        eMail: String(formData.get("eMail")),
        firstName: String(formData.get("firstName")),
        lastName: String(formData.get("lastName")),
        message: String(formData.get("message")),
      }) 
    },
    [ingestKey],
  )

  return (
    <form
      className="flex flex-col gap-3"
      onSubmit={handleSubmit}
    >
      {schema.map((field) =>
        field.name === "message" ? ( 
          <LabeledTextarea
            key={field.id} 
            minLength={16} 
            rows={8} 
            className="max-h-64 min-h-16"
            // The "Field" type comes with required, placeholder,
            // defaultValue and other useful props
            {...field} 
          />
        ) : ( 
          <LabeledInput key={field.id} {...field} /> 
        ),
      )}
      {children}
    </form>
  )
}

See the page live in our nextjs template.

See source code.

Workflows allow you to receive event notifications from BaseHub. BaseHub will send a POST request to a URL you specify when certain events happen in a BaseHub Repository.

Available events

• A commit happens. – This is a useful notification that can help you set up on-demand revalidation for your Next.js Apps, amongst other things.

• Collection Events: Row created, updated or deleted.

• New events in Event Block.

Workflow block

To configure webhooks, you’ll need to create a new Workflow block in your repo. There you can setup the URL that will be requested on new commits. Make sure to commit the block to make it effective.

Localization in BaseHub is enabled by the Variant Block.

Create the Variants Block1

Somewhere in the Editor, press “/variants” and add the block. Name it “Language“.

Add some langauges inside2

Add some variants for the languages you’ll support.

Enable the set on a Document or a Collection3

Take a look at this short video to see how we do it.

Query by variants on GraphQL4

After committing your changes, you will be able to apply variants arguments on the blocks that you enabled it, check it out:

{
  # from this point on, the schema will inherit the variant selected
  posts(variants: { language: es }) {
    items {
      _title
      excerpt
      coverImage {
        url
      }
      body {
        json {
          content
        }
      }
    }
  }
}

Full Example

• GitHub: https://github.com/basehub-ai/localized-blog

• BaseHub: https://basehub.com/basehub/localized-blog

• Demo: https://localized-blog-basehub.vercel.app/en

Astro is a framework for performant, content-driven websites. With it, you can use almost any UI library you want to (React, Vue, Svelte, etc).

Set Up basehub

Our official JavaScript/TypeScript library exposes a CLI generator that, when run, will generate a type-safe GraphQL client. Check out our API Reference for more information.

npm i basehub

pnpm i basehub

yarn add basehub

BASEHUB_TOKEN="<your-token>"

# Remember to also add this ^ env var in your deployment platform

"scripts": {
  "dev": "basehub dev & astro dev",
  "start": "basehub dev & astro dev",
  "build": "basehub && astro check && astro build",
  "preview": "astro preview",
  "astro": "astro"
},

npm run dev

pnpm dev

yarn dev

Your First Query

Now, let’s go ahead and query some content!

---
import { basehub } from 'basehub'

const data = await basehub({
	token: import.meta.env.BASEHUB_TOKEN
}).query({
	__typename: true,
	_sys: {
        id: true
	}
})
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
		<meta name="viewport" content="width=device-width" />
		<meta name="generator" content={Astro.generator} />
		<title>Astro</title>
	</head>
	<body>
		<pre><code>{JSON.stringify(data, null, 2)}</code></pre>
	</body>
</html>

Support Table

While you can query BaseHub content from Astro, there are some DX features that are not supported.

SvelteKit is a framework for rapidly developing robust, performant web applications using Svelte.

Set Up basehub

Our official JavaScript/TypeScript library exposes a CLI generator that, when run, will generate a type-safe GraphQL client. Check out our API Reference for more information.

npm i basehub

pnpm i basehub

yarn add basehub

BASEHUB_TOKEN="<your-token>"

# Remember to also add this ^ env var in your deployment platform

"scripts": {
  "dev": "basehub dev & vite dev",
  "build": "basehub && vite build",
  "preview": "vite preview",
  ... rest scripts
},

npm run dev

pnpm dev

yarn dev

Your First Query

Now, let’s go ahead and query some content!

import type { PageServerLoad } from "./$types"
import { basehub } from "basehub"
import { BASEHUB_TOKEN } from "$env/static/private"

export const load: PageServerLoad = async () => {
  const now = Date.now()
  const data = await basehub({ token: BASEHUB_TOKEN }).query({
    __typename: true,
    _sys: {
      id: true,
    },
  })
  return data
}

<script>
	/** @type {import('./$types').PageData} */
	export let data;
</script>

<pre><code>{JSON.stringify(data, null, 2)}</code></pre>

Support Table

While you can query BaseHub content from SvelteKit, there are some DX features that are not supported.

Generate

basehub generate

This command will get your BaseHub Token from your environment using dotenv-mono, use that to query the BaseHub API, and generate a type-safe SDK out of its schema.

Arguments

Aliases

Relevant Environment Variables

Dev

basehub dev

The dev command is very useful for local development. It basically runs basehub generate --watch --draft [...args] (notice how watch and draft mode are both being forced).

import { basehub } from 'basehub'

basehub().query({  })

When your token is setup, basehub.query() will query the data from the token’s repository. 

Inside the query object, you can pass any parameter that the Fetch API allows. That includes the Next.js revalidate parameters.

You can check out its usage in the GraphiQL Explorer linked to your schema.

Our <Pump/> component uses basehub.query() behind the scenes to retrieve the data, that’s way its props are so similar. The great advantage <Pump/> has it’s that it will stream your updates in real time while on draft mode.

Examples

Let’s see some common query patterns. Remember, the specific query keys you use will depend on your repository's structure, not on static API definitions.

Get a document block

basehub().query({
  homepage: {
    title: true,
    description: {
      json: { content: true },
    },
  },
})

Get a list of posts

basehub().query({
  posts: {
    items: {
      _id: true,
      _title: true,
      _slug: true,
      // more fields here...
    },
  },
})

Get the first item in a list

basehub().query({
  posts: {
    __args: { first: 1 },
    items: {
      _id: true,
      _title: true,
      _slug: true,
      // more fields here...
    },
  },
})

Filter by _slug

basehub().query({
  posts: {
    __args: {
      first: 1,
      filter: { _sys_slug: "your-post-slug" },
    },
    items: {
      _id: true,
      _title: true,
      _slug: true,
      // more fields here...
    },
  },
})

Order by created date

basehub().query({
  posts: {
    __args: {
      orderBy: "_sys_createdAt__DESC",
    },
    items: {
      _id: true,
      _title: true,
      _slug: true,
      // more fields here...
    },
  },
})

Create and use a fragment

import { basehub, fragmentOn } from "basehub"

const buttonFragment = fragmentOn("ButtonComponent", {
  label: true,
  href: true,
  variant: true,
})

basehub().query({
  homepage: {
    title: true,
    description: {
      json: { content: true },
    },
    cta: buttonFragment,
  },
})

Query a union

basehub().query({
  dynamicPages: {
    items: {
      pathname: true,
      sections: { 
        __typename: true, // required
        on_HeroSectionComponent: {          
          title: true,
          subtitle: true,
          // more fields
        },
        on_FeatureSectionComponent: {          
          title: true,
          subtitle: true,
          // more fields
        },
      },
    },
  },
})

import { basehub } from 'basehub'

basehub().mutation({  })

The basehub.mutation() lets you send GraphQL mutations to the BaseHub API using any JavaScript framework. This is useful for mutating data from your app into your BaseHub Repo.

You can check out its usage in the GraphiQL Explorer linked to your schema.

Methods

The mutation API works a bit different to the query API due to how GraphQL is designed. basehub().mutation() has other methods to add data into BaseHub, the most important one being transaction.

Example

Check out our Mutation API Playground for full examples.

• Playground.

• Source.

• Content.

Create

When running the create transaction, you will need to pass two additional parameters: parentId and data.

The parentId is the ID from the block where the creation will be done, could be any block, but that will affect which data structures are valid. In the example above, using that specific parentId we cannot insert anything apart from instances, because collection children are always instances (or a component that works as template).

The data field is the new block schema and values, including all its children.

Automatic Commit

The autoCommit is an optional field that accepts any string as the commit message that will be injected into the repository history. If not provided, the mutation updates will stay as work in progress (you will see them listed in your Changes Tab).

This method has the same signature as transaction. It’s very useful if you want to wait until the transaction is resolved to know for sure if it succeeded or failed.

Example

Check out our Mutation API Playground for full examples.

• Playground.

• Source.

• Content.

This is useful for example, when we have a PNG on our machine that we want to use in a BaseHub Image block. In order to use it, you should:

Example

On this example we’re uploading a new image file to BaseHub assets pool.

You can explore the full code for this example in Github.

export const uploadImageToBaseHub = async (imageInput: File) => {
  const { getUploadSignedURL } = await basehub().mutation({
    getUploadSignedURL: {
      __args: {
        fileName: imageInput.name,
      },
      signedURL: true,
      uploadURL: true,
    },
  });

  const uploadStatus = await fetch(getUploadSignedURL.signedURL, {
    method: "PUT",
    body: imageInput,
    headers: {
      "Content-Type": imageInput.type,
    },
  });

  if (uploadStatus.ok) {
    return getUploadSignedURL.uploadURL;
  }

  return null;
};

Example

You can explore the full code for this example in Github.

export async function getStatus(id: string) {
  const response = await basehub().mutation({
    transactionStatus: {
      __args: {
        id,
      },
    },
  });

  return response.transactionStatus;
}

import { Pump } from 'basehub/react-pump'

Pump is a React Server Component, meaning, it can only be used within frameworks that support RSC (Next.js only for now).

The power of Pump comes when you use Next.js Draft Mode alongside it. Pump lets developers write their queries and rendering logic in a simple and typesafe way, and get “content fast refresh” (live preview) out of the box, without affecting the website’s performance in any way.

Props

These are the props supported by <Pump /> .

Example

This query will get _sys.id from the API. Most importantly, when Next.js Draft Mode is enabled, it’ll subscribe to content changes in real time.

import { Pump } from "basehub/react-pump"
import { draftMode } from "next/headers"

const Page = () => {
  return (
    <Pump
      queries={[{ _sys: { id: true } }]}
      draft={draftMode().isEnabled}
      next={{ revalidate: 30 }}
    >
      {async ([data]) => {
        "use server"

        return (
          <pre>
            <code>{JSON.stringify(data, null, 2)}</code>
          </pre>
        )
      }}
    </Pump>
  )
}

export default Page

import { RichText } from 'basehub/react-rich-text'

A React Component that understands Rich Text Blocks’ data model and helps you render them in your website. If used in frameworks that support server components, it can be used as a RSC and just render the final result in the client without sending all the bundle to the client.

Props

These are the props supported by <RichText />

Example

import { Code, Heading, Link } from '@radix-ui/themes'
import NextLink from 'next/link'

export const ArticleBody = (props: ArticleFragment) => {
  return (
    <RichText
      content={props.content?.json.content}
      blocks={props.content?.json.blocks}
      components={{
        // native elements not present in this object will use the default handlers 
        h1: ({ children }) => (
          <Heading as="h1" size="3" weight="medium">
            {children}
          </Heading>
        ),
        h2: ({ children }) => (
          <Heading as="h2" size="2" weight="medium">
            {children}
          </Heading>
        ),
        h3: ({ children }) => (
          <Heading as="h3" size="2" weight="medium">
            {children}
          </Heading>
        ),
        a: ({ children, ...rest }) => (
          <Link asChild>
            <NextLink {...rest}>{children}</NextLink>
          </Link>
        ),
        // Custom component
        CodeSnippetComponent: ({ children, isInline }) => {
          if (!isInline) return null
          return <Code>{children}</Code>
        },
      }}
    />
  )
}

Styling

The <RichText /> component doesn’t come with styles. It's job is to render the html notes, but you'll need to add the styles yourself. This is intentional, as websites often vary a lot between typographies, colors, and sizes.

there are a couple ways to style a rich text:

1. Use regular CSS

2. Use the tailwindcss-typography plugin (recommended)

3. Override each of the nodes with your own components

Moreover, all of these methods can be combined as you please.

1. Just CSS

As an example:

.post-body > *:first-child {
  margin-top: 0;
}

.post-body > *:last-child {
  margin-bottom: 0;
}

.post-body p {
  margin-bottom: 1em;
}

.post-body h1 {
  font-size: 2em;
  margin: 1.5em 0 0.5em;
}

.post-body h2 {
  font-size: 1.8em;
  margin: 1.4em 0 0.4em;
}

.post-body h3 {
  font-size: 1.4em;
  margin: 1.3em 0 0.3em;
}

.post-body ul, 
.post-body ol {
  margin: 0 0 1em 1.5em;
}

.post-body li {
  margin-bottom: 0.5em;
}

.post-body img {
  max-width: 100%;
  height: auto;
  margin: 1em 0;
}

.post-body blockquote {
  border-left: 4px solid #ddd;
  padding-left: 1em;
  margin: 1em 0;
  font-style: italic;
  color: #666;
}

.post-body pre {
  background-color: #f4f4f4;
  padding: 1em;
  overflow-x: auto;
  margin: 1em 0;
}

.post-body code {
  background-color: #f4f4f4;
  padding: 0.2em 0.4em;
  border-radius: 3px;
}

import { RichText } from "basehub/react-rich-text"
import s from './post-body.module.css'

const PostBody = (props) => {
  return (
    <div className={s['post-body']}>
      <RichText {...props} />
    </div>
  )
}

2. With tailwind-typography (recommended)

Assuming you’re already using tailwind, using the typography plugin is fairly simple.

pnpm i @tailwindcss/typography --save-dev

Then in tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('@tailwindcss/typography'),
    // ...
  ],
}

And finally, you’ll use the prose class in the wrapping <div>

import { RichText } from "basehub/react-rich-text"

const PostBody = (props) => {
  return (
    <div className="prose">
      <RichText {...props} />
    </div>
  )
}

3. Overriding / Using your own design system

If you already have components to render quotes, headings, paragraphs, etc, you can easily use them like this:

import { RichText } from "basehub/react-rich-text"
import {
  Heading,
  Blockquote,
  Paragraph,
} from "@my-design-system"

const PostBody = (props) => {
  return (
    <div>
      <RichText
        {...props}
        components={{
          p: (props) => <Paragraph {...props} />,
          h1: (props) => <Heading {...props} level={1} />,
          h2: (props) => <Heading {...props} level={2} />,
          h3: (props) => <Heading {...props} level={3} />,
          blockquote: (props) => <Blockquote {...props} />,
          // rest...
        }}
      />
    </div>
  )
}

Example: https://github.com/basehub-ai/docs-template/blob/main/app/_components/article/index.tsx#L182

Custom Components

If you are using Custom Blocks in your Rich Text, you’ll need to add them to your query, and pass them via the blocks prop. Then, you’ll be able to set up the custom renderers for them (in a type-safe manner, by the way):

import { Pump } from "basehub/react-pump"
import { RichText } from "basehub/react-rich-text"
import Image from "next/image"
import { Callout, CodeSnippet } from './path-to/components'

const Page = async () => {
  return (
    <Pump
      draft={draftMode().isEnabled}
      next={{ revalidate: 60 }}
      queries={[
        {
          homepage: {
            subtitle: {
              json: {
                content: true,
                blocks: { 
                  __typename: true,
                  on_CalloutComponent: { 
                    _id: true,
                    intent: true,
                    text: true,
                  },
                  on_CodeSnippetComponent: { 
                    _id: true,
                    code: { 
                      code: true,
                      language: true,
                    },
                    fileName: true,
                  },
                } 
              }
            },
          },
        },
      ]}
    >
      {async ([{ homepage }]) => {
        "use server"
        return (
          <RichText
            blocks={homepage.subtitle.json.blocks} 
            components={{
              img: (props) => <Image {...props} />,
              CalloutComponent: (props) => <Callout data={props}>,
              CodeSnippetComponent: (props) => <CodeSnippet data={props}>,
            }}
          >
            {homepage.subtitle.json.content}
          </RichText>
        )
      }}
    </Pump>
  )
}

export default Page

import { CodeBlock } from 'basehub/react-code-block'

There are many syntax highlighting libraries in the JavaScript ecosystem. While this is a good thing, it can be exhausting for developers to shop for the right one. Prism, highlight.js, and Shiki are the most popular ones—an, in our opinion, Shiki is the best.

After building multiple websites with syntax highlighting, we’ve found ourselves copy-pasting a bunch of code and needing to re-read documentation over and over again. This is why we’ve built this.

Props

These are the props supported by <CodeBlock />

Basic Usage

import { CodeBlock } from 'basehub/react-code-block'

const Post = () => {
  return (
    <CodeBlock
      theme="github-dark"
      snippets={[{ code: `const hello = "world"`, lang: 'js' }]}
    />
  )
}

CSS Theme

import { CodeBlock } from 'basehub/react-code-block'

const Post = () => {
  return (
    <CodeBlock
      theme="github-dark"
      snippets={[{ code: `const hello = "world"`, lang: 'js' }]}
    />
  )
}

Examples

• From our docs: https://github.com/basehub-ai/docs-template/blob/main/app/_components/article/code-snippet/index.tsx#L21

• From the marketing website template: https://github.com/basehub-ai/marketing-website-template/blob/main/src/app/_components/code-snippet/index.tsx

import { useSearch } from 'basehub/react-search'

Arguments

Examples

• Documentation: Step by step

• Also you can check out our search implementation for this Documentation template on GitHub

import { SearchBox } from 'basehub/react-search'

// -> SearchBox.Root

Props

Examples

• Documentation: Step by step

• Also you can check out our search implementation for this Documentation template on Github

import { SearchBox } from 'basehub/react-search'

// -> SearchBox.Input

Props

The <SearchBox.Input /> extends the native HTMLInputProps.

Examples

• Documentation: Step by step

• Also you can check out our search implementation for this Documentation template on Github

<SearchBox.HitList /> Props

import { SearchBox } from 'basehub/react-search'

// -> SearchBox.HitList

<SearchBox.HitItem /> Props

import { SearchBox } from 'basehub/react-search'

// -> SearchBox.HitItem

The <SearchBox.HitItem /> extends the native HTMLDivProps.

<SearchBox.HitSnippet /> Props

import { SearchBox } from 'basehub/react-search'

// -> SearchBox.HitSnippet

The HitSnippet works as sugar syntax to render specific fields of the hit object with ease.

import { sendEvent } from 'basehub/events'

Parameters

Example

'use client'
// you'll need to run basehub before importing this type 👇🏼
import type { FeedbackEvents['ingestKey'] } from '~/.basehub/schema' 
import { sendEvent } from 'basehub/events'
import { Card, IconButton } from '@radix-ui/themes'
import { ThumbsDown, ThumbsUp } from 'lucide-react'
import * as React from 'react'

export const Feedback = ({
  ingestKey,
}: {
  ingestKey: FeedbackEvents['ingestKey']
}) => {
  const [sentFeedback, setSentFeedback] = React.useState<
    'positive' | 'negative' | null
  >(null)

  const handleFeedback = (type: 'positive' | 'negative') => {
    if (sentFeedback === type) return
    sendEvent(ingestKey, { positive: type === 'positive' }) 

    setSentFeedback(type)
  }

  return (
    <Card variant="classic" size="3">
      <IconButton onClick={() => handleFeedback('negative')}>
        <ThumbsDown fill={sentFeedback === 'negative' ? 'var(--accent-12)' : 'none'} />
      </IconButton>
      <IconButton onClick={() => handleFeedback('positive')}>
        <ThumbsUp fill={sentFeedback === 'positive' ? 'var(--accent-12)' : 'none'} />
      </IconButton>
    </Card>
  )
}

import { getEvents } from 'basehub/events'

Parameters