Quill — Administrator & Architecture Guide

This guide is the in‑depth technical reference for Quill 2.0.3: its architecture, internal model, module system, build and release pipeline, security considerations, and code‑level internals. It is written for developers integrating Quill at scale, architects evaluating it, and contributors working on the codebase itself.

Quill is not a deployed service — it is a browser library published to npm and a CDN, accompanied by a documentation website. "Operations" here therefore means building, testing, releasing, and embedding the library safely, rather than running a server.

Note

For day‑to‑day integration usage — installation, configuration options, the editor API, and recipes — see the companion User Guide. This guide assumes that material and goes deeper into how Quill works and how to operate it as a dependency.

1. Executive Summary

Quill is a modular, API‑driven rich text editor built on a structured document model rather than on contenteditable HTML soup. Three ideas define its architecture:

1. The document is a Delta. Content is a JSON op list (quill-delta), not HTML. This makes content lossless, diff‑able, transformable, and collaboration‑friendly.
2. The DOM is a tree of blots. Quill renders through Parchment, a document model that maps document nodes ("blots") to DOM nodes. Formats are blots or attributors registered in a shared registry.
3. Everything else is a module. The toolbar, keyboard handling, history, clipboard, uploader, tables, and syntax highlighting are all swappable modules layered onto a small core.

Important

The GitHub issue tracker for this snapshot shows active community concern about maintenance cadence and at least one open security advisory (CVE‑2025‑15056 / GHSA‑v3m3‑f69x‑jf25). Treat Quill as stable and widely deployed, but factor maintenance responsiveness and your own paste‑sanitization strategy into adoption decisions. See Security.

2. Architecture

2.1 High‑level component map

                         ┌──────────────────────────────────────┐
                         │              Quill (core)            │
                         │  public API · option expansion ·     │
                         │  static registry / import / register │
                         └───────────────┬──────────────────────┘
                                         │ orchestrates
   ┌──────────────┬───────────────┬──────┴───────┬──────────────┬───────────────┐
   ▼              ▼               ▼              ▼              ▼               ▼
┌────────┐   ┌─────────┐    ┌──────────┐   ┌───────────┐  ┌────────┐    ┌──────────┐
│ Editor │   │Selection│    │Composition│  │  Emitter  │  │ Theme  │    │ Modules  │
│ Delta  │   │ native  │    │  IME /    │  │ event bus │  │ snow / │    │ toolbar  │
│ sync   │   │ range   │    │ compose   │  │(eventemit-│  │ bubble │    │ keyboard │
│        │   │ bridge  │    │  events   │  │  ter3)    │  │ /core  │    │ history… │
└───┬────┘   └────┬────┘    └─────┬─────┘  └─────┬─────┘  └────────┘    └──────────┘
    │             │               │              │
    ▼             ▼               ▼              ▼
┌──────────────────────────────────────────────────────────┐
│                    Scroll (Parchment ScrollBlot)          │
│   the root blot — a tree of block/inline/embed/text blots │
│   mapped onto the contenteditable DOM (.ql-editor)        │
└──────────────────────────────────────────────────────────┘
                              │ renders
                              ▼
                ┌──────────────────────────────┐
                │  contenteditable DOM (.ql-…)  │
                └──────────────────────────────┘

2.2 The core objects

The Quill constructor wires up a fixed set of collaborators (packages/quill/src/core/quill.ts):

2.3 Construction sequence

When you call new Quill(container, options):

1. expandConfig() resolves the container selector, picks the theme constructor, merges Quill defaults + theme defaults + your options + per‑module defaults, and resolves the registry (custom registry > formats filter > shared global).
2. The container is cleared, marked .ql-container, and registered in a global WeakMap (core/instances.ts) keyed by DOM node.
3. A .ql-editor root is created and the Scroll blot is instantiated from the registry.
4. Editor, Selection, and Composition are constructed around the Scroll.
5. The theme is instantiated; it adds the default modules — keyboard, clipboard, history, uploader, plus input and uiNode — and any theme‑specific modules, then runs theme.init().
6. Event wiring connects Scroll updates back into the Editor's Delta sync and toggles the .ql-blank class.
7. If the container had initial HTML, it is converted through the clipboard and set as the initial contents; history is cleared; placeholder/readOnly are applied.

