How slab/quill works
1. Repository shape
- This is a monorepo with two main runtime products: the Quill editor library in packages/quill and the documentation/playground website in packages/website.
- The root also contains release/changelog automation and GitHub Actions workflows, so the repo is both a library source and a published docs site.
2. Primary product boundary: packages/quill
- packages/quill is the distributable rich-text editor package published to npm and served via CDN.
- It is built from TypeScript/JavaScript source into browser-ready bundles using Babel/Webpack, with package-specific configs (babel.config.cjs, webpack*.cjs, playwright.config.ts).
3. Editor core architecture
- The editing engine is centered around src/core and src/core/quill.ts, which define the main Quill runtime and its coordination of selection, history, clipboard, keyboard, composition, theme, and module lifecycle.
- src/core/emitter.ts provides the event bus that links DOM/user events to editor state updates.
4. Document model and rendering layer
- src/blots contains the document abstraction layer: blocks, inlines, embeds, text, scroll, cursor, etc.
- These blots form the internal tree Quill uses to represent and manipulate content, separating the editor’s logical document model from raw DOM.
- src/formats defines the built-in formatting primitives (bold, list, link, image, table, etc.) that map editor operations onto blots and DOM attributes.
5. Module-driven behavior
- src/modules houses behavior subsystems that plug into the core editor: clipboard, history, keyboard, input, toolbar, syntax highlighting, uploader, table handling, and external-HTML normalization.
- normalizeExternalHTML is a distinct ingestion path for pasted content, with dedicated normalizers for Google Docs and MS Word, showing that paste/import is a first-class architecture boundary.
6. Theme, UI, and styling boundary
- src/themes, src/ui, and src/assets separate behavior from presentation.
- Themes (base, snow, bubble) assemble CSS/stylus assets and UI elements like tooltips, pickers, icon pickers, and color pickers.
- This keeps the editor logic reusable across different visual skins and runtime integrations.
7. Data flow inside the editor
- User input enters through browser events handled by modules like keyboard, input, clipboard, and composition.
- Those events are normalized into editor operations via the core/editor layer, which updates the document model, selection state, and history.
- The document model then drives DOM updates and UI changes, with selection/scroll helpers ensuring the visible editor stays synchronized.
8. Website and documentation app: packages/website
- The website is a separate Next.js app that serves docs, blog posts, and the interactive playground.
- Its content is largely MDX-based under content/docs and content/blog, with page routing and layout components in src/pages and src/components.
- This is a content-driven frontend, not part of the editor runtime itself.
9. Interactive playground subsystem
- packages/website/src/playground and src/pages/playground host runnable demos for editor configurations and custom examples.
- The site uses components like Sandpack, Editor, and playground layouts to render live code examples and Quill configurations.
- Static standalone demos under src/pages/standalone provide prebuilt editor variants such as snow, bubble, and stress cases.
10. Testing strategy
- packages/quill/test/unit covers editor internals, formats, modules, themes, UI, and utility functions with Vitest.
- packages/quill/test/e2e uses Playwright for browser-level interaction tests against a dedicated dev server fixture.
- packages/quill/test/fuzz adds randomized validation for editor/table behavior, and test/types checks TypeScript typing contracts.
11. Build, release, and automation
- GitHub Actions workflows handle test, changelog, release, labels, and pull-request automation.
- Root scripts/ plus package-local build scripts support changelog generation, release orchestration, and asset/build transforms such as SVG import inlining.
- This repo is optimized for publishing both the editor package and the documentation site as separate deliverables.
12. External-facing outputs
- The library is consumed as an npm package and via CDN bundles, with theme CSS as separate artifacts.
- The website is the public documentation and demo surface, while the package is the editor runtime distributed to application developers.
Main entry points: quill.ts Core runtime · modules Modules · pages Site pages · test Tests
Components 18
Repo root
Monorepo-wide release, workflows, and shared metadata
- Automation · GitHub Actions, changelog, and release orchestration for publishing and repo maintenance
scripts
Quill package
Distributable rich-text editor runtime and browser bundles
- Quill API · Top-level package entry points that expose the editor library to consumers
packages/quill/src/quill.ts - Core runtime · Main Quill runtime coordinating selection, history, clipboard, keyboard, composition, themes, and module lifecycle
packages/quill/src/core/quill.ts - Event bus · Core emitter linking DOM/user events to editor state updates
packages/quill/src/core/emitter.ts - Document model · Internal content tree for blocks, inlines, embeds, text, cursor, and scroll management
packages/quill/src/blots - Formats · Built-in formatting behaviors such as bold, lists, links, embeds, tables, and alignment
packages/quill/src/formats - Modules · Clipboard, history, keyboard, input, toolbar, syntax, tables, uploader, and HTML normalization
packages/quill/src/modules - Normalize HTML · First-class pasted-content normalization path with Google Docs and MS Word handlers
packages/quill/src/modules/normalizeExternalHTML - Themes · Base, snow, and bubble themes that assemble styling and UI chrome
packages/quill/src/themes - UI widgets · Tooltips, pickers, icon pickers, color pickers, and shared editor UI helpers
packages/quill/src/ui - Styles/assets · Stylus themes, icons, and shared visual assets for the editor package
packages/quill/src/assets - Tests · Unit, E2E, fuzz, and type tests covering editor internals and browser behavior
packages/quill/test - Build config · Babel, Webpack, Playwright, and package-local build scripts for browser bundles and validation
packages/quill/webpack.config.cjs
Website
Next.js docs, blog, and playground app
- Docs content · Docs and blog content that document APIs, usage, and product direction
packages/website/content - Site pages · Routing, layouts, and page shells for docs, blog, home, and standalone demos
packages/website/src/pages - Site UI · Reusable layout, MDX, SEO, editor, and playground components for the website
packages/website/src/components - Playground · Interactive editor examples and standalone variants used to exercise Quill configurations
packages/website/src/playground - Site data · Structured docs and playground metadata used to build navigation and content indexes
packages/website/src/data
Connections 22
- Automation → Build config: drives · Release and CI automation run package build and validation workflows
- Automation → Tests: runs · Automation executes tests before release and on pull requests
- Quill API → Core runtime: exposes · The public API instantiates and surfaces the core editor runtime
- Core runtime → Event bus: uses · Core runtime routes editor and DOM events through the emitter
- Core runtime → Document model: updates · Core operations mutate the document model and selection state
- Core runtime → Modules: orchestrates · Core runtime loads and coordinates behavior modules
- Core runtime → Themes: skins · Core editor can be paired with different visual themes
- Document model → Formats: renders via · Document nodes are shaped and annotated by format primitives
- Modules → Normalize HTML: ingests · Clipboard and paste flows delegate HTML normalization to dedicated handlers
- Modules → UI widgets: presents · Modules such as toolbar and syntax use shared UI widgets
- Themes → Styles/assets: bundles · Themes assemble stylus files and icon assets into runtime skins
- UI widgets → Styles/assets: consumes · UI widgets rely on shared icons and styling assets
- Tests → Core runtime: verifies · Unit and E2E tests cover editor runtime behavior
- Tests → Modules: verifies · Tests cover clipboard, history, keyboard, tables, and normalization modules
- Build config → Quill API: builds · Tooling compiles the package entry points into distributable bundles
- Site pages → Docs content: renders · Route handlers render MDX docs and blog content
- Site pages → Site UI: composes · Page shells are assembled from shared website components
- Site pages → Site data: navigates · Pages use structured data for docs and playground navigation
- Site UI → Playground: hosts · Playground components embed runnable Quill demos
- Site data → Docs content: indexes · Data definitions organize docs and API content into site navigation
- Playground → Quill API: embeds · Interactive demos instantiate the Quill library in multiple configurations
- Playground → Themes: demonstrates · Standalone demos showcase Quill theme variants and editor states