Note: @aws-sdk/signature-v4-crt requires native bindings. On Linux/Mac run npm rebuild after install. The server requires Postgres (>=14) and Redis; use docker-compose up to spin them up locally.

Project setup

1. Copy the source/ directory into your project root or a subdirectory (e.g. ./outline-src/).

2. Merge tsconfig.json path aliases into your own config. Outline uses ~/ as an alias for app/:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~/*": ["./app/*"],
      "shared/*": ["./shared/*"]
    }
  }
}

3. Configure required environment variables. Copy .env.sample (if present) or set:

SECRET_KEY=<random 32-char string>
DATABASE_URL=postgres://user:pass@localhost:5432/outline
REDIS_URL=redis://localhost:6379
URL=http://localhost:3000
PORT=3000
# Optional S3 storage
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_S3_UPLOAD_BUCKET_NAME=
AWS_REGION=
# Optional Sentry
SENTRY_DSN=
DEFAULT_LANGUAGE=en_US

4. Run database migrations before starting the server:

yarn db:migrate

5. Start development servers:

yarn dev        # starts both Vite frontend and Node backend via concurrently

6. For production, build then start:

yarn build
yarn start

Public API

createAction

import { createAction } from "~/actions";

function createAction(
  definition: Optional<Omit<Action, "type" | "variant">, "id">
): Action;

Registers a new command-bar or context-menu action. Use this when adding custom user-triggerable commands. The perform callback receives an ActionContext with current user, document, and UI state. Analytics tracking fires automatically if analyticsName is provided.

ActionSeparator

import { ActionSeparator } from "~/actions";

const ActionSeparator: TActionSeparator; // { type: "action_separator" }

A sentinel object used to insert visual dividers between groups of actions in menus and the command bar. Place it between createAction calls when building action arrays for a menu renderer.

resolve

import { resolve } from "~/actions";

function resolve<T>(value: any, context: ActionContext): T;

Unwraps a value that may be either a static value or a function that accepts an ActionContext. Used internally by action rendering but useful when building conditional action properties such as visible, enabled, or name that depend on runtime state.

Avatar / AvatarSize / AvatarVariant

import { Avatar, AvatarSize, AvatarVariant } from "~/components/Avatar";

enum AvatarSize { /* Small, Medium, Large, ... */ }
enum AvatarVariant { /* Circle, Square */ }

A presentational component for rendering user and group avatars. Accepts an IAvatar model (user or integration object) and renders appropriately sized, shaped profile images with presence indicators via AvatarWithPresence.

Working examples

Scenario - Registering a custom action

Add a custom action that opens an external link from the command bar and context menus.

import { createAction, ActionSeparator } from "~/actions";
import { DownloadIcon } from "outline-icons";

const exportAction = createAction({
  name: "Export to PDF",
  analyticsName: "export_pdf",
  section: { name: "Document", id: "document" },
  icon: <DownloadIcon />,
  visible: ({ activeDocumentId }) => !!activeDocumentId,
  perform: async ({ activeDocumentId }) => {
    if (!activeDocumentId) return;
    window.open(`/api/documents/${activeDocumentId}/export?type=pdf`, "_blank");
  },
});

// Group with separator for menu rendering
const documentActions = [exportAction, ActionSeparator];

Scenario - Resolving dynamic action properties

Use resolve to evaluate action properties that may be static or context-dependent, matching how Outline's internal menu renderers work.

import { resolve, createAction } from "~/actions";
import type { ActionContext } from "~/types";

const archiveAction = createAction({
  name: (ctx: ActionContext) =>
    ctx.activeDocument?.isArchived ? "Unarchive" : "Archive",
  analyticsName: "toggle_archive",
  perform: (ctx) => {
    const doc = ctx.activeDocument;
    if (!doc) return;
    doc.isArchived ? doc.unarchive() : doc.archive();
  },
});

// Evaluate the name in a custom renderer:
function renderActionName(action: typeof archiveAction, ctx: ActionContext) {
  return resolve<string>(action.name, ctx);
}

Scenario - Rendering Avatar in a user list

Embed the Avatar component with presence tracking inside a custom team member list.

import React from "react";
import { Avatar, AvatarSize, AvatarVariant, AvatarWithPresence } from "~/components/Avatar";
import type { IAvatar } from "~/components/Avatar";

interface Props {
  users: IAvatar[];
  onlineIds: Set<string>;
}

