basehub-ai/basehub

SDK for BaseHub—Fast, Collaborative, AI-Native Content Management.

basehub 🪄

JavaScript / TypeScript SDK for BaseHub, the first AI-native content hub.

Features:

• ✨ Infers types from your BaseHub repository... meaning IDE autocompletion works great.
• 🏎️ No dependency on graphql... meaning your bundle is more lightweight.
• 🌐 Works everywhere fetch is supported... meaning you can use it anywhere.

Install

npm i basehub

Quickstart

1. Set required environment variable:

# .env

BASEHUB_URL="https://basehub.com/<team-slug>/<repo-slug>/graphql?token=<read-token>"

# or disambiguated

BASEHUB_TEAM="<team-slug>"
BASEHUB_REPO="<repo-slug>"
BASEHUB_TOKEN="<read-token>"

💡 Get your read token from the Connect panel: https://basehub.com/<team-slug>/<repo-slug>/connect

2. Generate client:

npx run basehub

❗️ Important: make sure you run the generator before your app's build step. A common pattern is to run it in your postinstall script.

3. Use in your app:

This example uses Next.js, but you can use any JavaScript framework.

// app/page.tsx

import { basehub } from "basehub";

const Page = async () => {
  const firstQuery = await basehub().query({
    __typename: true,
  });

  return <pre>{JSON.stringify(firstQuery, null, 2)}</pre>;
};

export default Page;

Choosing another output directory with --output

By default, basehub will generate the SDK inside node_modules/basehub/dist/generated-client. While this is a good default as it allows you to quickly get started, this approach modifies node_modules which, depending on your setup, might result in IDE or build pipeline issues. If this happens, please report the issue!

Additionally, you might want to connect to more than one BaseHub Repository.

To solve this, basehub supports an --output argument that specifies the directory in which the SDK will be generated. You then can use this directory to import generated stuff. For example: running basehub --output .basehub will generate the SDK in a new .basehub directory in the root of your project. You can then import { basehub } from '../<path>/.basehub' and use the SDK normally.

We recommend including the new --output directory to .gitignore, as these generated files are not precisely relevant to Git, but that's up to you and shouldn't affect the SDK's behavior.

About the SDK

The basehub sdk is generated with GenQL (read their docs). Thank you Morse for creating such a great package.

basehub's Issues

Try `postinstall` script to potentially save a step

Bundle generated code with `esbuild` + potentially ditch `tsup` and just use `esbuild`

Best way to add an `alt` attribute on images with RichText?

Hi! I’m trying to add an alt attribute to my blog posts images. I use the RichText component to display the content, but only information I receive is its URL, in the src attribute.

I defined my alt text by setting a caption on images (don’t know if it’s the best way, but I can’t find any other way). To set an alt attribute on images, I look in the body’s JSON for the image based on its src.

          <RichText
            components={{
              img: (props) => {
                const caption = post.body?.json.content.find(
                  (block: any) =>
                    block.type === 'image' && block.attrs?.src === props.src,
                )?.attrs?.caption
                // eslint-disable-next-line @next/next/no-img-element
                return <img {...props} alt={caption} />
              },
            }}
          >
            {post.body.json.content}
          </RichText>

(See in context)

Is there a better way to do that? Ideally, the caption should be returned in the image props, right? By the way, getting the image’s height and width too would be great to use Next.js’ Image component 😉 .

Make sure generation works in monorepos

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

Hi, I created my first blog post using the BaseHub blog template that was created during the setup, and committed my changes.

Then I followed the steps in the attached image, which works fine (returns "{ typename: 'Query' }" successfully).

But whenever I try to run:

const data = await basehub({ next: { revalidate: 30 }}).query({
    typename: true,
    blogIndex: {
      _id: true,
      blogPosts: {
        args: { first: 10, orderBy: 'publishDateDESC' },
        items: {
          _id: true,
          _title: true,
          _slug: true,
          subtitle: true,
          coverImage: { url: true },
          body: { json: true },
        },
      },
    }
  });