Note

The shared globalRegistry (a Parchment.Registry) is created once at module load. Because it is shared across all editor instances by default, registering a format with Quill.register affects every editor on the page unless you pass a per‑instance registry.

2.4 The Delta synchronization loop

The heart of Quill is keeping a canonical Delta in lockstep with a contenteditable DOM that the user (and the browser) mutate unpredictably.

user types / pastes / IME      API call (insertText, format, …)
        │                                │
        ▼                                ▼
  DOM mutation                    Editor.<method>()
        │                                │
   MutationObserver                 Scroll mutation
        │                                │
        ▼                                ▼
  Scroll.update() ──────► Emitter SCROLL_UPDATE ──► Editor.update()
        │                                                  │
        ▼                                                  ▼
  diff old vs. new Delta  ◄──────────────────────  new canonical delta
        │
        ▼
  TEXT_CHANGE (change, oldContents, source)  ──► your handlers

Editor.update() is the reconciliation point. It recomputes the document Delta from the blot tree, diffs it against the previous Delta, and emits the change. A fast path optimizes single‑character ASCII edits to avoid a full re‑diff.

3. The Document Model (Parchment & Delta)

3.1 Blots

Quill's content tree is made of blots (from Parchment). Each blot wraps a DOM node and declares a blotName, a tagName, and an optional className. Quill defines these core blots in packages/quill/src/blots/:

3.2 Formats

Formats are blots or attributors registered under formats/{name}. Quill ships these in packages/quill/src/formats/:

Formats come in three implementation shapes:

• Blot formats (e.g. bold, link, header) wrap content in a DOM element.
• Class attributors apply ql-{format}-{value} classes (used for things like alignment when class‑based).
• Style attributors apply inline CSS (e.g. color, background, size, font have style variants used during paste normalization).

Tip

Registering a format via Quill.register(BlotOrAttributor) infers the name from blotName/attrName and adds it under formats/{name}. Anything registered under blots/ or formats/ is also pushed into the global Parchment registry so the Scroll can build it.

3.3 Delta

quill-delta (re‑exported as Quill.import('delta')) provides the Delta class with insert/retain/delete ops, plus compose, diff, transform, and invert. These operations are what make:

• History work — undo entries are inverse Deltas (record() stores changeDelta.invert(oldDelta)).
• Collaboration possible — transform is operational transformation, letting concurrent edits be rebased.
• Tables/embeds composable — embed handlers (tableEmbed.ts) register custom compose/transform/invert logic with Delta.

4. The Module System

4.1 The Module base class

All modules extend the tiny base in core/module.ts:

abstract class Module<T extends {} = {}> {
  static DEFAULTS = {};
  constructor(public quill: Quill, protected options: Partial<T> = {}) {}
}

A module receives its host Quill instance and merged options. It wires up its behavior in the constructor (event listeners, key bindings, DOM hooks). Modules are added by the theme via theme.addModule(name), which looks the module class up from the registry (modules/{name}), merges Module.DEFAULTS with user options, and constructs it.

4.2 Built‑in modules and their defaults

4.3 Themes as module orchestrators

Themes (themes/snow.ts, themes/bubble.ts, base themes/base.ts) extend BaseTheme. Each:

• Supplies a default toolbar config if the toolbar module is enabled without a container.
• Builds toolbar buttons and pickers with the SVG icon set (ui/icons.ts, ui/picker.ts, ui/color-picker.ts, ui/icon-picker.ts).
• Wires a tooltip (ui/tooltip.ts) for link editing (snow) or selection‑anchored formatting (bubble).
• Adds a theme‑specific link handler (snow shows an inline edit tooltip; bubble opens the tooltip editor).

snow default toolbar:   [header 1/2/3] · [bold italic underline link] · [list ordered/bullet] · [clean]
bubble default toolbar: [bold italic link] · [header 1, header 2, blockquote]

5. Repository Structure

