feat: add @rep-protocol/vite and @rep-protocol/next plugins by olamide226 · Pull Request #39 · RuachTech/rep

olamide226 · 2026-03-17T02:06:34Z

Summary

@rep-protocol/vite — Vite plugin that injects the REP <script id="__rep__"> tag during vite dev, eliminating the need to run the Go gateway during development. Uses transformIndexHtml + configureServer middleware. Watches .env.local for live reload.
@rep-protocol/next — Next.js integration via RepScript (React Server Component) and a session-key route handler. RepScript renders the payload during next dev and returns null in production — the gateway owns injection in prod for both output: 'standalone' and output: 'export'.
Both plugins produce byte-identical JSON to the Go gateway (sorted keys, Go HTML escaping of <>&), so the SDK works identically in dev and prod.

Security

Next.js RepScript returns null when NODE_ENV=production — prevents build-time env var leakage
Session-key route handler returns 404 in production — no unhardened endpoint in prod
Only REP_PUBLIC_* and REP_SENSITIVE_* reach the client; REP_SERVER_* and non-REP vars stay server-side
JSON values Go-escaped (<>& → \u003c\u003e\u0026) to prevent </script> breakout via dangerouslySetInnerHTML
Guardrails scan PUBLIC vars for misclassified secrets (Shannon entropy + known format detection)

Changes

plugins/vite/ — 6 source files, 49 tests
plugins/next/ — 8 source files, 13 tests
Updated examples/todo-react to use Vite plugin
Updated examples/nextjs-proxy to use RepScript + session-key route
Docs: installation, development, React framework guide, both example pages
CI: sdk.yml path filters, release-sdk.yml tag recovery + npm publish steps
Monorepo: pnpm-workspace.yaml, release-please-config.json, .release-please-manifest.json

Test plan

cd plugins/vite && pnpm test — 49 tests pass (crypto round-trips, env classification, payload byte parity, plugin integration)
cd plugins/next && pnpm test — 13 tests pass (RepScript dev/prod modes, session-key dev/prod, encryption round-trip, XSS prevention, server var isolation)
cd plugins/vite && pnpm build — CJS + ESM + types
cd plugins/next && pnpm build — CJS + ESM + types (two entry points)
Manual: add plugin to a Vite app, run pnpm dev, verify rep.get() returns values
Manual: add RepScript to a Next.js app, run next dev, verify SDK works without gateway

Eliminates the need to run the Go gateway during development. The plugin injects the same <script id="__rep__"> tag via Vite's transformIndexHtml hook, making the SDK work identically in `vite dev`. - crypto.ts: HKDF-SHA256 key derivation, AES-256-GCM, HMAC, SRI (Node crypto) - env.ts: dotenv reading + REP_* variable classification by prefix tier - guardrails.ts: Shannon entropy + known secret format detection - payload.ts: Go-compatible JSON serialization (sorted keys, HTML escaping) - index.ts: Vite plugin with session-key middleware and env file watching - 49 tests covering crypto round-trips, env classification, payload parity - Update todo-react example to use the plugin instead of rep:dev proxy - Add plugins/* to pnpm-workspace and release-please config

RepScript is a React Server Component that injects the REP <script> tag during `next dev`, eliminating the need to run the Go gateway during development. Returns null in production — the gateway owns injection in prod for both standalone and static export modes. Security: - RepScript returns null when NODE_ENV=production, preventing build-time env vars from being baked into static HTML - Session-key route handler returns 404 in production, preventing accidental exposure of an unhardened endpoint alongside the gateway - Only REP_PUBLIC_* and REP_SENSITIVE_* reach the client; REP_SERVER_* and non-REP vars stay server-side - JSON values are Go-escaped (<>& → \u003c\u003e\u0026) to prevent script tag breakout via dangerouslySetInnerHTML - RepScript RSC for layout.tsx (dev renders, prod returns null) - Session-key GET handler for app/api/rep/session-key/route.ts - Module-scoped key singleton shared between RepScript and handler - 13 tests covering security boundaries, encryption round-trips, XSS - Update nextjs-proxy example to use the plugin - Add plugins/next to release-please config and linked-versions

