mirror of
https://github.com/outline/outline.git
synced 2026-11-20 21:23:06 +03:00
Co-authored-by: linear-code[bot] <222613912+linear-code[bot]@users.noreply.github.com>
12 KiB
12 KiB
Outline is a fast, collaborative knowledge base built for teams. It's built with React and TypeScript in both frontend and backend, uses a real-time collaboration engine, and is designed for excellent performance and user experience. The backend is a Koa server with an RPC API and uses PostgreSQL and Redis. The application can be self-hosted or used as a cloud service.
There is a web client which is fully responsive and works on mobile devices.
Monorepo Structure:
app/- React web application with MobX state managementserver/- Koa API server with Sequelize ORM and background workersshared/- Shared TypeScript types, utilities, and editor componentsplugins/- Plugin system for extending functionalitypublic/- Static assets served directly- Various config files - TypeScript, Vite, Vitest, oxfmt, Oxlint configurations
Refer to /docs/ARCHITECTURE.md for detailed architecture documentation.
Instructions
You're an expert in the following areas:
- TypeScript
- React and React Router
- MobX and MobX-React
- Node.js and Koa
- Sequelize ORM
- PostgreSQL
- Redis
- HTML, CSS and Styled Components
- Prosemirror (rich text editor)
- WebSockets and real-time collaboration
General Guidelines
- Critical – Do not create new markdown (.md) files.
- Use early returns for readability.
- Leave an empty line above every comment, unless the comment is the first line in a block.
- Emphasize type safety and static analysis.
- Follow consistent oxfmt formatting.
- Do not replace smart quotes ("") or ('') with simple quotes ("").
- Do not add translation strings manually; they will be extracted automatically from the codebase.
- UI strings use US English and full grammar. Do not join two sentences with a comma.
Dependencies and Upgrading
- Use yarn for all dependency management.
- After updating dependency versions, install to update lockfiles:
yarn install
- When adding a
resolutionsentry to address a security advisory in a transitive dependency, target only the specific vulnerable descriptors using thename@npm:<range>syntax rather than overriding the package globally. Inspectyarn.lockto find the exact ranges requested by upstream packages and add one entry per vulnerable range, e.g.:
"resolutions": {
"qs@npm:^6.5.2": "^6.14.2",
"qs@npm:^6.11.0": "^6.14.2",
"qs@npm:^6.14.0": "^6.14.2"
}
This keeps overrides scoped to the affected dependents and avoids forcing unrelated consumers onto an incompatible version.
TypeScript Usage
- Use strict mode.
- Avoid "unknown" unless absolutely necessary.
- Never use "any".
- Prefer type definitions; avoid type assertions (as, !).
- Always use curly braces for if statements.
- Avoid # for private properties.
- Prefer interface over type for object shapes.
Classes & Code Organization
Class Member Order
- Public static variables
- Public static methods
- Public variables
- Public methods
- Protected variables & methods
- Private variables & methods
Exports
- Exported members must appear at the top of the file.
- Always use named exports for new components & classes.
- Document ALL public/exported functions with JSDoc.
React Usage
- Use functional components with hooks.
- Event handlers should be prefixed with "handle", like "handleClick" for onClick.
- Avoid unnecessary re-renders by using React.memo, useMemo, and useCallback appropriately.
- Use descriptive prop types with TypeScript interfaces.
- Do not import React unless it is used directly.
- Use styled-components for component styling.
- Ensure high accessibility (a11y) standards using ARIA roles and semantic HTML.
- In components that stay mounted across navigation (layout, sidebar, command bar), do not use
useLocation. UseuseLocationSelectorto select only the value you need, or readhistory.locationin effects and handlers. - Give stable props to memoized and
observercomponents, especially list rows. Do not create new arrays, objects, or JSX on each render; use shared constants for empty arrays. - Do not read
ref.currentduring render to pass it to props or context. Keep the element in state with a callback ref. - If the initial value of
useStatereads observables, use a lazy initializer. Otherwise the expression runs, and subscribes, on every render.
MobX State Management
- Use MobX stores for global state management.
- Keep stores in
app/stores/. - Use
observable,action, andcomputeddecorators appropriately. - Prefer computed values over manual calculations in render.
- Keep business logic in stores, not components.
- Do not read an observable during render only for an effect or a per-item check. Use
useComputedto derive a narrow value (e.g.isActive) so only affected components re-render. - Use
observable.maprather than a set when observers check membership by key.ObservableSet.has()tracks the whole set, so any change re-renders every observer. - Store lookups called for each row of a list must not scan a computed list such as
orderedData, as this subscribes the component to every item in the store. - A context value provided near the app root must not change on navigation. Expose frequently changing store values as getters read on access, not values read during render.
- For client model/store fetch deduplication, use
CoalescedFetchorKeyedCoalescedFetchinstead of anisFetchingearly return. A forced call during a request must await a follow-up request after it settles, even if it fails; unforced callers must await the in-flight result.
Database & ORM
- Use Sequelize models in
server/models/. - Generate migrations with Sequelize CLI:
yarn sequelize migration:create --name=add-field-to-table
- Run migrations with
yarn db:migrate. - Use transactions for multi-table operations.
- Add appropriate indexes for query performance.
- Always handle database errors gracefully.
- When updating Sequelize array or JSON attributes, replace the value instead of mutating it in place; reload the model in tests to verify persistence rather than trusting its in-memory state.
- Schedule optional background work that depends on a transaction from
afterCommit, and use non-fatal scheduling so a queue failure does not fail the committed operation. - When changing persisted task input fields, keep readers compatible with queued inputs or migrate them before removing old fields.
- For row locks used only for non-key updates or soft deletes, use
LOCK.NO_KEY_UPDATEand setlock.ofto the target model when includes or scopes add joins. Verify with separate transactions that foreign-key inserts and locks on unrelated joined rows do not block the operation, while competing writers to the target still wait for commit. - In import task completion and failure handlers, reload the import under a row lock in the transaction before changing its state. Preserve
ProcessedandImport.terminalStatesoutcomes, and never mark a completed task errored. Test cancellation committed while a task runs and late failure callbacks, then reload the import and task to verify their states.
API Design
- RESTful endpoints under
/api/. - Authentication endpoints under
/auth/. - Use consistent error responses.
- Validate request data using the validation middleware and schemas
- Use presenters to format API responses.
- Keep API routes thin, use model methods for business logic, or commands if logic spans multiple models.
Authentication & Authorization
- JWT tokens for authentication.
- Policies in
server/policies/for authorization. - Use cancan-style ability checks.
- Use authenticated middleware for protected routes.
- Always verify user permissions before data access.
- When linking accounts by provider email, use exact case-insensitive equality within the workspace.
- Set account email and passkey management routes to
AuthenticationType.APP; API-key authentication must not change login credentials or authenticators. - For passkey registration and sign-in verification, consume the stored challenge atomically with Redis
GETDELbefore verification; do not read it and delete only after success. Verify that a failed attempt consumes the challenge and concurrent attempts cannot both retrieve it.
Real-time Collaboration
- WebSocket connections for real-time updates.
- Use Y.js for collaborative editing.
- Handle connection state changes gracefully.
- For bulk deletions that drive authorization or WebSocket processing, load affected models in the transaction and delete each with request context so downstream processors receive the expected per-item events.
- Do not persist viewer-specific unfurls in shared document mentions; only store unfurls that map to a stable mention type.
- When persisting pasted attachment URLs, use
signedUrlToAttachmentUrlto convert this instance’s signed URLs to stable attachment redirects. Cover HTML, Markdown, and single-URL pastes, including pasting over selected text; document nodes and link marks must not retain expiring local URLs, and external URLs must remain unchanged. - Editor plugins that repair the document (assigning missing IDs, fixing invalid structure) must use
RepairPluginfromshared/editor/plugins/RepairPlugin.ts. Other plugins that change the document inappendTransactionmust only respond to local changes, guard withisLocalDocChangefromshared/editor/lib/multiplayer.ts. Otherwise every connected client writes the change in response to remote edits and is attributed as an editor. - When changing block-node Markdown serializers, write a leading blank line separately from the block opener so list indentation and blockquote prefixes apply to the opener. Verify parse/serialize/parse structural equality inside lists and blockquotes, including after empty paragraphs; Markdown patch edits must preserve untouched nested blocks.
Documentation
- All public/exported functions & classes must have JSDoc.
- Include:
- Description
- @param and @return (start lowercase, end with period)
- @throws if applicable
- Add a newline between the description and the @ block.
- Use correct punctuation.
Testing
- Run tests with Vitest:
# Run a specific test file (preferred)
yarn test path/to/test.spec.ts
# Run every test (avoid)
yarn test
# Run test suites (avoid)
yarn test:app # All frontend tests
yarn test:server # All backend tests
yarn test:shared # All shared code tests
- Write unit tests for utilities and business logic in a collocated .test.ts file.
- Server tests share a module registry between files. A server test that uses
vi.mockorvi.resetModulesmust start with// @vitest-isolate trueso it runs isolated. - Do not create new test directories
- Mock external dependencies appropriately in mocks folder.
- Aim for high code coverage but focus on critical paths.
Code Quality
- Use Oxlint for linting:
yarn lint - Format code with oxfmt:
yarn format - Check types with TypeScript:
yarn tsc - Pre-commit hooks run automatically via Husky.
- Fix linting issues before committing.
Error Handling
- Use custom error classes in
server/errors.ts. - Always catch and handle errors appropriately.
- Log errors with appropriate context.
- Return user-friendly error messages.
- Never expose sensitive information in errors.
Performance
- Use React.memo for expensive components.
- Implement pagination for large lists.
- Use database indexes effectively.
- Cache expensive computations.
- Use
Redis.ephemeralClientfor request-path caches, rate limits, and locks, including lock extension and release. - Monitor performance with appropriate tools.
- Lazy load routes and components where appropriate.
Security
- Sanitize all user input.
- Always use
sanitizeUrl()when settinghreforsrcfrom user-controlled data in ProseMirrortoDOMmethods, regardless of whether it is imported via an alias or a relative path. Unlike React components,toDOMwrites raw DOM and does not sanitize attribute values. - Use CSRF protection.
- Use rateLimiter middleware for sensitive endpoints.
- Follow OWASP guidelines.
- Never store sensitive data in plain text.
- Use environment variables for secrets.
- When reading untrusted response bodies or import archives, enforce limits while consuming data rather than truncating after buffering. For ZIP imports, set
ZipHelperentry-count and aggregate read-byte limits as well as per-entry limits. Verify oversized responses and archives whose individually valid entries exceed the aggregate limit stop reading.