It keeps returning my this error (and I can't get my actual blog posts... What's wrong?

I already tried reinstalling - but it still doesn't work...

new `<CodeBlock />` react component

it's curretly way too hard to add a code snippet into your website. choosing the syntax highlighter is the worse.

I suggest: an Async Server Component which uses shikiji to highlight code, well integrated with BaseHub's API for code snippet blocks, and which exposes primitives (potentially ala radix, or ala our RichText) to:

• have line numbers
• have file names
• have "copy code" button
• highlight specific lines

RichText style is more fit for syntax highlighting because the code follows a strict order.

An initial api design could be something like this:

<CodeSnippet.Root language="" theme="" code={code}>
  <header>
     <p>filename.tsx</p>
     <CodeSnippet.CopyButton>Copy to clipboard</CodeSnippet.CopyButton>
  </header>
  <pre>
    <CodeSnippet.Highlighter components={{
      line: ({ children, number, isHighlighted }) => <span>{}</span>,
      token: ({ type, children, style }) => {
        // type can be "keyword", "string", "comment", etc... see how they do it in https://prismjs.com/
        return <span style={style}>{children}</span>
      }
    }} />
  </pre>

</CodeSnippet.Root>

<CodeSnippet.Highlighter>'s components are optional. If you set theme, they'll come with styles, and you're always free to add your own if you want.
you can do <CodeSnippet.Root language="" theme="" code={code} highlightedLines={[1, 4]} /> alone and it should work i guess. Meaning, if no children sent, will render default Highlighter.

🐛 bug: Error: ENOENT: no such file or directory Turborepo

npx envinfo --system --binaries 👇🏽

System:
    OS: macOS 14.2.1
    CPU: (20) x64 Intel(R) Core(TM) i9-10910 CPU @ 3.60GHz
    Memory: 80.64 GB / 128.00 GB
    Shell: 5.9 - /bin/zsh
 
 Binaries:
    Node: 20.11.1 - ~/.nvm/versions/node/v20.11.1/bin/node
    npm: 10.2.4 - ~/.nvm/versions/node/v20.11.1/bin/npm
    pnpm: 8.15.4 - ~/Library/pnpm/pnpm

apps/web/package.json 👇🏽

{
 "name": "@sambi/web",
 "version": "0.1.0",
 "private": true,
 "type": "module",
 "scripts": {
   "build": "pnpm with-env next build",
   "clean": "git clean -xdf .next .turbo node_modules",
   "dev": "pnpm with-env next dev",
   "format": "prettier --check . --ignore-path ../../.gitignore",
   "lint": "dotenv -v SKIP_ENV_VALIDATION=1 next lint",
   "start": "pnpm with-env next start",
   "typecheck": "tsc --noEmit",
   "with-env": "dotenv -e ../../.env --"
 },
 "dependencies": {
   "@headlessui/react": "^1.7.13",
   "@leafac/rehype-shiki": "^2.2.1",
   "@mdx-js/loader": "^3.0.0",
   "@mdx-js/react": "^3.0.0",
   "@next/mdx": "^14.0.4",
   "@sambi/api": "workspace:^0.1.0",
   "@sambi/auth": "workspace:^0.1.0",
   "@sambi/db": "workspace:^0.1.0",
   "@sambi/ui": "workspace:^0.1.0",
   "@sambi/validators": "workspace:^0.1.0",
   "@t3-oss/env-nextjs": "^0.9.2",
   "acorn": "^8.10.0",
   "acorn-jsx": "^5.3.2",
   "basehub": "^3.0.4",
   "escape-string-regexp": "^5.0.0",
   "fast-glob": "^3.2.12",
   "framer-motion": "^11.0.5",
   "next": "^14.1.0",
   "react": "18.2.0",
   "react-dom": "18.2.0",
   "recma-import-images": "0.0.3",
   "remark-gfm": "^4.0.0",
   "remark-unwrap-images": "^4.0.0",
   "shiki": "^0.11.1",
   "unified-conditional": "0.0.2",
   "zod": "^3.22.4"
 },
 "devDependencies": {
   "@sambi/eslint-config": "workspace:^0.2.0",
   "@sambi/prettier-config": "workspace:^0.1.0",
   "@sambi/tailwind-config": "workspace:^0.1.0",
   "@sambi/tsconfig": "workspace:^0.1.0",
   "@types/mdx": "^2.0.7",
   "@types/node": "^20.11.25",
   "@types/react": "^18.2.57",
   "@types/react-dom": "^18.2.19",
   "dotenv-cli": "^7.3.0",
   "eslint": "^8.57.0",
   "jiti": "^1.21.0",
   "prettier": "^3.2.5",
   "sharp": "0.33.1",
   "tailwindcss": "^3.4.1",
   "typescript": "^5.3.3"
 },
 "eslintConfig": {
   "root": true,
   "extends": [
     "@sambi/eslint-config/base",
     "@sambi/eslint-config/nextjs",
     "@sambi/eslint-config/react"
   ]
 },
 "prettier": "@sambi/prettier-config"
}

Apologies, didn't set up a reproduction repo for you. I'm trying to get Basehub installed on: https://github.com/sambi-dev/sambi
inside the apps/web workspace. Following the docs here: https://basehub.com/docs/api-reference/basehub-sdk

Current behavior:

• Run pnpm basehub or npx basehub from apps/web results in the following

srs@SAMBIMAC web % pnpm basehub
🪄 Generating...
✔ generating the client in `/Users/srs/GitHub/sambi/apps/web/node_modules/basehub/dist/generated-client`
Error: ENOENT: no such file or directory, scandir '/Users/srs/GitHub/sambi/apps/web/node_modules/basehub/src-react-pump'
   at Object.readdirSync (node:fs:1515:26)
   at copyDirSync (/Users/srs/GitHub/sambi/node_modules/basehub/dist/bin.js:274:38)
   at writeReactPump (/Users/srs/GitHub/sambi/node_modules/basehub/dist/bin.js:268:3)
   at /Users/srs/GitHub/sambi/node_modules/basehub/dist/bin.js:353:3
   at Generator.next (<anonymous>)
   at fulfilled (/Users/srs/GitHub/sambi/node_modules/basehub/dist/bin.js:47:24) {
 errno: -2,
 code: 'ENOENT',
 syscall: 'scandir',
 path: '/Users/srs/GitHub/sambi/apps/web/node_modules/basehub/src-react-pump'
}

Expected behavior:

• Run pnpm basehub or npx basehub from apps/web
• Client generated inside apps/web/node_modules and can be accessed as needed by basehub sdk
• I can get to work

Additional information:

• Just signed up for team plan today

review how we are loading env files (the order, priorities, and the ability to load from multiple files)

• we should mimic Next.js behavior