@tiptap/core vs. prosemirror-state

@tiptap/core is a headless rich text editor framework built on top of ProseMirror, offering a comprehensive and opinionated API for developers to build sophisticated editing experiences. Its core philosophy revolves around providing a flexible, extensible, and modern toolkit that abstracts away much of the complexity of rich text editing, making it ideal for projects requiring highly customized UIs and advanced features. The primary audience for @tiptap/core includes front-end developers building content management systems, web applications with rich text input fields, or any project demanding a robust and feature-rich editor without being tied to a specific UI.

prosemirror-state, conversely, is a foundational piece of the ProseMirror toolkit, specifically focusing on managing the state of a ProseMirror editor. It provides the core data structures and logic for document content, selection, and history, acting as the central nervous system for any ProseMirror-based editor. Its philosophy is minimal and focused, aiming to offer the essential building blocks for state management rather than a complete editing solution. Developers who would reach for prosemirror-state are typically those building their own editor infrastructure from the ground up, leveraging ProseMirror's powerful core but needing fine-grained control over every aspect of the editing process.

The key architectural difference lies in their scope and abstraction level. @tiptap/core acts as a higher-level abstraction, composing and extending ProseMirror's core functionalities to offer a more developer-friendly API with built-in concepts like commands, extensions, and event handling. It aims to simplify the integration of ProseMirror into applications. prosemirror-state, on the other hand, is a lower-level module that exposes ProseMirror's fundamental state management primitives directly. This means working with @tiptap/core involves interacting with its own defined command system and extension API, while using prosemirror-state requires a deeper understanding of ProseMirror's internal state management mechanisms.

A second technical difference emerges in their extensibility models. @tiptap/core utilizes a structured extension system that allows developers to easily add new features, commands, marks, and nodes, often with pre-built extensions available within the Tiptap ecosystem. This promotes a modular approach to editor development. prosemirror-state, being a core component, is not inherently extensible in the same way; extensibility in a ProseMirror editor built directly with prosemirror-state comes from ProseMirror's own plugin system and the ability to define custom node types, mark types, and schema configurations, which requires a more direct manipulation of ProseMirror's core concepts.

Developer experience contrasts significantly due to their abstraction levels. @tiptap/core aims for a smoother onboarding experience with its well-defined API, comprehensive documentation, and a rich set of community extensions. It abstracts away many of ProseMirror's complexities, potentially leading to a faster development cycle for common editor features. prosemirror-state, while powerful, presents a steeper learning curve. Developers must engage directly with ProseMirror's core APIs, including schema design, transaction handling, and plugin development, demanding a deeper investment in understanding ProseMirror's underlying architecture before building any substantial functionality.

Performance and bundle size considerations also highlight their differences. prosemirror-state is a remarkably small and focused package, contributing minimally to the overall application bundle size. Its minimal footprint makes it an attractive choice for performance-critical applications or environments where every kilobyte counts, especially when building an editor from scratch where only essential state management is needed. @tiptap/core, while optimized, is a larger package due to its included abstractions, utility functions, and broader feature set. It bundles more logic and tooling, leading to a higher bundle size, though it remains highly efficient for its feature scope.

For practical recommendations, choose @tiptap/core when you need a fully-fledged rich text editor with a modern API and extensive customization capabilities, particularly for web applications requiring a rich content creation interface or a CMS. It's excellent for projects where rapid development of a feature-rich editor is a priority. Opt for prosemirror-state when you are building a highly bespoke editor from the ground up, need absolute control over the state management, or are integrating ProseMirror's core capabilities into a larger application where you intend to manage the editor's UI and behavior entirely yourself. It is the choice for maximum control and minimal dependencies.

Ecosystem and maintenance present distinct considerations. @tiptap/core benefits from a vibrant ecosystem of extensions and community support, offering a more complete out-of-the-box solution with a clear path for adding functionality. Its development is active and geared towards providing a modern, opinionated editor framework. prosemirror-state, being a core ProseMirror module, is part of a stable and well-established, albeit smaller, ecosystem. While its direct development activity might appear less frequent, its stability and foundational nature mean it's less prone to breaking changes, appealing to projects prioritizing long-term stability and deep integration with the ProseMirror architecture.

In terms of niche use cases, @tiptap/core excels in scenarios demanding seamless integration of rich text editing within complex UI frameworks like React or Vue, offering wrappers and helpers to streamline this. Its headless nature allows for complete UI freedom. prosemirror-state is indispensable for developers who need to build custom ProseMirror plugins or extend ProseMirror's core data structures in unconventional ways, or when creating a highly specialized document editor where the state management logic is tightly coupled with application-specific data models.