{
  "compilerOptions": {
    "paths": {
      "@tryghost/activitypub": ["./source/apps/activitypub/src/index.tsx"],
      "@tryghost/activitypub/*": ["./source/apps/activitypub/src/*"]
    }
  }
}

5. Add source/apps/activitypub to your bundler's include or resolve.modules array (Vite/Webpack) so CSS and asset imports resolve correctly.

6. Wire the ActivityPub app into your admin shell by importing AdminXApp and mounting it at your chosen route.

7. For Docker-based local dev: docker compose -f source/compose.dev.yaml up -d starts the full backing stack (database, mail, storage).

Public API

AdminXApp

import AdminXApp from '@tryghost/activitypub';
// or directly:
import AdminXApp from './source/apps/activitypub/src/app';

const AdminXApp: React.ComponentType<Record<string, unknown>>;

The root React application component for the ActivityPub admin interface. Mount this inside your admin shell or any React tree to render the full ActivityPub management UI including feeds, followers, and settings.

routes

import { routes } from './source/apps/activitypub/src/index.tsx';

const routes: RouteObject[]; // React Router v6 route definitions

The exported React Router route configuration for the ActivityPub app. Use this to compose ActivityPub routes into an existing React Router setup rather than mounting the full AdminXApp.

FeatureFlagsProvider

import { FeatureFlagsProvider } from './source/apps/activitypub/src/index.tsx';

const FeatureFlagsProvider: React.ComponentType<{
  children: React.ReactNode;
  flags?: Record<string, boolean>;
}>;

Context provider that enables or disables experimental features within the ActivityPub UI. Wrap your component tree with this before mounting AdminXApp or any ActivityPub component to control feature visibility.

useNotificationsCountForUser

import { useNotificationsCountForUser } from './source/apps/activitypub/src/index.tsx';

function useNotificationsCountForUser(userId: string): {
  count: number | undefined;
  isLoading: boolean;
};

React hook that returns the unread ActivityPub notification count for a given user. Use this in nav bars or badge indicators to show live notification counts without mounting the full ActivityPub app.

Working examples

Scenario - Mounting the ActivityPub admin app in an existing React admin

Drop the full ActivityPub admin panel into an existing admin shell. Assumes React Router v6 is already configured.

import React from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import AdminXApp from './source/apps/activitypub/src/app';
import { FeatureFlagsProvider } from './source/apps/activitypub/src/index.tsx';

export default function AdminShell() {
  return (
    <BrowserRouter>
      <FeatureFlagsProvider flags={{ socialWeb: true }}>
        <Routes>
          <Route path="/activitypub/*" element={<AdminXApp />} />
        </Routes>
      </FeatureFlagsProvider>
    </BrowserRouter>
  );
}

Scenario - Composing only the ActivityPub routes into an existing router

When you already have a React Router root and want to nest ActivityPub routes without ceding full layout control.

import React from 'react';
import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import { routes as activityPubRoutes } from './source/apps/activitypub/src/index.tsx';
import RootLayout from './layouts/RootLayout';

const router = createBrowserRouter([
  {
    path: '/',
    element: <RootLayout />,
    children: [
      ...activityPubRoutes,
      // your other routes
    ],
  },
]);

export default function App() {
  return <RouterProvider router={router} />;
}

Scenario - Notification badge using the ActivityPub hook

Display an unread notification count in a top nav bar without mounting the full ActivityPub app.

import React from 'react';
import { useNotificationsCountForUser } from './source/apps/activitypub/src/index.tsx';

interface NavBadgeProps {
  userId: string;
}

export function ActivityPubNavBadge({ userId }: NavBadgeProps) {
  const { count, isLoading } = useNotificationsCountForUser(userId);

  if (isLoading || !count) return null;

  return (
    <span className="notification-badge">
      {count > 99 ? '99+' : count}
    </span>
  );
}

File walkthrough

• .agents/ - Contains structured AI agent skill packs (e.g., add-admin-api-endpoint, create-database-migration) with markdown instructions for automated coding tasks.
• .codex/ - Holds environment.toml defining the automated development environment specification for Codex-based workflows.
• .cursor/ - Stores worktrees.json for Cursor IDE multi-worktree navigation support.
• .github/ - Full GitHub ecosystem config: CI workflows, Renovate bot config, issue templates, PR templates, custom Actions, and agentic workflow definitions.
• .vscode/ - Editor settings and recommended extensions for contributors.
• adr/ - Markdown Architecture Decision Records; read these to understand why key technical choices were made.
• apps/ - Standalone frontend applications. apps/activitypub is the Fediverse/social web UI; other apps include AdminX extensions.
• docker/ - Dockerfiles and supporting assets consumed by the compose.dev.*.yaml files.
• docs/ - Internal developer documentation not published to ghost.org/docs.
• ghost/ - The heart of the repo: all Ghost core packages, API layers, models, and services as individual npm packages.
• scripts/ - Monorepo-level scripts for version bumping, cleaning, and dependency inspection.
• nx.json - Nx task runner configuration defining caching, pipelines, and affected-project logic.
• package.json - Root manifest; defines the user@example.com package and workspace scripts.
• pnpm-workspace.yaml - Declares all workspace globs so pnpm links internal packages correctly.

Common pitfalls and fixes

• pnpm version mismatch: The workspace enforces a specific pnpm version via scripts/enforce-package-manager.js; install the pinned version with corepack enable && corepack prepare.
• CSS not loading for ActivityPub app: apps/activitypub/src/styles/index.css must be processed by your bundler; add a CSS loader or Vite plugin — do not skip the CSS import in index.tsx.
• React version peer conflict: The ActivityPub app requires React 18; if your project uses React 17 you will get hook errors — upgrade or alias React in your bundler.
• Missing URL env var at runtime: Ghost core will refuse to start without a URL environment variable set to the site's public origin — set it before running any Ghost process.
• ESM/CJS interop with internal packages: Internal ghost/ packages publish both ESM and CJS; if your bundler picks the wrong condition, set "moduleResolution": "bundler" in tsconfig.json.
• Nx cache stale after dependency changes: Run pnpm exec nx reset to clear the Nx computation cache after modifying package.json files in any workspace package.

Vibe-coding prompt template

I have the Ghost CMS monorepo source in the `source/` directory.
The upstream package is `user@example.com`.
I also have `USAGE.md` which documents the public exports and setup steps.

Please help me integrate the ActivityPub admin UI and notification hooks
into my existing React + TypeScript project step by step:

1. Read `USAGE.md` fully before making any changes.
2. Install all required dependencies listed in the "Required dependencies" section.
3. Update my `tsconfig.json` with the path aliases shown in "Project setup".
4. Mount `AdminXApp` from `source/apps/activitypub/src/app` inside my admin
   shell at the `/activitypub` route, wrapped in `FeatureFlagsProvider`.
5. Add the `useNotificationsCountForUser` hook to my nav bar component.
6. Show me the exact file changes needed, with full file contents where modified.
7. Do not invent any exports — only use symbols documented in `USAGE.md`.

License and credit

Ghost is released under the MIT License. See source/LICENSE for the full license text.

Upstream project: TryGhost/Ghost — maintained by the Ghost Foundation. The user@example.com package is the root of that repository.

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.