Merge pull request #380 from shishantbiswas/next-docs

add (docs): section for production build issue, React SDK setup
add(docs): update next.js docs to use colocation for <Admin /> component
2026-08-02 08:06:00 +00:00 · 2026-03-28 06:06:29 -05:00 · 2026-03-28 15:31:43 +05:30 · 2026-03-28 14:55:38 +05:30
3 changed files with 85 additions and 18 deletions
@@ -16,11 +16,6 @@ export type BkndAdminConfig = {
    * @default `/`
    */
   basepath?: string;
-   /**
-    * Sub-path for the Admin UI within the base path
-    * @default ``
-    */
-   admin_basepath?: string;
   /**
    * Path to return to when clicking the logo
    * @default `/`
@@ -101,7 +101,7 @@ export function useNavigate() {
               }
            }

-            const _url = options?.absolute ? `~/${app.options.basepath}/${app.options.admin_basepath}${url}`.replace(/\/+/g, "/") : url;
+            const _url = options?.absolute ? `~/${basepath}${url}`.replace(/\/+/g, "/") : url;
            const state = {
               ...options?.state,
               referrer: location,
@@ -71,7 +71,7 @@ export type NextjsBkndConfig<Env = NextjsEnv> = FrameworkBkndConfig<Env> & {

 ## Serve the API

-Create a helper file to instantiate the bknd instance and retrieve the API, importing the configurationfrom the `bknd.config.ts` file:
+Create a helper file to instantiate the bknd instance and retrieve the API, importing the configuration from the `bknd.config.ts` file:

 ```ts title="src/bknd.ts"
 import {
@@ -127,31 +127,80 @@ export const DELETE = handler;
 ```

 ## Enabling the Admin UI
+Create a file at `admin/[[...admin]]/page.client.tsx`:
+
+``` tsx title="admin/[[...admin]]/page.client.tsx"
+"use client";
+import dynamic from "next/dynamic";
+
+export const Admin = dynamic(async () => (await import("bknd/ui")).Admin, {
+  ssr: false,
+});
+```
+<Callout type="info">
+  We are using [Colocation](https://nextjs.org/docs/app/getting-started/project-structure#colocation) to prevent server-side hydration error, and the dynamic function to load Admin component only on client side.
+</Callout>
+

 Create a page at `admin/[[...admin]]/page.tsx`:
-
 ```tsx title="admin/[[...admin]]/page.tsx"
-import { Admin } from "bknd/ui";
 import { getApi } from "@/bknd";
 import "bknd/dist/styles.css";
+import { Admin } from "./page.client";
+import { Suspense } from "react";
+import { redirect } from "next/navigation";

 export default async function AdminPage() {
  // make sure to verify auth using headers
  const api = await getApi({ verify: true });

+  // early return if not logged in
+  if (!api.getUser()) {
+    return redirect("/unauthorized");
+  }
+
  return (
-    <Admin
-      withProvider={{ user: api.getUser() }}
-      config={{
-        basepath: "/admin",
-        logo_return_path: "/../",
-        theme: "system",
-      }}
-    />
+    <Suspense>
+      <Admin
+        withProvider={{ user: api.getUser() }}
+        config={{
+          basepath: "/admin",
+          logo_return_path: "/../",
+          theme: "system",
+        }}
+      />
+    </Suspense>
  );
-}
+};
 ```

+## React SDK configuration
+
+To use queries and mutation on client side, bknd provides first class support for it with it's [React SDK](/usage/react) 
+to set it up with Next.js add the `ClientProvider` to your root layout
+
+
+```tsx title="app/layout.tsx"
+import { ClientProvider } from "bknd/client";
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body>
+        <ClientProvider>
+          {children}
+        </ClientProvider>
+      </body>
+    </html>
+  );
+};
+```
+
+
 ## Example usage of the API

 You can use the `getApi` helper function we've already set up to fetch and mutate in static pages and server components:
@@ -172,3 +221,26 @@ export default async function Home() {
  );
 }
 ```
+
+## Note for Production
+If your admin component is not rendering and has a error like `Identifier 'b' has already been declared`, you will need to add these lines to your `next.config.(mjs|ts)` file:
+
+```ts
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // ...
+  // for turbopack 
+  experimental: {
+    turbopackMinify: false,
+  },
+
+  // for webpack
+  // webpack: (config) => {
+  //   config.optimization.minimize = false;
+  //   return config;
+  // },
+};
+
+export default nextConfig;
+```
Author	SHA1	Message	Date
Cameron Pak	8c596781ff	Merge pull request #380 from shishantbiswas/next-docs add (docs): section for production build issue, React SDK setup	2026-03-28 06:06:29 -05:00
shishantbiswas	43cbdb3010	add(docs): update next.js docs to use colocation for `<Admin />` component	2026-03-28 15:31:43 +05:30
shishantbiswas	b3c9f258de	add: prod section at the end	2026-03-28 14:55:38 +05:30