CopyPatch
EN TR
GitHub Get Started

CopyPatch v2 Documentation

CopyPatch adds inline copy editing to the React applications you already own. Authorized editors and clients can click, edit, and publish copy directly on the live page at ?copypatch=1, while your code, JSX structure, and CSS styling remain 100% untouched.

Core Principle: CopyPatch is an embedded library runtime, not an external SaaS or standalone server. It lives inside your application at the same-origin /__copypatch/api/v2 path, eliminating CORS configuration, proxy layers, and extra hosting infrastructure.

How It Works

  1. Mark Approved Strings: Wrap text nodes with <EditableText contentKey="..."> or read text values with useCopyPatch().
  2. Embed the Backend: Mount the v2 backend at /__copypatch/api/v2 inside your host framework (Next.js App Router, Astro SSR, React Router, Express, Fastify, or Hono).
  3. Choose Storage: Use @copypatch/storage-sqlite for single-server or container deployments, or @copypatch/storage-postgres for horizontally scaled clusters.
  4. Edit On-Page: Authorized team members navigate to ?copypatch=1, authenticate via Argon2id passphrase or host-auth session, and edit inline.
  5. Draft & Publish: Save revisions in draft mode for review, or publish live instantly when holding the publisher role.

Quick Integration Preview

QuickStart.tsx 
// 1. Mount in your host server (e.g. Next.js, Express, Fastify, Hono)
// app/%5F%5Fcopypatch/api/v2/[...path]/route.ts
import { createCopyPatchRouteHandlers } from '@copypatch/next/server';
import { copypatch } from '@/lib/copypatch';

export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } =
  createCopyPatchRouteHandlers(copypatch);

// 2. Wrap components in your client layout
import { CopyPatchProvider, EditableText } from '@copypatch/react';

export function Hero() {
  return (
    <CopyPatchProvider locale="en">
      <EditableText contentKey="hero.title" as="h1">
        Let clients edit the copy. Not the website.
      </EditableText>
    </CopyPatchProvider>
  );
}

Framework Compatibility Matrix

Host Framework Server Integration Deployment Notes
Next.js App Router @copypatch/next catch-all route handlers Direct server snapshot reads via readPublishedSnapshot() for SSR/RSC.
Astro SSR @copypatch/node native adapter Mount in an Astro SSR endpoint; static-only mode renders fallback text only.
React Router v7 @copypatch/node native adapter Framework Mode with server entry point.
Vite + Node / Express / Fastify / Hono @copypatch/node middleware & handlers Mount before request body parsers and SPA catch-all fallbacks.
Static-Only Hosting (SSG) Not Supported for Editing Can render bundled fallback copy, but cannot host API routes or write mutations.

Key Differences from v1

  • Embedded Same-Origin Runtime: v2 runs inside your existing Node/Next server at /__copypatch/api/v2. No second port, standalone daemon, or CORS proxy.
  • Pluggable Storage Adapters: Native SQLite (better-sqlite3) and PostgreSQL (pg) adapters with versioned, idempotent migrations.
  • Dual Authentication Architecture: Built-in Argon2id passphrase session management with CSRF protection, or pluggable authAdapter to reuse host user accounts.
  • Role Separation: Explicit editor role for draft updates and publisher role for live releases.
  • Optimistic Concurrency Control: Atomic compare-and-swap (CAS) validation on revisions prevents accidental overwrites between simultaneous editors.

Next Steps

Follow the step-by-step guides to install and configure CopyPatch in your stack: