Novel

Novel is an open-source, headless rich-text editor for React that recreates Notion’s block-based writing experience out of the box: slash commands, a floating bubble menu, drag handles, and image uploads all ship as composable pieces rather than a monolithic widget. It wraps Tiptap and ProseMirror, adding an OpenAI/Vercel AI SDK-powered autocomplete extension so developers can drop AI-assisted writing into any React app without building the editor primitives from scratch.

The package is distributed as novel on npm and is the headless core extracted from the larger novel.sh monorepo (which also ships a Next.js demo app). Because every UI surface — the command palette, bubble menu items, image resizer — is exposed as an unstyled component or hook, teams can restyle the editor freely with Tailwind or any CSS approach while reusing Novel’s ProseMirror extensions and upload/AI plumbing.

What You Get

• EditorRoot / EditorContent components that wrap Tiptap’s EditorProvider with a Jotai store and a tunnel-based context for portaling command menus
• A slash-command extension (Command, createSuggestionItems, renderItems, handleCommandNavigation) for building a Notion-style / command palette
• Bubble menu primitives (EditorBubble, EditorBubbleItem) for selection-triggered floating toolbars
• Prebuilt Tiptap extensions: StarterKit, TiptapImage/UpdatedImage, TiptapLink, TaskItem/TaskList, HorizontalRule, Youtube, Twitter, Mathematics (KaTeX), MarkdownExtension, CharacterCount, and GlobalDragHandle
• AI-autocomplete building blocks (AIHighlight, addAIHighlight, removeAIHighlight) designed to pair with OpenAI or the Vercel AI SDK
• Image upload plumbing (createImageUpload, handleImageDrop, handleImagePaste, UploadImagesPlugin) for drag/drop/paste-to-upload workflows
• Utility helpers (getPrevText, getAllContent, isValidUrl, getUrlFromString) and shared Jotai atoms for cross-component editor state

Common Use Cases

• Adding a Notion-style block editor to a SaaS app’s notes, docs, or wiki feature
• Building an AI-assisted writing surface (blog editor, content tool) with inline autocomplete
• Embedding a rich-text editor with image upload, checklists, and embeds (YouTube, Twitter) into a custom CMS or admin panel
• Prototyping a Notion clone or collaborative document editor on top of React

Under The Hood

Architecture - Novel is the packages/headless workspace inside a pnpm/Turborepo monorepo (the sibling apps/web is just the novel.sh demo, not part of the published package). src/index.ts re-exports four layers: components (components/editor.tsx defines EditorRoot, which wraps children in a Jotai Provider plus a tunnel-rat context so the slash-command menu can portal its rendered output out of the DOM position where EditorCommand is mounted, and EditorContent, a thin forwardRef wrapper around Tiptap’s EditorProvider), extensions (ProseMirror/Tiptap extensions such as slash-command.tsx, ai-highlight.ts, mathematics.ts), plugins (upload-images.tsx, a ProseMirror plugin implementing drag/drop/paste-triggered uploads with placeholder/error decorations), and utils (Jotai atoms in store.ts/atoms.ts for cross-component editor state, plus plain helper functions). The design cleanly separates ‘editor shell’ (state/context) from ‘extension’ (behavior) from ‘plugin’ (low-level ProseMirror hooks), letting consumers opt into only the pieces they need.

Tech Stack - Built on @tiptap/core and @tiptap/react 2.11.x (itself a ProseMirror wrapper), with @tiptap/starter-kit and a long list of official Tiptap extensions (image, link, placeholder, task-list, underline, youtube, character-count) as dependencies. State is managed with jotai rather than React context/reducers for the command-menu and range atoms. UI-adjacent libraries include cmdk (command palette), tippy.js (popover positioning for the bubble/slash menus), react-moveable (image resize handles), katex (math rendering), and tiptap-markdown (Markdown serialization). The package is built with tsup to dual CJS/ESM output (dist/index.cjs / dist/index.js) and ships types via tsc; react is a peer dependency (>=18), keeping the published bundle lean.

Code Quality - The packages/headless workspace has no test files (*.test.*) — there is no automated test suite for the editor logic, so correctness relies on manual verification in the demo app and community bug reports via GitHub issues. Linting and formatting are enforced via Biome (biome.json, pnpm lint/pnpm format scripts) rather than ESLint/Prettier. TypeScript is used throughout with exported types (EditorInstance, JSONContent, SuggestionItem, UploadFn), and files are small and single-purpose (e.g. editor.tsx is 45 lines, utils/index.ts is 44 lines), which keeps individual units easy to audit even without test coverage.

API Design - The public surface favors composition: EditorRoot/EditorContent/EditorBubble/EditorCommand are meant to be nested as children rather than configured through one large props object, mirroring shadcn/Radix-style compound-component patterns. Extensions and plugins are exported as standalone values (StarterKit, TiptapImage, createImageUpload) so consumers assemble their own Tiptap extensions array instead of accepting a fixed bundle. This gives strong flexibility but pushes real setup cost onto the consumer — getting a working editor requires wiring several extensions, a Jotai provider, and (for AI features) a separate completion backend, so time-to-first-render is higher than a drop-in <Editor /> widget, offset by the official docs and demo app at novel.sh.