Introduction to CopyPatch v3

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

// 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';

declare function resolveTrustedClientAddress(request: Request): Promise<string>;

export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } =
  createCopyPatchRouteHandlers(copypatch, {
    resolveContext: async (request) => ({
      clientAddress: await resolveTrustedClientAddress(request),
    }),
  });

// 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

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:

• Installation & CLI Guide – Install packages and scaffold project files.
• Next.js App Router Guide – Set up server routes and server component snapshots.
• React Integration Guide – Configure the provider, text components, and hooks.
• Security Architecture – Learn about same-origin isolation and threat protections.