export function TeamMemberList({ users, onlineIds }: Props) {
  return (
    <ul>
      {users.map((user) => (
        <li key={user.id} style={{ display: "flex", alignItems: "center", gap: 8 }}>
          <AvatarWithPresence
            model={user}
            size={AvatarSize.Medium}
            variant={AvatarVariant.Circle}
            isOnline={onlineIds.has(user.id)}
          />
          <span>{user.name}</span>
        </li>
      ))}
    </ul>
  );
}

File walkthrough

• .github/ - GitHub Actions workflows for CI, Docker image publishing, CodeQL analysis, and automated PR management.
• .vscode/ - Shared editor settings (format on save, TypeScript SDK path) to enforce consistency.
• __mocks__/ - Module mocks (e.g. for file imports, SVGs) used by Jest during unit testing.
• app/ - All client-side code: React components, MobX stores, route definitions, action system, hooks, and the rich text editor layer.
• app/actions/ - Declarative action registry powering the command bar, context menus, and keyboard shortcuts.
• app/components/ - Shared UI components (Avatar, CommandBar, DocumentExplorer, dialogs, etc.).
• app/editor/ - ProseMirror/TipTap rich text editor extensions, plugins, and toolbar components.
• app/hooks/ - Custom React hooks (context, permissions, real-time presence, etc.).
• app/models/ - MobX model classes mirroring server entities (Document, Collection, User, etc.).
• app/routes/ - React Router route tree and lazy-loaded scene wrappers.
• app/scenes/ - Full-page route components (document viewer, settings pages, auth screens).
• app/stores/ - MobX stores for client-side state management and API interaction.
• docs/ - Architecture overview, translation guide, and contributor docs.
• plugins/ - Self-contained plugin modules for OAuth providers, storage adapters, and third-party integrations.
• public/ - Static files served directly (logos, favicons, manifest).
• server/ - Koa HTTP server, REST API routes, Sequelize models, background job queues, and WebSocket collaboration server.
• shared/ - Cross-boundary TypeScript types, constants, and pure utility functions used by both app/ and server/.
• build.js - Custom esbuild/Vite orchestration script for production builds.
• vite.config.ts - Vite dev server and bundle configuration including path aliases and plugin setup.

Common pitfalls and fixes

• ~/ path alias not resolved: Add "~/*": ["./app/*"] to tsconfig.json paths and mirror it in vite.config.ts under resolve.alias.
• MobX computedRequiresReaction warnings: Wrap computed accesses in reaction, autorun, or an observer component; do not read computed values outside reactive contexts.
• Missing SECRET_KEY crashes server on boot: Generate with openssl rand -hex 32 and set in .env; the server validates its presence at startup.
• @aws-sdk/signature-v4-crt native build failure: Ensure cmake and a C++ toolchain are installed; on Alpine Linux add build-base and cmake packages before npm install.
• Yarn Berry (PnP) module resolution errors: Outline uses Yarn Berry with nodeLinker: node-modules set in .yarnrc.yml; do not switch to PnP mode without patching all bare-specifier imports.
• Database migrations not run: Always execute yarn db:migrate before first start and after pulling new commits; skipping causes relation does not exist runtime errors.

Vibe-coding prompt template

I have dropped the Outline knowledge base source code into `./source/` in my project.
I have also read `USAGE.md` which documents the real exports and setup steps.
The upstream package is `user@example.com`.

Please help me integrate Outline into my existing Node.js/TypeScript project step by step:

1. Read `USAGE.md` and `source/tsconfig.json` to understand path aliases and project structure.
2. Merge the required `paths` aliases into my `tsconfig.json` and configure `vite.config.ts` accordingly.
3. Set up the environment variables listed in `USAGE.md` in my `.env` file.
4. Wire the `source/server/` Koa application into my existing Express/Koa entry point, or run it as a separate service.
5. Show me how to import and use `createAction` from `source/app/actions/index.ts` to add a custom command-bar action.
6. Show me how to render the `Avatar` component from `source/app/components/Avatar/index.ts` in my React component tree.
7. Identify any dependency conflicts between my current `package.json` and `source/package.json` and suggest resolutions.

Only use exports that are explicitly documented in `USAGE.md`. Do not invent new APIs.

License and credit

Outline is released under the BSL 1.1 license (Business Source License). See source/LICENSE for the full terms. The hosted product and source are maintained by the Outline team at github.com/outline/outline and getoutline.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.