Local Development — Dev Server and Mock Payloads

During local development you typically don’t have the REP gateway running. The SDK handles this gracefully — rep.get() returns undefined when no payload is present.

Option A: Build-tool plugin (recommended)

The easiest way to get full REP support in development. The plugin injects the same <script id="__rep__"> tag that the gateway produces, so the SDK works identically.

Vite

npm install -D @rep-protocol/vite

vite.config.ts

import { defineConfig } from 'vite';
import { repPlugin } from '@rep-protocol/vite';

export default defineConfig({
  plugins: [repPlugin()],
});

The plugin reads .env.local (configurable via env option), classifies variables, encrypts sensitive vars, and injects the payload into your HTML. Changes to .env.local trigger a full page reload.

# Just run Vite as normal — no second terminal needed
npm run dev

Next.js

npm install -D @rep-protocol/next

app/layout.tsx

import type { ReactNode } from 'react';
import { RepScript } from '@rep-protocol/next';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html>
      <head><RepScript /></head>
      <body>{children}</body>
    </html>
  );
}

// app/api/rep/session-key/route.ts (only needed for SENSITIVE vars)
export { GET } from '@rep-protocol/next/session-key';

RepScript is a React Server Component that renders the REP payload during next dev. It returns null in production — the gateway handles injection in prod. No build-time env vars are baked into the output.

# Just run Next.js as normal — no second terminal needed
npm run dev

Note

Both plugins run guardrails on PUBLIC vars and warn if they look like secrets. Use the strict option to make warnings into errors. Unlike the gateway, they scan csv values whole.

Option B: Default values (simplest)

Use the second argument to rep.get():

const apiUrl = rep.get('API_URL', 'http://localhost:3000');
// In dev: returns 'http://localhost:3000'
// In prod: returns the injected value

This is the simplest approach and works with any framework. No extra configuration needed.

Option C: Mock payload in HTML

Add a <script id="__rep__"> tag to your index.html:

<!-- Only in development — the gateway replaces this in production -->
<script id="__rep__" type="application/json">
{
  "public": {
    "API_URL": "http://localhost:3000",
    "FEATURE_FLAGS": "dark-mode,debug"
  },
  "_meta": {
    "version": "0.1.0",
    "injected_at": "2026-01-01T00:00:00Z",
    "integrity": "hmac-sha256:dev-mode-no-verification",
    "ttl": 0
  }
}
</script>

This gives you the full SDK experience (including rep.verify() and rep.meta()) without the gateway.

Caution

Don’t forget to remove this tag from your production HTML. In production, the gateway injects it automatically.

Option D: CLI dev server (full fidelity)

The rep dev command runs a local gateway that reads your .env file and proxies to your dev server:

With Vite

# Terminal 1: Start Vite dev server
npm run dev
# → Vite running at http://localhost:5173

# Terminal 2: Start REP gateway proxy
rep dev --env .env.local --proxy http://localhost:5173
# → Gateway at http://localhost:8080 → proxies to Vite

Open http://localhost:8080 (the gateway port), not :5173. The gateway injects variables into Vite’s HTML responses.

With static files

# Build first
npm run build

# Serve from dist/ with REP injection
rep dev --env .env.local --static ./dist

.env.local example

REP_PUBLIC_API_URL=http://localhost:3000
REP_PUBLIC_FEATURE_FLAGS=dark-mode,debug
REP_SENSITIVE_ANALYTICS_KEY=test-key-123

CLI dev server options

Flag	Default	Description
-e, --env <path>	.env.local	Path to .env file
-p, --port <number>	8080	Gateway port
--proxy <url>	—	Upstream proxy URL
--static <path>	—	Serve static files (embedded mode)
--hot-reload	false	Enable hot reload
--gateway-bin <path>	auto-detected	Path to gateway binary

Note

When using proxy mode with Vite, access the site through the gateway port (8080), not Vite’s port (5173). Vite’s HMR WebSocket continues to work through the proxy for CSS and module updates.

Using all CLI commands in development

The CLI provides a complete development workflow:

# 1. Validate your manifest
rep validate --manifest .rep.yaml
# ✓ Manifest is valid — 6 variables, 4 settings

# 2. Generate TypeScript types
rep typegen --manifest .rep.yaml --output src/rep.d.ts
# ✓ Generated types for 3 public + 2 sensitive variables

# 3. Start the dev server
rep dev --env .env.local --proxy http://localhost:5173

# 4. Before deployment: scan bundles for leaked secrets
rep lint --dir ./dist
# ✓ No secrets detected in 12 files