Contributing

Thank you for your interest in contributing to Stesura. This page covers how to get involved, what we expect from contributors, and the legal agreement that governs all contributions.

Contributor License Agreement

Before your first contribution can be accepted, you must agree to the Stesura Contributor License Agreement (CLA).

By submitting a pull request, opening an issue with a proposed patch, or otherwise contributing code, documentation, or other material to this project, you agree that:

Assignment of rights. You irrevocably assign and transfer to the company behind Stesura all right, title, and interest (including all intellectual property rights) in and to your contributions. This includes copyright, patent rights, and any other proprietary rights that may apply.
Original work. Your contribution is your original creation and you have the right to grant the above assignment.
No encumbrances. Your contribution does not violate any third-party license, agreement, or obligation.
Moral rights waiver. To the fullest extent permitted by applicable law, you waive any moral rights you may have in your contributions.

The company reserves the right to use, license, sublicense, modify, and distribute your contributions under any terms it chooses, including proprietary licenses.

If you are contributing on behalf of an employer or under a work-made-for-hire arrangement, you represent that you are authorised by your employer to make the assignment above on their behalf.

Getting Started

Prerequisites

Node.js 24.x
npm 11
Git

Fork and clone


git clone https://github.com/<your-fork>/stesura.git
cd stesura
npm i

(Upstream is github.com/stesura/stesura .)

Run the demo app


npm run dev:demo

Run the docs


npm run dev:docs

Build and test


npm run build
npm run test

Project structure


apps/
  blog/      – Blog site
  demo/      – Runnable examples (in-memory, IndexedDB, Pitter Patter)
  docs/      – This documentation site (Nextra / Next.js)
  sandbox/   – Scratch app for experiments
  testbed/   – Full-stack reference implementation (Supabase auth + collab backend)
  web/       – Marketing site
packages/
  core/                     – Schema, plugins, commands
  editor-react/             – StesuraEditor component, toolbar, menus, state hooks
  editor-react-ui/          – Low-level editor UI primitives
  collab-adapter(-react/-server/-local)/ – Collaboration transport
  pagination(-react)/       – Page-layout engine, header/footer editing panel
  references(-react)/       – Footnotes, endnotes and cross-references
  track-changes(-react)/    – Track-changes / suggestion mode
  comments(-react)/         – Adapter-driven comment threads
  proofread(-react)/        – Spell checking
  docx(-react)/             – DOCX import/export
  pdf-export-client/ pdf-export-server/ – PDF export
  ai/ ai-react/ ai-server/  – AI text actions, autocomplete, chat
  markdown/                 – Markdown parse/serialize
  i18n/                     – Translation strings
  icons/ fonts/             – Icon sets and bundled fonts
  profiler/                 – Dev-time performance collector
  ui/ marketing-ui/         – App-level design system / marketing chrome
  eslint-config/ typescript-config/ test-config/ – Shared configs

Making a contribution

Open an issue first for non-trivial changes so we can discuss the approach before you invest time coding.
Create a branch off the default branch: git checkout -b feat/my-feature.
Make your changes. Keep commits focused and write clear commit messages.
Add or update tests where relevant. All packages use Vitest; run npm run test from the repo root.
Run npm run lint and npm run typecheck and fix any failures.
Open a pull request with a description of what you changed and why.

Code style

TypeScript strict mode is on across all packages.
Formatting is enforced by the shared ESLint config (@stesura/eslint-config).
Do not add any casts without a comment explaining why.
New public APIs must be exported from the relevant package’s index.ts and documented here in the docs.

Reporting issues

Please use the GitHub issue tracker. Include:

A minimal reproducible example or a clear description of the steps to reproduce.
The browser and OS you are using.
The versions of the relevant @stesura/* packages.

Questions

For general questions about using the library, open a GitHub Discussion rather than an issue.