From 9aa1fba0eb4ea641b94b812434c76632bdfb9633 Mon Sep 17 00:00:00 2001 From: Ola Adebayo Date: Wed, 2 Sep 2026 11:08:17 +0100 Subject: [PATCH] docs: revamp navigation, close plugin coverage gaps, fix binary size claims MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Full sweep of the docs site for navigability and accuracy: - Merge quick-start.mdx and the near-duplicate examples/quick-no-manifest.mdx into one canonical getting-started tutorial; shrink examples/no-manifest.md to a pointer instead of a third copy of the same content. - Rename examples/nextjs-csr-kubernetes.mdx to nextjs-csr-embedded.mdx to match the actual example folder name on disk. - Add reference/plugins/vite.mdx and reference/plugins/next.mdx documenting repPlugin()/RepScript options and dev-only behavior — previously the Vite and Next.js plugins had no reference page and were under-linked from the framework guides and homepage. - Cross-link the plain-HTML example from frameworks/vanilla.mdx and quick-start.mdx now that it's easier to find. - Fix binary size claims across docs, CLAUDE.md, AGENTS.md, and gateway/README.md: measured the current build (6.9MB darwin/arm64, 7.3MB linux/amd64) and corrected every "~3-5MB"/"~6MB" claim to ~7MB. Also fixes a real spec conformance violation — RFC-0001 R6 required "under 5MB", which the current binary now exceeds; relaxed to "under 8MB" in both spec/REP-RFC-0001.md and its docs mirror. - Add Build-Tool Plugins and Codemod cards to the homepage's Project Components grid — both are real, shipped capabilities that weren't represented there. Claude-Session: https://claude.ai/code/session_01SFPGdCQcXhSzCRRMrkNyyr --- AGENTS.md | 2 +- CLAUDE.md | 2 +- docs/.astro/content-modules.mjs | 40 ++-- docs/astro.config.mjs | 13 +- .../docs/deployment/docker-embedded.mdx | 2 +- ...kubernetes.mdx => nextjs-csr-embedded.mdx} | 0 .../docs/examples/quick-no-manifest.mdx | 123 ------------ docs/src/content/docs/frameworks/react.mdx | 2 +- docs/src/content/docs/frameworks/vanilla.mdx | 2 + docs/src/content/docs/guides/installation.mdx | 6 +- docs/src/content/docs/index.mdx | 14 +- docs/src/content/docs/quick-start.mdx | 33 ++++ .../content/docs/reference/plugins/next.mdx | 78 ++++++++ .../content/docs/reference/plugins/vite.mdx | 62 ++++++ docs/src/content/docs/spec/rfc-0001.mdx | 2 +- examples/no-manifest.md | 178 ++---------------- gateway/README.md | 4 +- spec/REP-RFC-0001.md | 2 +- 18 files changed, 238 insertions(+), 327 deletions(-) rename docs/src/content/docs/examples/{nextjs-csr-kubernetes.mdx => nextjs-csr-embedded.mdx} (100%) delete mode 100644 docs/src/content/docs/examples/quick-no-manifest.mdx create mode 100644 docs/src/content/docs/reference/plugins/next.mdx create mode 100644 docs/src/content/docs/reference/plugins/vite.mdx diff --git a/AGENTS.md b/AGENTS.md index 6eb120d..e248622 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ REP introduces: 3. **HMAC-SHA256 integrity verification** + SRI hashing on every payload 4. **Automatic secret detection guardrails** (Shannon entropy, known key format matching) 5. **Hot config reload** via Server-Sent Events (optional) -6. A **lightweight Go gateway binary** (~3–5MB, zero dependencies, `FROM scratch` compatible) +6. A **lightweight Go gateway binary** (~7MB, zero dependencies, `FROM scratch` compatible) 7. A **zero-dependency TypeScript SDK** (~1.5KB gzipped) with synchronous access for public vars --- diff --git a/CLAUDE.md b/CLAUDE.md index dca2496..59a7956 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,7 +20,7 @@ REP introduces: 3. **HMAC-SHA256 integrity verification** + SRI hashing on every payload 4. **Automatic secret detection guardrails** (Shannon entropy, known key format matching) 5. **Hot config reload** via Server-Sent Events (optional) -6. A **lightweight Go gateway binary** (~3–5MB, zero dependencies, `FROM scratch` compatible) +6. A **lightweight Go gateway binary** (~7MB, zero dependencies, `FROM scratch` compatible) 7. A **zero-dependency TypeScript SDK** (~1.5KB gzipped) with synchronous access for public vars --- diff --git a/docs/.astro/content-modules.mjs b/docs/.astro/content-modules.mjs index f1f599a..1f7ebc7 100644 --- a/docs/.astro/content-modules.mjs +++ b/docs/.astro/content-modules.mjs @@ -1,29 +1,27 @@ export default new Map([ -["src/content/docs/concepts/hot-reload.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fhot-reload.mdx&astroContentModuleFlag=true")], +["src/content/docs/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Findex.mdx&astroContentModuleFlag=true")], ["src/content/docs/contributing.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fcontributing.mdx&astroContentModuleFlag=true")], -["src/content/docs/concepts/security-model.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fsecurity-model.mdx&astroContentModuleFlag=true")], +["src/content/docs/quick-start.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fquick-start.mdx&astroContentModuleFlag=true")], +["src/content/docs/concepts/hot-reload.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fhot-reload.mdx&astroContentModuleFlag=true")], ["src/content/docs/concepts/how-it-works.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fhow-it-works.mdx&astroContentModuleFlag=true")], +["src/content/docs/concepts/security-model.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fsecurity-model.mdx&astroContentModuleFlag=true")], ["src/content/docs/concepts/variable-classification.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fvariable-classification.mdx&astroContentModuleFlag=true")], ["src/content/docs/concepts/wire-format.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fconcepts%2Fwire-format.mdx&astroContentModuleFlag=true")], -["src/content/docs/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Findex.mdx&astroContentModuleFlag=true")], -["src/content/docs/deployment/docker-compose.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fdocker-compose.mdx&astroContentModuleFlag=true")], -["src/content/docs/quick-start.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fquick-start.mdx&astroContentModuleFlag=true")], ["src/content/docs/deployment/ci-cd.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fci-cd.mdx&astroContentModuleFlag=true")], +["src/content/docs/deployment/docker-compose.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fdocker-compose.mdx&astroContentModuleFlag=true")], ["src/content/docs/deployment/docker-embedded.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fdocker-embedded.mdx&astroContentModuleFlag=true")], ["src/content/docs/deployment/docker-proxy.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fdocker-proxy.mdx&astroContentModuleFlag=true")], -["src/content/docs/examples/quick-no-manifest.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fexamples%2Fquick-no-manifest.mdx&astroContentModuleFlag=true")], -["src/content/docs/examples/todo-react.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fexamples%2Ftodo-react.mdx&astroContentModuleFlag=true")], ["src/content/docs/deployment/kubernetes.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fdeployment%2Fkubernetes.mdx&astroContentModuleFlag=true")], +["src/content/docs/examples/nextjs-csr-embedded.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fexamples%2Fnextjs-csr-embedded.mdx&astroContentModuleFlag=true")], +["src/content/docs/examples/nextjs-proxy.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fexamples%2Fnextjs-proxy.mdx&astroContentModuleFlag=true")], +["src/content/docs/examples/simple-html.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fexamples%2Fsimple-html.mdx&astroContentModuleFlag=true")], +["src/content/docs/examples/todo-react.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fexamples%2Ftodo-react.mdx&astroContentModuleFlag=true")], ["src/content/docs/frameworks/angular.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fangular.mdx&astroContentModuleFlag=true")], -["src/content/docs/frameworks/vue.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fvue.mdx&astroContentModuleFlag=true")], -["src/content/docs/frameworks/vanilla.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fvanilla.mdx&astroContentModuleFlag=true")], ["src/content/docs/frameworks/react.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Freact.mdx&astroContentModuleFlag=true")], ["src/content/docs/frameworks/svelte.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fsvelte.mdx&astroContentModuleFlag=true")], -["src/content/docs/guides/installation.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Finstallation.mdx&astroContentModuleFlag=true")], -["src/content/docs/guides/development.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fdevelopment.mdx&astroContentModuleFlag=true")], -["src/content/docs/guides/testing.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Ftesting.mdx&astroContentModuleFlag=true")], -["src/content/docs/guides/manifest.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmanifest.mdx&astroContentModuleFlag=true")], +["src/content/docs/frameworks/vanilla.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fvanilla.mdx&astroContentModuleFlag=true")], +["src/content/docs/frameworks/vue.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fframeworks%2Fvue.mdx&astroContentModuleFlag=true")], ["src/content/docs/reference/cli.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fcli.mdx&astroContentModuleFlag=true")], ["src/content/docs/reference/codemod.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fcodemod.mdx&astroContentModuleFlag=true")], ["src/content/docs/reference/gateway-endpoints.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fgateway-endpoints.mdx&astroContentModuleFlag=true")], @@ -31,14 +29,20 @@ export default new Map([ ["src/content/docs/reference/manifest-schema.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fmanifest-schema.mdx&astroContentModuleFlag=true")], ["src/content/docs/reference/sdk.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fsdk.mdx&astroContentModuleFlag=true")], ["src/content/docs/spec/conformance.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fspec%2Fconformance.mdx&astroContentModuleFlag=true")], -["src/content/docs/spec/rfc-0001.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fspec%2Frfc-0001.mdx&astroContentModuleFlag=true")], ["src/content/docs/spec/index.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fspec%2Findex.mdx&astroContentModuleFlag=true")], +["src/content/docs/spec/rfc-0001.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fspec%2Frfc-0001.mdx&astroContentModuleFlag=true")], ["src/content/docs/spec/security-model.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fspec%2Fsecurity-model.mdx&astroContentModuleFlag=true")], -["src/content/docs/reference/adapters/vue.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fadapters%2Fvue.mdx&astroContentModuleFlag=true")], -["src/content/docs/reference/adapters/svelte.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fadapters%2Fsvelte.mdx&astroContentModuleFlag=true")], +["src/content/docs/guides/development.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fdevelopment.mdx&astroContentModuleFlag=true")], +["src/content/docs/guides/installation.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Finstallation.mdx&astroContentModuleFlag=true")], +["src/content/docs/guides/testing.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Ftesting.mdx&astroContentModuleFlag=true")], +["src/content/docs/guides/manifest.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmanifest.mdx&astroContentModuleFlag=true")], ["src/content/docs/reference/adapters/react.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fadapters%2Freact.mdx&astroContentModuleFlag=true")], -["src/content/docs/guides/migration/from-vite.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-vite.mdx&astroContentModuleFlag=true")], -["src/content/docs/guides/migration/from-next.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-next.mdx&astroContentModuleFlag=true")], +["src/content/docs/reference/adapters/svelte.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fadapters%2Fsvelte.mdx&astroContentModuleFlag=true")], +["src/content/docs/reference/adapters/vue.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fadapters%2Fvue.mdx&astroContentModuleFlag=true")], +["src/content/docs/reference/plugins/next.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fplugins%2Fnext.mdx&astroContentModuleFlag=true")], +["src/content/docs/reference/plugins/vite.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Freference%2Fplugins%2Fvite.mdx&astroContentModuleFlag=true")], ["src/content/docs/guides/migration/from-cra.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-cra.mdx&astroContentModuleFlag=true")], +["src/content/docs/guides/migration/from-next.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-next.mdx&astroContentModuleFlag=true")], +["src/content/docs/guides/migration/from-vite.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Ffrom-vite.mdx&astroContentModuleFlag=true")], ["src/content/docs/guides/migration/overview.mdx", () => import("astro:content-layer-deferred-module?astro%3Acontent-layer-deferred-module=&fileName=src%2Fcontent%2Fdocs%2Fguides%2Fmigration%2Foverview.mdx&astroContentModuleFlag=true")]]); \ No newline at end of file diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index c5e0cf6..63b5588 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -194,16 +194,12 @@ export default defineConfig({ { label: 'Examples', items: [ - { - label: 'Zero-Config Quick Start', - slug: 'examples/quick-no-manifest', - }, { label: 'Todo App (React)', slug: 'examples/todo-react' }, { label: 'Simple HTML (ESM.sh)', slug: 'examples/simple-html' }, { label: 'Next.js — Proxy Mode', slug: 'examples/nextjs-proxy' }, { label: 'Next.js CSR + Kubernetes', - slug: 'examples/nextjs-csr-kubernetes', + slug: 'examples/nextjs-csr-embedded', }, ], }, @@ -226,6 +222,13 @@ export default defineConfig({ { label: 'Svelte', slug: 'reference/adapters/svelte' }, ], }, + { + label: 'Build-Tool Plugins', + items: [ + { label: 'Vite', slug: 'reference/plugins/vite' }, + { label: 'Next.js', slug: 'reference/plugins/next' }, + ], + }, { label: 'Codemod', slug: 'reference/codemod' }, ], }, diff --git a/docs/src/content/docs/deployment/docker-embedded.mdx b/docs/src/content/docs/deployment/docker-embedded.mdx index 94050d1..73b8d0d 100644 --- a/docs/src/content/docs/deployment/docker-embedded.mdx +++ b/docs/src/content/docs/deployment/docker-embedded.mdx @@ -36,7 +36,7 @@ CMD ["--mode", "embedded", "--static-dir", "/static", "--port", "8080", "--stric Exactly two things: - Your built static files (`dist/`) -- The REP gateway binary (~6MB) +- The REP gateway binary (~7MB) No OS, no shell, no utilities, no package manager. Attack surface: near zero. diff --git a/docs/src/content/docs/examples/nextjs-csr-kubernetes.mdx b/docs/src/content/docs/examples/nextjs-csr-embedded.mdx similarity index 100% rename from docs/src/content/docs/examples/nextjs-csr-kubernetes.mdx rename to docs/src/content/docs/examples/nextjs-csr-embedded.mdx diff --git a/docs/src/content/docs/examples/quick-no-manifest.mdx b/docs/src/content/docs/examples/quick-no-manifest.mdx deleted file mode 100644 index af6f299..0000000 --- a/docs/src/content/docs/examples/quick-no-manifest.mdx +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Zero-Config Quick Start — No Manifest Required -description: Use REP with just naming conventions and no configuration file. Rename env vars with REP_PUBLIC_/REP_SENSITIVE_ prefixes, install the SDK, and run the gateway. ---- - -import { Aside } from '@astrojs/starlight/components'; - -The `.rep.yaml` manifest is entirely optional. The gateway works with nothing but environment variables — the naming convention **is** the configuration. - -## How it works - -| Env var prefix | Tier | In the browser | -|---|---|---| -| `REP_PUBLIC_*` | PUBLIC | Plaintext in `` breakout from untrusted env values. The tag still carries `type="application/json"`, so the browser never executes it. +- **Ephemeral keys are process-scoped**, held in a module-level singleton (`getOrCreateKeys()`) so the same key survives across route handler invocations within one `next dev` process. +- **Byte-identical payload** to the Go gateway and the Vite plugin (sorted keys, same HMAC + SRI format) — `rep.verify()` and `rep.meta()` behave the same regardless of which one produced the payload. + +## App Router only + +`RepScript` is a Server Component and requires the App Router (`app/`). The Pages Router (`pages/`) doesn't support React Server Components — use the [CLI dev server](/guides/development/#option-d-cli-dev-server-full-fidelity) or [mock payload](/guides/development/#option-c-mock-payload-in-html) approach instead. + +## See also + +- [Local Development guide](/guides/development/) — where this fits alongside the CLI dev server and mock-payload approaches +- [Next.js — Proxy Mode example](/examples/nextjs-proxy/) — production deployment behind the gateway +- [Vite plugin reference](/reference/plugins/vite/) — the equivalent for Vite diff --git a/docs/src/content/docs/reference/plugins/vite.mdx b/docs/src/content/docs/reference/plugins/vite.mdx new file mode 100644 index 0000000..3617ca2 --- /dev/null +++ b/docs/src/content/docs/reference/plugins/vite.mdx @@ -0,0 +1,62 @@ +--- +title: Vite Plugin Reference — @rep-protocol/vite +description: API reference for the REP Vite plugin. repPlugin() options, dev-mode behavior, the /rep/session-key middleware, and how it differs from the production gateway. +--- + +import { Aside } from '@astrojs/starlight/components'; + +```bash +npm install -D @rep-protocol/vite +``` + +```ts +// vite.config.ts +import { defineConfig } from 'vite'; +import { repPlugin } from '@rep-protocol/vite'; + +export default defineConfig({ + plugins: [repPlugin()], +}); +``` + +## `repPlugin(options?)` + +```typescript +interface RepPluginOptions { + env?: string; + strict?: boolean; +} + +function repPlugin(options?: RepPluginOptions): Plugin; +``` + +| Option | Type | Default | Description | +|---|---|---|---| +| `env` | `string` | `'.env.local'` | Path to the env file, relative to the project root. Classified the same way as the gateway: `REP_PUBLIC_*`, `REP_SENSITIVE_*`, `REP_SERVER_*` prefixes. | +| `strict` | `boolean` | `false` | Turn guardrail warnings into thrown errors instead of console warnings. | + +```ts +repPlugin({ + env: '.env.development', + strict: true, +}) +``` + +## Behavior + +- **Dev only.** The plugin only runs during `vite dev` (`configureServer` hook). It does nothing during `vite build` — production HTML ships with no `__rep__` script tag, and the gateway injects it at serve time instead. +- **Injects `