Docs: - installation.mdx: add build-tool plugins section (Vite + Next.js) - development.mdx: add plugin as Option A (recommended), renumber others - frameworks/react.mdx: add Vite plugin tab to dev mode section - examples/todo-react.mdx: update to show Vite plugin workflow - examples/nextjs-proxy.mdx: update file tree and dev section for RepScript CI: - sdk.yml: add plugins/** to path filters so plugin changes trigger CI - release-sdk.yml: add vite/next to recover-stale-releases tag map and publish-npm steps

Copilot

Pull request overview

This PR adds first-party Vite and Next.js dev-time integrations for REP, wiring them into the monorepo/release tooling and updating examples + docs to use the new plugins.

Changes:

Introduces new workspace packages: @rep-protocol/vite (Vite dev server plugin) and @rep-protocol/next (Next.js RepScript + dev-only /rep/session-key route handler).
Updates monorepo config/release automation to include plugins/* packages (pnpm workspace, release-please, CI/release workflows).
Updates docs and examples to demonstrate plugin-based dev injection (no gateway required for local dev).

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
release-please-config.json	Adds `vite`/`next` components and package entries for release-please.
pnpm-workspace.yaml	Adds `plugins/*` packages to the pnpm workspace.
pnpm-lock.yaml	Adds lock entries for `plugins/vite` and `plugins/next` dependencies.
plugins/vite/vitest.config.ts	Vitest configuration for the new Vite plugin package.
plugins/vite/tsconfig.json	TypeScript config for the Vite plugin package.
plugins/vite/src/crypto.ts	Crypto primitives (HKDF/HMAC/AES-GCM/SRI + Go HTML escaping) for payload generation.
plugins/vite/src/env.ts	`.env` parsing + REP tier classification logic.
plugins/vite/src/guardrails.ts	Secret-detection guardrails (entropy + known prefixes).
plugins/vite/src/payload.ts	Payload builder intended to mirror gateway payload output.
plugins/vite/src/index.ts	Implements `repPlugin()` and dev-only `/rep/session-key` middleware + HTML injection.
plugins/vite/src/tests/crypto.test.ts	Unit tests for crypto helpers.
plugins/vite/src/tests/env.test.ts	Unit tests for env parsing/classification.
plugins/vite/src/tests/payload.test.ts	Unit tests for payload output/encryption/decryption.
plugins/vite/src/tests/plugin.test.ts	Unit tests for Vite plugin integration behavior.
plugins/vite/package.json	New npm package definition for `@rep-protocol/vite`.
plugins/next/vitest.config.ts	Vitest configuration for the new Next.js plugin package.
plugins/next/tsconfig.json	TypeScript config for the Next.js plugin package.
plugins/next/src/crypto.ts	Crypto primitives duplicated for Next.js integration.
plugins/next/src/env.ts	`.env` parsing + REP tier classification logic (duplicated).
plugins/next/src/guardrails.ts	Guardrails logic (duplicated).
plugins/next/src/payload.ts	Payload builder (duplicated).
plugins/next/src/keys.ts	Module-scoped singleton for dev keys shared across handlers/components.
plugins/next/src/session-key.ts	Dev-only `/rep/session-key` GET handler (returns 404 in production).
plugins/next/src/index.ts	`RepScript` RSC that injects REP payload in dev and returns null in prod.
plugins/next/src/tests/session-key.test.ts	Tests for the dev session-key handler.
plugins/next/src/tests/rep-script.test.ts	Tests for `RepScript` injection, escaping, and tier exposure rules.
plugins/next/package.json	New npm package definition for `@rep-protocol/next`.
examples/todo-react/vite.config.ts	Adds `repPlugin()` to the example’s Vite config for dev injection.
examples/todo-react/package.json	Adds new dev script + bumps REP deps and adds `@rep-protocol/vite`.
examples/nextjs-proxy/src/app/layout.tsx	Adds `RepScript` to the example layout for dev injection.
examples/nextjs-proxy/src/app/api/rep/session-key/route.ts	Adds dev-only session-key route re-export.
examples/nextjs-proxy/package.json	Updates REP deps and adds `@rep-protocol/next`.
docs/src/content/docs/guides/installation.mdx	Documents installing/using Vite + Next build-tool plugins.
docs/src/content/docs/guides/development.mdx	Reframes dev workflow around build-tool plugins (Option A).
docs/src/content/docs/frameworks/react.mdx	Adds Vite plugin option for React dev mode.
docs/src/content/docs/examples/todo-react.mdx	Updates example run instructions for plugin-based dev.
docs/src/content/docs/examples/nextjs-proxy.mdx	Updates example structure + dev instructions for `@rep-protocol/next`.
CLAUDE.md	Documents new plugins and their intended parity with gateway logic.
.release-please-manifest.json	Tracks initial versions for `plugins/vite` and `plugins/next`.
.github/workflows/sdk.yml	Expands path filters to include `plugins/**`.
.github/workflows/release-sdk.yml	Adds npm publish steps for `@rep-protocol/vite` and `@rep-protocol/next`.

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/src/content/docs/guides/installation.mdx

docs/src/content/docs/guides/development.mdx

docs/src/content/docs/frameworks/react.mdx

pnpm-lock.yaml

examples/nextjs-proxy/package.json

plugins/vite/src/index.ts

plugins/next/src/session-key.ts

CLAUDE.md

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR adds first-party build-tool integrations (Vite + Next.js) that inject a REP payload during development so the JS SDK can run without the Go gateway, and wires the new packages into the monorepo release + CI machinery.

Changes:

Add @rep-protocol/vite (Vite dev server plugin) and @rep-protocol/next (RepScript + dev-only /rep/session-key route handler) packages.
Update docs + examples to use the new dev-time injection path.
Update workspace/release automation (pnpm workspace, release-please, and publish workflow) to include plugins/*.

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
release-please-config.json	Adds `vite`/`next` components and package entries for release-please.
pnpm-workspace.yaml	Adds `plugins/*` to the pnpm workspace.
pnpm-lock.yaml	Locks new dependencies for the plugin packages (Next/Vite/Vitest/etc.).
plugins/vite/vitest.config.ts	Vitest config for the Vite plugin package.
plugins/vite/tsconfig.json	TS compiler settings for the Vite plugin package.
plugins/vite/src/crypto.ts	Node crypto implementation (HKDF/HMAC/AES-GCM/SRI) mirroring gateway behavior.
plugins/vite/src/env.ts	dotenv + classification of REP_* vars into tiers.
plugins/vite/src/guardrails.ts	Secret-detection guardrails for PUBLIC values.
plugins/vite/src/payload.ts	Manual payload JSON construction + Go-style escaping + SRI.
plugins/vite/src/index.ts	Vite plugin implementation: inject payload + dev session-key endpoint + env watching.
plugins/vite/src/tests/crypto.test.ts	Unit tests for crypto helpers.
plugins/vite/src/tests/env.test.ts	Unit tests for env parsing/classification.
plugins/vite/src/tests/payload.test.ts	Unit tests for payload building, ordering, escaping, encryption, integrity.
plugins/vite/src/tests/plugin.test.ts	Unit tests for Vite plugin behavior (middleware/injection/strict mode).
plugins/vite/package.json	New publishable package manifest for `@rep-protocol/vite`.
plugins/next/vitest.config.ts	Vitest config for the Next plugin package.
plugins/next/tsconfig.json	TS compiler settings for the Next plugin package.
plugins/next/src/crypto.ts	Same crypto helpers as Vite plugin (copied).
plugins/next/src/env.ts	Same env parsing/classification as Vite plugin (copied).
plugins/next/src/guardrails.ts	Same guardrails as Vite plugin (copied).
plugins/next/src/payload.ts	Same payload builder as Vite plugin (copied).
plugins/next/src/keys.ts	Module-scoped singleton keys for RepScript + session-key handler.
plugins/next/src/index.ts	`RepScript` RSC: injects payload in dev, renders null in prod.
plugins/next/src/session-key.ts	Dev-only Next route handler for `/rep/session-key` (404 in prod).
plugins/next/src/tests/rep-script.test.ts	Tests RepScript dev/prod behavior + escaping + encryption behavior.
plugins/next/src/tests/session-key.test.ts	Tests session-key handler behavior + singleton key sharing.
plugins/next/package.json	New publishable package manifest for `@rep-protocol/next`.
examples/todo-react/vite.config.ts	Uses `repPlugin()` in dev.
examples/todo-react/package.json	Adds plugin + updates scripts and REP package versions.
examples/nextjs-proxy/src/app/layout.tsx	Injects `<RepScript />` in dev via Next integration.
examples/nextjs-proxy/src/app/api/rep/session-key/route.ts	Re-exports `GET` handler from `@rep-protocol/next/session-key`.
examples/nextjs-proxy/package.json	Adds `@rep-protocol/next` and bumps REP package versions.
docs/src/content/docs/guides/installation.mdx	Documents optional Vite/Next plugins for dev-time injection.
docs/src/content/docs/guides/development.mdx	Adds “build-tool plugin” as the recommended dev option.
docs/src/content/docs/frameworks/react.mdx	Adds Vite-plugin approach for React dev mode.
docs/src/content/docs/examples/todo-react.mdx	Updates run instructions to prefer Vite plugin in dev.
docs/src/content/docs/examples/nextjs-proxy.mdx	Updates structure + dev guidance for Next integration.
CLAUDE.md	Documents new `plugins/` packages and repo conventions around mirroring gateway logic.
.release-please-manifest.json	Adds plugin package version tracking entries.
.github/workflows/sdk.yml	Adds `plugins/**` to CI trigger paths.
.github/workflows/release-sdk.yml	Adds tagging + publish steps for `@rep-protocol/vite` and `@rep-protocol/next`.

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

examples/nextjs-proxy/package.json:25

@rep-protocol/next is used by runtime app code (layout imports RepScript, API route re-exports GET). Putting it in devDependencies can break production installs that omit dev deps. Move it to dependencies (or adjust the example to avoid runtime imports in prod).

  "devDependencies": {
    "@rep-protocol/cli": "^0.1.11",
    "@rep-protocol/next": "^0.1.11",
    "@types/node": "^22.0.0",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "typescript": "^5.4.0"

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

plugins/vite/src/index.ts

+        res.setHeader('Content-Type', 'application/json');
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.end(body);


plugins/next/src/session-key.ts

plugins/next/src/guardrails.ts

@@ -0,0 +1,92 @@
+/**
+ * Guardrails — secret detection for REP Vite plugin.


.release-please-manifest.json

+  "plugins/vite": "0.1.11",
+  "plugins/next": "0.1.11",


docs/src/content/docs/guides/installation.mdx

docs/src/content/docs/guides/development.mdx

+  ```ts
+  // vite.config.ts
+  import { repPlugin } from '@rep-protocol/vite';
+
+  export default defineConfig({
+    plugins: [repPlugin()],
+  });


docs/src/content/docs/guides/development.mdx

docs/src/content/docs/frameworks/react.mdx

+  ```ts
+  // vite.config.ts
+  import { repPlugin } from '@rep-protocol/vite';
+
+  export default defineConfig({
+    plugins: [react(), repPlugin()],
+  });
+  ```


examples/todo-react/package.json

- Add missing imports in doc code snippets (defineConfig, ReactNode) - Remove Access-Control-Allow-Origin: * from session-key endpoints (same-origin in normal dev, wildcard is unnecessary attack surface) - Add react-dom to next plugin devDependencies (fixes peer dep mismatch) - Fix guardrails.ts header in next plugin (said "Vite" instead of "Next.js") - Soften "matches exactly" comment on payload.ts — injected_at timestamp precision differs (JS ms vs Go ns) but SRI is self-consistent - Fix CLAUDE.md workspace comment (listed examples/* which isn't in workspace)

olamide226 added 3 commits March 16, 2026 21:23

Copilot AI review requested due to automatic review settings March 17, 2026 02:06

Copilot started reviewing on behalf of olamide226 March 17, 2026 02:07 View session

Merge branch 'main' into feat/vite-plugin

c8d65e5

Copilot AI reviewed Mar 17, 2026

View reviewed changes

remove examples from workspace

506199f

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings March 17, 2026 02:16

Copilot started reviewing on behalf of olamide226 March 17, 2026 02:17 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

olamide226 merged commit b99e881 into main Mar 17, 2026
9 checks passed

olamide226 deleted the feat/vite-plugin branch March 17, 2026 02:33

github-actions bot mentioned this pull request Mar 17, 2026

chore(main): release #40

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add @rep-protocol/vite and @rep-protocol/next plugins#39

feat: add @rep-protocol/vite and @rep-protocol/next plugins#39
olamide226 merged 6 commits intomainfrom
feat/vite-plugin

olamide226 commented Mar 17, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,92 @@
		/**
		* Guardrails — secret detection for REP Vite plugin.

Conversation

olamide226 commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Security

Changes

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

olamide226 commented Mar 17, 2026 •

edited

Loading