quill/                              (monorepo root — npm workspaces)
├── package.json                    workspace config; build/start/lint scripts
├── tsconfig.json
├── packages/
│   ├── quill/                      THE LIBRARY (published as `quill`)
│   │   ├── package.json            deps, webpack/vitest/playwright scripts
│   │   ├── webpack.config.cjs      build configuration
│   │   ├── webpack.common.cjs
│   │   ├── babel.config.cjs        preset-env + preset-typescript
│   │   ├── playwright.config.ts    e2e config
│   │   ├── scripts/build           build entry (`./scripts/build production`)
│   │   └── src/
│   │       ├── core.ts             full build entry (registers all formats/modules)
│   │       ├── quill.ts            re-export of core/quill
│   │       ├── core/               quill, editor, selection, emitter, composition,
│   │       │                       theme, module, logger, instances, utils/
│   │       ├── blots/              block, inline, text, break, cursor, embed,
│   │       │                       container, scroll
│   │       ├── formats/            21 format definitions
│   │       ├── modules/            clipboard, keyboard, history, toolbar, syntax,
│   │       │                       table, tableEmbed, uploader, input, uiNode,
│   │       │                       normalizeExternalHTML/
│   │       ├── themes/             base, snow, bubble
│   │       ├── ui/                 picker, color-picker, icon-picker, icons, tooltip
│   │       └── assets/             *.styl stylesheets + SVG icons
│   │       └── test/               unit/ (vitest), fuzz/ (vitest), e2e/ (playwright)
│   └── website/                    DOCS SITE (private, Next.js + MDX)
│       ├── next.config.mjs
│       ├── env.js
│       ├── content/                docs/*.mdx, blog/*.mdx, guides/*.mdx
│       └── src/                    pages/, components/, playground/, data/, svg/
└── scripts/                        changelog.mjs, release.js, utils/configGit.mjs

5.1 Build entries

• Full build (src/core.ts) imports and registers every standard format and module, plus both themes. This is what import 'quill' resolves to.
• Core build (quill/core) provides only the editor core; consumers register what they need.

Versioning is injected at build time: Quill.version reads a QUILL_VERSION global defined by babel-plugin-transform-define, falling back to 'dev'.

6. Building, Testing & Releasing

6.1 Prerequisites

npm install            # install all workspace deps from the repo root

6.2 Development servers

6.3 Building

The library build emits dist/quill.js, dist/quill.core.js, and the stylesheets quill.core.css, quill.snow.css, quill.bubble.css (compiled from the Stylus .styl assets), plus source maps.

6.4 Testing

Tip

The fuzz suite is the strongest correctness signal for the Delta/OT logic — it generates random operation sequences and checks that compose/transform/invert hold. Run it after any change to editor.ts, history.ts, or tableEmbed.ts.

6.5 Linting

npm run lint runs across all workspaces. The library lints with ESLint (TypeScript, import resolution, prettier, jsx‑a11y, require‑extensions) and tsc --noEmit for type checking. Prettier is configured for single quotes.

6.6 Release

Release tooling lives in scripts/:

The published artifact is the quill package (packages/quill), with main: quill.js, type module. The website is private ("private": true) and not published to npm — it is deployed separately as the documentation site at quilljs.com.

Important

The CDN (jsDelivr) serves the published npm package directly. Releasing a new version to npm makes it available at https://cdn.jsdelivr.net/npm/quill@<version>/dist/.... There is no separate CDN upload step — CDN currency is a function of the npm release.

7. Security Analysis

Quill edits a contenteditable surface and imports external HTML on paste, which puts it on the XSS attack surface of any application that embeds it. Understand the boundaries before deploying.

7.1 Trust boundaries

7.2 What Quill does and does not do

• Does: parse paste HTML in a detached DOMParser document, strip to a structured Delta via the matcher pipeline, normalize Word/Google‑Docs markup, and constrain content to registered formats (when you set formats/registry).
• Does not: act as a general‑purpose HTML sanitizer, validate URL schemes comprehensively, or protect a downstream renderer. Those are your responsibility.

Caution

Restrict allowed formats with the formats option and sanitize on render. The strongest defense against stored‑XSS is to (a) store Deltas, (b) constrain formats, and (c) sanitize/encode at the rendering boundary — not to rely on the editor alone.

7.3 Known issues from the community tracker

The issue tracker for this snapshot includes:

• CVE‑2025‑15056 / GHSA‑v3m3‑f69x‑jf25 (open) — a request for a patched version and maintainer guidance. Track upstream for remediation status before deploying in high‑risk contexts.
• getSemanticHTML correctness (#4509, open, heavily discussed) — semantic HTML export has edge cases; do not assume byte‑perfect output for complex documents (notably nested lists, #979/#4805).
• Accessibility gaps (#4439, #4806) — toolbar keyboard navigation and certain tooltip controls have reported a11y limitations relevant to compliance reviews.

Warning

Several open issues question maintenance responsiveness (#4622, #4800, #4803). For security‑sensitive deployments, plan for the possibility that you may need to carry local patches or contribute fixes upstream.

7.4 Secrets and network

Quill has no secrets, no network calls, and no telemetry of its own. It does not phone home. The only network considerations are (a) the CDN you load it from and (b) the default uploader, which converts dropped images to inline data URLs client‑side (no upload occurs unless you supply a handler).

8. Code Quality & Conventions

Note

The recurring @ts-expect-error // Fix me later comments are the clearest "tech debt" signal in the codebase — they mark spots where the type system and the DOM editing reality diverge. They are safe but worth tightening over time.

9. Integration & Operations Playbook

9.1 Embedding checklist

• [ ] Choose full vs. core build deliberately (bundle size vs. convenience).
• [ ] Include the theme stylesheet matching your theme option.
• [ ] Pin the version (npm quill@2.0.3 or a versioned CDN URL) — avoid floating @latest in production.
• [ ] Decide your storage format (store Deltas, not HTML).
• [ ] Constrain allowed formats to what your product needs.
• [ ] Define a sanitization strategy for any HTML you render from stored content.
• [ ] If using syntax, ensure highlight.js loads before Quill.
• [ ] Provide a real uploader.handler if you need server‑side image storage (the default inlines data URLs).

9.2 Performance tuning

9.3 Upgrading

Quill 2.x changed the document/registry model versus 1.x (the website's upgrading-to-2-0 guide covers specifics). When upgrading:

1. Review custom blots/formats against the Parchment 3 API.
2. Re‑validate any custom clipboard matchers.
3. Run your integration's e2e tests against the new build before shipping.

9.4 Diagnostics

Quill.debug('info'); // 'error' | 'warn' | 'log' | 'info' | true/false

Logging is namespaced (quill, quill:events, quill:selection, quill:clipboard, quill:keyboard, quill:toolbar). The default level is warn. Because Quill.debug is static, it affects every editor on the page.

Caution

Leaving debug at info/log in production is noisy and can leak document structure into the console. Keep it at warn (the default) in production builds.

10. Troubleshooting (Operational)

Build fails: TypeScript errors only with --skipLibCheck off

Cause. The library lints types with tsc --noEmit --skipLibCheck. Third‑party type mismatches can surface without skipLibCheck.

Solution. Match the project's lint command (lint:tsc) rather than a bespoke tsc invocation.

Website dev server shows the published Quill, not my local changes

Cause. The website only uses the local build when NEXT_PUBLIC_LOCAL_QUILL=true.

Solution. Use npm run start:website (which sets the flag) or npm start at the root, not a bare next dev.

Fuzz tests fail after editing Delta logic

Cause. A change to editor.ts, history.ts, or tableEmbed.ts broke an OT invariant (compose/transform/invert).

Solution. Treat fuzz failures as correctness regressions, not flakiness — the seed that failed encodes a concrete violating sequence. Reproduce and fix the invariant.

Cannot import {name}. Are you sure it was registered?

Cause. Quill.import(name) was called for a path never registered (common when mixing core build with full‑build assumptions).

Solution. Register the component first, or use the full build which registers all standard formats/modules.

Cannot load {name} module. Are you sure you registered it?

Cause. A module named in modules options isn't registered.

Solution. Register the module class under modules/{name} before construction, or remove the option.

Port conflict on dev start

Cause. The library dev server defaults to webpack port 9080 and the website to 9000 (from the root package.json config.ports).

Solution. Free the ports or override via the npm config port variables.

11. Quick Reference

Workspace scripts (root)

Library scripts (packages/quill)

Distribution artifacts (dist/)

Key environment / config values

Error message → meaning