diff --git a/packages/website/docs/.vitepress/config.ts b/packages/website/docs/.vitepress/config.ts index 0c3b2c8cfb..507300e446 100644 --- a/packages/website/docs/.vitepress/config.ts +++ b/packages/website/docs/.vitepress/config.ts @@ -75,6 +75,7 @@ const SIDEBAR_DEFAULT = [ text: "Real-time collaboration", link: "/docs/real-time-collaboration", }, + { text: "Next.js", link: "/docs/nextjs" }, { text: "Without React (vanilla JS)", link: "/docs/vanilla-js", diff --git a/packages/website/docs/docs/nextjs.md b/packages/website/docs/docs/nextjs.md new file mode 100644 index 0000000000..7268df551b --- /dev/null +++ b/packages/website/docs/docs/nextjs.md @@ -0,0 +1,58 @@ +--- +title: Next.js and BlockNote +description: Details on integrating BlockNote with Next.js +imageTitle: Next.js and BlockNote +path: /docs/nextjs +--- + +# Next.js and BlockNote + +BlockNote is a component that should only be rendered client-side (and not on the server). If you're using Next.js, you need to make sure that Next.js does not try to render BlockNote as a server-side component. + +To do this, first see if you're using the modern [App router](https://nextjs.org/docs/app) or the classic [Pages router](https://nextjs.org/docs/pages). + +(If the component you want to add BlockNote to is in an `app` directory, you're likely to be using the App router. If you're working in a `pages` directory, you're using the pages router). + +## App router + +Make sure to use BlockNote in a [Client Component](https://nextjs.org/docs/getting-started/react-essentials#client-components). You can do this by creating a separate file for your component, and starting that with `"use client";` [directive](https://react.dev/reference/react/use-client). + +```typescript +"use client"; // this registers as a Client Component +import { BlockNoteEditor } from "@blocknote/core"; +import { BlockNoteView, useBlockNote } from "@blocknote/react"; +import "@blocknote/core/style.css"; + +// Our component that we can now use +export default Editor() { + // Creates a new editor instance. + const editor: BlockNoteEditor | null = useBlockNote({}); + + // Renders the editor instance using a React component. + return ; +} +``` + +## Pages router + +If you're using the classic Pages router (note that Next.js recommends upgrading to the App router) and are running into issues embedding BlockNote directly, you can use [Dynamic Imports](https://nextjs.org/docs/pages/building-your-application/optimizing/lazy-loading) to make sure BlockNote is only imported on the client-side. + +First, create an isolated `` component using the snipped above. + +Then, you can import this using `next/dynamic` in your page: + +```typescript +import dynamic from "next/dynamic"; + +const Editor = dynamic(() => import("./editor"), { ssr: false }); + +function App() { + return ( +
+ +
+ ); +} +``` + +This should resolve any issues you might run into when embedding BlockNote in your Next.js React app! diff --git a/packages/website/docs/docs/quickstart.md b/packages/website/docs/docs/quickstart.md index d448dfc20e..f4e78adc7f 100644 --- a/packages/website/docs/docs/quickstart.md +++ b/packages/website/docs/docs/quickstart.md @@ -46,6 +46,10 @@ function App() { As well as `BlockNoteView` and `useBlockNote`, we import `@blocknote/core/style.css` to provide default styling for the editor. +::: warning Next.js usage (or other server-side React frameworks) +Are you using Next.js (`create-next-app`)? Because BlockNote is a client-only component, make sure to disable server-side rendering of BlockNote. [Read our guide on setting up Next.js + BlockNote](/docs/nextjs) +::: + ## Demo: Basic App Using BlockNote Taking the same code, the live preview below turns it into a super simple, working app: