@aryanbansal-launch/edge-utils 0.1.12 → 0.1.13

package/bin/launch-edge-local.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Shortcut for: npx launch-init local
+ */
+process.argv.splice(2, 0, 'local');
+import('./launch-init.js').catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/bin/launch-edge-test-local.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Runs `wrangler dev` using the Wrangler bundled with @aryanbansal-launch/edge-utils.
+ * Same as `npx wrangler dev`; extra args are passed through (e.g. --port 8788).
+ */
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+let wranglerBin;
+try {
+  wranglerBin = require.resolve('wrangler/bin/wrangler.js');
+} catch {
+  console.error(
+    'Could not resolve wrangler. Reinstall @aryanbansal-launch/edge-utils (it bundles wrangler).'
+  );
+  process.exit(1);
+}
+
+const cwd = process.cwd();
+const wranglerToml = path.join(cwd, 'wrangler.toml');
+if (!fs.existsSync(wranglerToml)) {
+  console.error(
+    'No wrangler.toml in the current directory.\n' +
+      `  cwd: ${cwd}\n` +
+      '  Run this from your project root (where wrangler.toml lives), or run the local wizard first:\n' +
+      '  npx launch-edge-local'
+  );
+  process.exit(1);
+}
+
+const extraArgs = process.argv.slice(2);
+const child = spawn(process.execPath, [wranglerBin, 'dev', ...extraArgs], {
+  stdio: 'inherit',
+  cwd,
+  env: process.env,
+});
+
+child.on('error', (err) => {
+  console.error(err);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/launch-help.js

@@ -66,6 +66,8 @@ ${colors.bright}${colors.green}1. Security & Access Control${colors.reset}
           password: string,
           realm?: string
         }
+    ${colors.dim}Hostname match:${colors.reset} URL host, Host header, or X-Forwarded-Host
+      (use with local Wrangler + rewriteRequestToOrigin)
     ${colors.dim}Returns:${colors.reset} Promise<Response> | null
     ${colors.dim}Example:${colors.reset}
       const auth = await protectWithBasicAuth(request, {
@@ -148,6 +150,14 @@ ${colors.bright}${colors.green}5. Response Utilities${colors.reset}
     ${colors.dim}Example:${colors.reset}
       return passThrough(request);
 
+  ${colors.cyan}rewriteRequestToOrigin(request, backendOrigin)${colors.reset}
+    Rewrite request URL to your local app (used by functions/dev-worker.edge.js)
+    ${colors.dim}Parameters:${colors.reset}
+      - request: Request object
+      - backendOrigin: string (e.g. http://127.0.0.1:3000 from BACKEND_URL)
+    ${colors.dim}Returns:${colors.reset} Request
+    ${colors.dim}Note:${colors.reset} Sets X-Forwarded-Host when host changes (Basic Auth + localhost)
+
 ${colors.bright}${colors.green}6. Configuration${colors.reset}
 
   ${colors.cyan}generateLaunchConfig(options)${colors.reset}
@@ -177,6 +187,34 @@ ${colors.dim}──────────────────────
     Configure: redirects, rewrites, cache priming
     Supports bulk import from CSV/JSON files
 
+${colors.bright}${colors.yellow}🧪 LOCAL TESTING (Wrangler / Miniflare)${colors.reset}
+${colors.dim}────────────────────────────────────────────────────────────────────${colors.reset}
+
+  ${colors.cyan}npx create-launch-edge local${colors.reset}
+    Interactive wizard: pick a preset (redirect, JSON, basic auth, bots, Next.js RSC)
+    Writes or updates functions/[proxy].edge.js; creates dev-worker.edge.js + wrangler.toml if missing
+    ${colors.dim}Alias:${colors.reset} ${colors.cyan}npx launch-edge-local${colors.reset} (same as above)
+
+  ${colors.cyan}npx launch-edge-test-local${colors.reset}
+    Starts ${colors.dim}wrangler dev${colors.reset} using the Wrangler bundled with this package
+    Run from ${colors.bright}project root${colors.reset} (directory that contains wrangler.toml)
+    ${colors.dim}Extra args pass through:${colors.reset} --port 8788
+    ${colors.dim}Example:${colors.reset} npx launch-edge-test-local --var BACKEND_URL=http://127.0.0.1:5173
+
+  ${colors.bright}Typical flow${colors.reset}
+    1. ${colors.cyan}npx create-launch-edge local${colors.reset}  → choose preset, confirm overwrite if asked
+    2. Start your app on the port in ${colors.dim}BACKEND_URL${colors.reset} (see wrangler.toml; default 3000)
+    3. ${colors.cyan}npx launch-edge-test-local${colors.reset}
+    4. Open the URL Wrangler prints (often ${colors.dim}http://localhost:8787${colors.reset}) + path from the wizard
+
+  ${colors.bright}Quick checks${colors.reset}
+    ${colors.dim}•${colors.reset} JSON preset: open /api/edge-ping
+    ${colors.dim}•${colors.reset} Redirect preset: open the legacy path; expect 301
+    ${colors.dim}•${colors.reset} Basic auth preset: browser prompt (e.g. demo / demo); use hostnameIncludes localhost
+    ${colors.dim}•${colors.reset} Bots: ${colors.dim}curl -A "GPTBot" http://localhost:8787/${colors.reset} → 403
+
+  ${colors.bright}Before publishing${colors.reset}  ${colors.dim}npm run build${colors.reset} in this package so dist/ matches src/
+
   ${colors.cyan}npx launch-help${colors.reset}
     Display this help guide
 

package/bin/launch-init.js

@@ -2,18 +2,28 @@
 
 import fs from 'fs';
 import path from 'path';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const invokedAsLocal = path.basename(__filename) === 'launch-edge-local.js';
 
 const functionsDir = path.join(process.cwd(), 'functions');
 const edgeFile = path.join(functionsDir, '[proxy].edge.js');
+const devWorkerFile = path.join(functionsDir, 'dev-worker.edge.js');
+const wranglerTomlPath = path.join(process.cwd(), 'wrangler.toml');
 
-// Simple ANSI colors for better terminal output
 const colors = {
   reset: '\x1b[0m',
   bright: '\x1b[1m',
+  dim: '\x1b[2m',
   green: '\x1b[32m',
   yellow: '\x1b[33m',
   cyan: '\x1b[36m',
-  blue: '\x1b[34m'
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m'
 };
 
 const template = `
@@ -84,12 +94,215 @@ export default async function handler(request, context) {
 }
 `.trim();
 
+const devWorkerTemplate = `
+import { rewriteRequestToOrigin } from "@aryanbansal-launch/edge-utils";
+import handler from "./[proxy].edge.js";
+
+/**
+ * Wrangler / Miniflare entry: rewrites the request URL to your local app (BACKEND_URL)
+ * before running your Launch edge handler. Generated by launch-init.
+ */
+export default {
+  async fetch(request, env, ctx) {
+    const req = rewriteRequestToOrigin(request, env.BACKEND_URL);
+    return handler(req, {});
+  }
+};
+`.trim();
+
+const wranglerTemplate = `name = "launch-edge-local-dev"
+main = "functions/dev-worker.edge.js"
+compatibility_date = "2024-01-01"
+
+[vars]
+BACKEND_URL = "http://127.0.0.1:3000"
+`;
+
+/** Presets for: npx launch-init local */
+const LOCAL_PRESETS = [
+  {
+    id: 'redirect',
+    title: 'Redirect — path match → new path (301)',
+    testPath: '/legacy-demo',
+    hint: 'Open /legacy-demo — you should be redirected to /redirect-target',
+    template: `
+import { passThrough, redirectIfMatch } from "@aryanbansal-launch/edge-utils";
+
+/** Local test: redirect preset (generated by launch-init local) */
+export default async function handler(request, context) {
+  const redirectResponse = redirectIfMatch(request, {
+    path: "/legacy-demo",
+    to: "/redirect-target",
+    status: 301
+  });
+  if (redirectResponse) return redirectResponse;
+
+  return passThrough(request);
+}
+`.trim()
+  },
+  {
+    id: 'json',
+    title: 'JSON — edge-only API route',
+    testPath: '/api/edge-ping',
+    hint: 'Open /api/edge-ping — JSON is served from the Worker (no backend needed for this path)',
+    template: `
+import { jsonResponse, passThrough } from "@aryanbansal-launch/edge-utils";
+
+/** Local test: JSON preset (generated by launch-init local) */
+export default async function handler(request, context) {
+  const url = new URL(request.url);
+  if (url.pathname === "/api/edge-ping") {
+    return jsonResponse({ ok: true, source: "edge-utils", path: url.pathname });
+  }
+  return passThrough(request);
+}
+`.trim()
+  },
+  {
+    id: 'basic-auth',
+    title: 'Basic auth — password gate (uses localhost host)',
+    testPath: '/',
+    hint: 'Browser will prompt for user/pass (demo / demo). Use hostnameIncludes "localhost" in dev.',
+    template: `
+import { passThrough, protectWithBasicAuth } from "@aryanbansal-launch/edge-utils";
+
+/** Local test: basic auth preset (generated by launch-init local) */
+export default async function handler(request, context) {
+  const authResponse = await protectWithBasicAuth(request, {
+    hostnameIncludes: "localhost",
+    username: "demo",
+    password: "demo",
+    realm: "Local edge test"
+  });
+  if (authResponse && authResponse.status === 401) return authResponse;
+
+  return passThrough(request);
+}
+`.trim()
+  },
+  {
+    id: 'bots',
+    title: 'Block AI crawlers — block common bot user-agents',
+    testPath: '/',
+    hint: 'Normal browser works. Test with curl -A "GPTBot" http://localhost:8787/ — should be blocked',
+    template: `
+import { passThrough, blockAICrawlers } from "@aryanbansal-launch/edge-utils";
+
+/** Local test: bot block preset (generated by launch-init local) */
+export default async function handler(request, context) {
+  const botResponse = blockAICrawlers(request);
+  if (botResponse) return botResponse;
+
+  return passThrough(request);
+}
+`.trim()
+  },
+  {
+    id: 'rsc',
+    title: 'Next.js RSC — strip RSC header on selected paths (advanced)',
+    testPath: '/your-rsc-page',
+    hint: 'Adjust affectedPaths to match a route in your app; used when RSC headers break local proxy',
+    template: `
+import { passThrough, handleNextJS_RSC } from "@aryanbansal-launch/edge-utils";
+
+/** Local test: Next.js RSC preset (generated by launch-init local) */
+export default async function handler(request, context) {
+  const rscResponse = await handleNextJS_RSC(request, {
+    affectedPaths: ["/your-rsc-page"]
+  });
+  if (rscResponse) return rscResponse;
+
+  return passThrough(request);
+}
+`.trim()
+  }
+];
+
+function printLocalInstructions(preset) {
+  console.log(`\n${colors.bright}${colors.green}Local test — next steps${colors.reset}\n`);
+  console.log(`  ${colors.cyan}1.${colors.reset} Start your app on the same origin as ${colors.cyan}BACKEND_URL${colors.reset} in wrangler.toml (default ${colors.yellow}http://127.0.0.1:3000${colors.reset}).`);
+  console.log(`  ${colors.cyan}2.${colors.reset} From project root: ${colors.bright}npx launch-edge-test-local${colors.reset}`);
+  console.log(`     ${colors.dim}(same as ${colors.reset}${colors.bright}npx wrangler dev${colors.reset}${colors.dim}; extra args pass through, e.g. --port 8788)${colors.reset}`);
+  console.log(`  ${colors.cyan}3.${colors.reset} Open ${colors.bright}http://localhost:8787${preset.testPath}${colors.reset} ${colors.dim}(Wrangler prints the port if different)${colors.reset}`);
+  console.log(`\n  ${colors.magenta}Try:${colors.reset} ${preset.hint}\n`);
+}
+
+async function localWizard() {
+  console.log(`\n${colors.bright}${colors.cyan}Edge utilities — test locally (Wrangler / Miniflare)${colors.reset}\n`);
+
+  const packageJsonPath = path.join(process.cwd(), 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    console.log(`${colors.red}❌ No package.json here.${colors.reset} Run from your project root.\n`);
+    process.exit(1);
+  }
+
+  const rl = readline.createInterface({ input, output });
+
+  try {
+    console.log(`${colors.bright}Pick what you want to try:${colors.reset}\n`);
+    LOCAL_PRESETS.forEach((p, i) => {
+      console.log(`  ${colors.cyan}${i + 1}.${colors.reset} ${p.title}`);
+    });
+    console.log('');
+
+    const raw = await rl.question(`${colors.bright}Enter 1–${LOCAL_PRESETS.length} [1]: ${colors.reset}`);
+    const n = parseInt(raw || '1', 10);
+    if (Number.isNaN(n) || n < 1 || n > LOCAL_PRESETS.length) {
+      console.log(`${colors.red}Invalid choice.${colors.reset}\n`);
+      process.exit(1);
+    }
+    const preset = LOCAL_PRESETS[n - 1];
+
+    let overwrite = true;
+    if (fs.existsSync(edgeFile)) {
+      const ans = await rl.question(
+        `${colors.yellow}Overwrite functions/[proxy].edge.js?${colors.reset} [y/N]: `
+      );
+      overwrite = /^y(es)?$/i.test(ans.trim());
+      if (!overwrite) {
+        console.log(`\n${colors.blue}Skipped writing [proxy].edge.js.${colors.reset} Still ensuring dev-worker + wrangler…\n`);
+      }
+    }
+
+    if (!fs.existsSync(functionsDir)) {
+      fs.mkdirSync(functionsDir, { recursive: true });
+      console.log(`${colors.green}✨${colors.reset} Created /functions`);
+    }
+
+    if (overwrite) {
+      fs.writeFileSync(edgeFile, preset.template + '\n');
+      console.log(`${colors.green}✨${colors.reset} Wrote functions/[proxy].edge.js (${preset.id})`);
+    }
+
+    if (!fs.existsSync(devWorkerFile)) {
+      fs.writeFileSync(devWorkerFile, devWorkerTemplate + '\n');
+      console.log(`${colors.green}✨${colors.reset} Created /functions/dev-worker.edge.js`);
+    } else {
+      console.log(`${colors.blue}ℹ${colors.reset}  /functions/dev-worker.edge.js already exists`);
+    }
+
+    if (!fs.existsSync(wranglerTomlPath)) {
+      fs.writeFileSync(wranglerTomlPath, wranglerTemplate);
+      console.log(`${colors.green}✨${colors.reset} Created wrangler.toml`);
+    } else {
+      console.log(`${colors.blue}ℹ${colors.reset}  wrangler.toml already exists (left unchanged)`);
+    }
+
+    printLocalInstructions(preset);
+  } catch (err) {
+    console.error(`${colors.red}Error:${colors.reset}`, err.message);
+    process.exit(1);
+  } finally {
+    rl.close();
+  }
+}
+
 async function init() {
   console.log(`\n${colors.bright}${colors.cyan}🚀 create-launch-edge: Contentstack Launch Initializer${colors.reset}\n`);
 
   let actionsTaken = 0;
 
-  // 1. Root level check: Look for package.json
   const packageJsonPath = path.join(process.cwd(), 'package.json');
   if (!fs.existsSync(packageJsonPath)) {
     console.log(`${colors.red}❌ Error: Root directory not detected.${colors.reset}`);
@@ -100,7 +313,6 @@ async function init() {
   }
 
   try {
-    // 2. Folder existence check
     if (!fs.existsSync(functionsDir)) {
       fs.mkdirSync(functionsDir, { recursive: true });
       console.log(`${colors.green}✨ New:${colors.reset} Created /functions directory`);
@@ -109,7 +321,6 @@ async function init() {
       console.log(`${colors.blue}ℹ️  Existing:${colors.reset} /functions directory already found`);
     }
 
-    // 3. File existence check (don't overwrite user's work)
     if (!fs.existsSync(edgeFile)) {
       fs.writeFileSync(edgeFile, template + '\n');
       console.log(`${colors.green}✨ New:${colors.reset} Created /functions/[proxy].edge.js`);
@@ -118,7 +329,22 @@ async function init() {
       console.log(`${colors.blue}ℹ️  Existing:${colors.reset} /functions/[proxy].edge.js already found`);
     }
 
-    // Final Summary Messages based on the state
+    if (!fs.existsSync(devWorkerFile)) {
+      fs.writeFileSync(devWorkerFile, devWorkerTemplate + '\n');
+      console.log(`${colors.green}✨ New:${colors.reset} Created /functions/dev-worker.edge.js`);
+      actionsTaken++;
+    } else {
+      console.log(`${colors.blue}ℹ️  Existing:${colors.reset} /functions/dev-worker.edge.js already found`);
+    }
+
+    if (!fs.existsSync(wranglerTomlPath)) {
+      fs.writeFileSync(wranglerTomlPath, wranglerTemplate);
+      console.log(`${colors.green}✨ New:${colors.reset} Created wrangler.toml (local edge dev)`);
+      actionsTaken++;
+    } else {
+      console.log(`${colors.blue}ℹ️  Existing:${colors.reset} wrangler.toml already found — skipped creating default`);
+    }
+
     if (actionsTaken === 0) {
       console.log(`\n${colors.bright}${colors.blue}🏁 Everything is already set up!${colors.reset}`);
       console.log(`No changes were made to your existing files.`);
@@ -130,8 +356,10 @@ async function init() {
     console.log(`\n${colors.bright}Next Steps:${colors.reset}`);
     console.log(`1. Open ${colors.cyan}functions/[proxy].edge.js${colors.reset}`);
     console.log(`2. Customize your redirects, auth, and RSC paths`);
-    console.log(`3. Deploy your project to Contentstack Launch\n`);
-    
+    console.log(`3. Deploy your project to Contentstack Launch`);
+    console.log(`4. Test edge locally: ${colors.bright}npx launch-edge-local${colors.reset} (wizard), then ${colors.bright}npx launch-edge-test-local${colors.reset}`);
+    console.log(`   (${colors.dim}Wrangler is bundled; run app on BACKEND_URL for pass-through routes)${colors.reset}\n`);
+
     console.log(`${colors.blue}Documentation:${colors.reset} https://github.com/AryanBansal-launch/launch-edge-utils#readme\n`);
   } catch (error) {
     console.error(`\n${colors.red}❌ Error during setup:${colors.reset}`, error.message);
@@ -139,4 +367,18 @@ async function init() {
   }
 }
 
-init();
+const args = process.argv.slice(2);
+const runLocal =
+  invokedAsLocal ||
+  args[0] === 'local' ||
+  args.includes('--local');
+
+async function main() {
+  if (runLocal) {
+    await localWizard();
+  } else {
+    await init();
+  }
+}
+
+main();

package/dist/auth/basic-auth.js

@@ -1,6 +1,13 @@
 export function protectWithBasicAuth(request, options) {
     const url = new URL(request.url);
-    if (!url.hostname.includes(options.hostnameIncludes)) {
+    // Match URL host, Host header, or X-Forwarded-Host (set by rewriteRequestToOrigin when
+    // the browser hits localhost:8787 but the request URL is rewritten to 127.0.0.1:3000).
+    const hostHeader = request.headers.get("host")?.split(":")[0] ?? "";
+    const forwardedHost = request.headers.get("x-forwarded-host")?.split(":")[0] ?? "";
+    const hostMatches = url.hostname.includes(options.hostnameIncludes) ||
+        hostHeader.includes(options.hostnameIncludes) ||
+        forwardedHost.includes(options.hostnameIncludes);
+    if (!hostMatches) {
         return null;
     }
     const authHeader = request.headers.get("Authorization");

package/dist/dev/rewrite-origin.js

@@ -0,0 +1,27 @@
+/**
+ * Rewrites the request URL so its origin (and optional path prefix from `backendOrigin`)
+ * points at your local app. Use with Wrangler / Miniflare so `passThrough(request)` and
+ * other `fetch(request)` calls reach the dev server instead of the Worker dev port.
+ *
+ * When the incoming host differs from the backend host, sets `X-Forwarded-Host` to the
+ * original `incoming.host` (unless already present) so helpers like `protectWithBasicAuth`
+ * can still match `localhost` while the URL points at `127.0.0.1`.
+ */
+export function rewriteRequestToOrigin(request, backendOrigin) {
+    const base = new URL(backendOrigin);
+    const incoming = new URL(request.url);
+    const prefix = base.pathname === "/" ? "" : base.pathname.replace(/\/$/, "");
+    const path = `${prefix}${incoming.pathname}${incoming.search}${incoming.hash}`;
+    const target = new URL(path, base.origin);
+    const headers = new Headers(request.headers);
+    if (incoming.hostname !== target.hostname && !headers.has("x-forwarded-host")) {
+        headers.set("x-forwarded-host", incoming.host);
+    }
+    return new Request(target.toString(), {
+        method: request.method,
+        headers,
+        body: request.body,
+        redirect: request.redirect,
+        ...(request.body != null ? { duplex: "half" } : {}),
+    });
+}

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from "./dev/rewrite-origin.js";
 export * from "./response/json.js";
 export * from "./response/passthrough.js";
 export * from "./redirect/redirect.js";

package/examples/local-dev/node_modules/.package-lock.json

@@ -0,0 +1,23 @@
+{
+  "name": "local-dev-example",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "../..": {
+      "name": "@aryanbansal-launch/edge-utils",
+      "version": "0.1.5",
+      "license": "MIT",
+      "dependencies": {
+        "wrangler": "^3.114.0"
+      },
+      "bin": {
+        "launch-edge-local": "bin/launch-edge-local.js",
+        "launch-init": "bin/launch-init.js"
+      }
+    },
+    "node_modules/@aryanbansal-launch/edge-utils": {
+      "resolved": "../..",
+      "link": true
+    }
+  }
+}

package/examples/local-dev/package-lock.json

@@ -0,0 +1,29 @@
+{
+  "name": "local-dev-example",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "local-dev-example",
+      "dependencies": {
+        "@aryanbansal-launch/edge-utils": "file:../.."
+      }
+    },
+    "../..": {
+      "name": "@aryanbansal-launch/edge-utils",
+      "version": "0.1.5",
+      "license": "MIT",
+      "dependencies": {
+        "wrangler": "^3.114.0"
+      },
+      "bin": {
+        "launch-edge-local": "bin/launch-edge-local.js",
+        "launch-init": "bin/launch-init.js"
+      }
+    },
+    "node_modules/@aryanbansal-launch/edge-utils": {
+      "resolved": "../..",
+      "link": true
+    }
+  }
+}

package/examples/local-dev/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "local-dev-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "launch-edge-test-local"
+  },
+  "dependencies": {
+    "@aryanbansal-launch/edge-utils": "file:../.."
+  }
+}

package/examples/local-dev/sample-handler.ts

@@ -0,0 +1,18 @@
+import { jsonResponse, passThrough } from "@aryanbansal-launch/edge-utils";
+
+/**
+ * Minimal Launch-style handler for local Miniflare testing.
+ */
+export default async function handler(request: Request, _context: unknown) {
+  const url = new URL(request.url);
+
+  if (url.pathname === "/api/edge-ping") {
+    return jsonResponse({
+      ok: true,
+      source: "edge-utils-example",
+      path: url.pathname,
+    });
+  }
+
+  return passThrough(request);
+}

package/examples/local-dev/worker.ts

@@ -0,0 +1,11 @@
+import { rewriteRequestToOrigin } from "@aryanbansal-launch/edge-utils";
+import handler from "./sample-handler.js";
+
+type Env = { BACKEND_URL: string };
+
+export default {
+  async fetch(request: Request, env: Env, _ctx: unknown) {
+    const req = rewriteRequestToOrigin(request, env.BACKEND_URL);
+    return handler(req, {});
+  },
+};

package/examples/local-dev/wrangler.toml

@@ -0,0 +1,6 @@
+name = "edge-utils-local-dev-example"
+main = "worker.ts"
+compatibility_date = "2024-01-01"
+
+[vars]
+BACKEND_URL = "http://127.0.0.1:3000"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryanbansal-launch/edge-utils",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -15,11 +15,16 @@
   "bin": {
     "create-launch-edge": "bin/launch-init.js",
     "launch-config": "bin/launch-config.js",
-    "launch-help": "bin/launch-help.js"
+    "launch-help": "bin/launch-help.js",
+    "launch-edge-local": "./bin/launch-edge-local.js",
+    "launch-edge-test-local": "./bin/launch-edge-test-local.js"
   },
   "exports": {
     ".": "./dist/index.js"
   },
+  "dependencies": {
+    "wrangler": "^3.114.0"
+  },
   "files": [
     "dist",
     "bin",

package/readme.md

@@ -10,12 +10,26 @@ A comprehensive toolkit for [Contentstack Launch](https://www.contentstack.com/d
 ## 📋 Table of Contents
 
 - [Quick Start](#-quick-start)
+- [User journey](#-user-journey)
 - [Usage Flow](#-usage-flow)
 - [Complete API Reference](#-complete-api-reference)
 - [Real-World Examples](#-real-world-examples)
 - [CLI Commands](#-cli-commands)
 - [Platform Support](#-platform-support)
 
+A lightweight, high-performance toolkit specifically designed for **Contentstack Launch Edge Functions**. Speed up your development with production-ready utilities for security, authentication, routing, and Next.js compatibility—all optimized to run at the edge.
+
+---
+
+## ✨ Features
+
+- 🛡️ **Security First**: Block AI crawlers and manage IP access with ease.
+- 🔐 **Edge Auth**: Implement Basic Auth directly at the edge for specific hostnames.
+- 📍 **Geo-Aware**: Easily extract location data from request headers.
+- ⚛️ **Next.js Ready**: Built-in fixes for RSC header issues on Launch proxies.
+- 🔀 **Smart Routing**: Declarative redirects based on path and method.
+- ⚡ **Lean edge code**: No runtime deps inside the utilities you import at the edge; the npm package bundles **Wrangler** so local testing works without a separate install.
+
 ---
 
 ## ⚡ Quick Start
@@ -51,6 +65,98 @@ npx launch-help
 
 ---
 
+## 🧭 User journey
+
+Step-by-step paths for the three most common goals. Adjust paths and ports to match your app.
+
+### Scenario 1: Use a particular edge utility in production
+
+You want **one or more** helpers from this library (for example Basic Auth, bot blocking, or `redirectIfMatch`) in your **Contentstack Launch** edge handler.
+
+1. **Install the package** (from your project root, next to `package.json`):
+   ```bash
+   npm install @aryanbansal-launch/edge-utils
+   ```
+2. **Scaffold the edge function file** (skip if `functions/[proxy].edge.js` already exists):
+   ```bash
+   npx create-launch-edge
+   ```
+   This creates `functions/` and a starter `functions/[proxy].edge.js` if missing.
+3. **Open** `functions/[proxy].edge.js` in your editor.
+4. **Import** only what you need from the package, for example:
+   ```javascript
+   import { blockAICrawlers, redirectIfMatch, passThrough } from "@aryanbansal-launch/edge-utils";
+   ```
+5. **Wire your handler**: call each utility in order; when a function returns a `Response`, return it immediately; otherwise continue until `passThrough(request)` (or your own `fetch`) sends traffic to the origin.
+6. **Review the API** (optional):
+   ```bash
+   npx launch-help
+   ```
+7. **Deploy** your site through **Contentstack Launch** using your normal workflow (CLI or UI). Launch runs `functions/[proxy].edge.js` at the edge before traffic hits your app.
+
+---
+
+### Scenario 2: Test edge utilities locally (Wrangler / Miniflare)
+
+You want to **try** a preset (redirect, JSON route, basic auth, bots, or Next.js RSC) **on your machine** before deploying.
+
+1. **Install the package**:
+   ```bash
+   npm install @aryanbansal-launch/edge-utils
+   ```
+2. **One-time scaffold** (creates `functions/dev-worker.edge.js` and `wrangler.toml` if they are missing; safe to run again):
+   ```bash
+   npx create-launch-edge
+   ```
+3. **Start the local wizard** (pick a preset interactively):
+   ```bash
+   npx launch-edge-local
+   ```
+   Or:
+   ```bash
+   npx create-launch-edge local
+   ```
+4. **Enter a number** `1`–`5` for the preset. If `[proxy].edge.js` already exists, confirm overwrite when prompted (`y`).
+5. **Align the backend URL** with your app: open `wrangler.toml` and set `[vars] BACKEND_URL` to your dev server (default `http://127.0.0.1:3000`). Change the port if your app uses something else (for example `5173` for Vite).
+6. **Start your app** in another terminal (for example `npm run dev`) so it listens on that host/port.
+7. **Start the local Worker** from the **same project root** as `wrangler.toml`:
+   ```bash
+   npx launch-edge-test-local
+   ```
+   This runs the bundled `wrangler dev`. Extra args are supported, e.g. `npx launch-edge-test-local --port 8788` or `--var BACKEND_URL=http://127.0.0.1:5173`.
+8. **Open the URL** Wrangler prints (often `http://localhost:8787`) and the path the wizard suggests (for example `/api/edge-ping` for the JSON preset).
+9. **Optional checks**: see `npx launch-help` under **Local testing** for curl / bot tests.
+
+**Note:** After you change **source** in `@aryanbansal-launch/edge-utils`, run `npm run build` in the package before linking or publishing so `dist/` matches `src/`.
+
+---
+
+### Scenario 3: Redirects, rewrites, and cache priming (`launch.json`)
+
+You want **config-driven** redirects, rewrites, or cache priming **without** coding them in the edge file—Launch reads **`launch.json`** at the project root.
+
+1. **Install the package** (includes the `launch-config` CLI):
+   ```bash
+   npm install @aryanbansal-launch/edge-utils
+   ```
+2. **Run the interactive configurator** from your **project root**:
+   ```bash
+   npx launch-config
+   ```
+3. **Follow the prompts** to add:
+   - **Redirects** (one-by-one or bulk),
+   - **Rewrites** (source path → destination),
+   - **Cache priming URLs** (relative paths only, as required by Launch).
+4. **Bulk import** (optional): choose CSV or JSON when the CLI asks, and provide a file path to import many redirects at once.
+5. **Confirm** `launch.json` is created or updated at the **root** of your Launch project (alongside `package.json`).
+6. **Deploy** through Contentstack Launch so the new configuration is applied.
+
+**Alternative (code):** you can build `launch.json` in code with `generateLaunchConfig` from this package and write the file yourself—see the **Configuration** subsection in the [Complete API Reference](#-complete-api-reference) below.
+
+**Using both:** keep bulk static rules in `launch.json` and use `functions/[proxy].edge.js` for dynamic logic (geo, cookies, A/B tests). They can coexist on the same project.
+
+---
+
 ## 🔄 Usage Flow
 
 ### Understanding Edge Functions
@@ -291,7 +397,7 @@ Add Basic Authentication to protect environments.
 **Parameters:**
 - `request` (Request) - The incoming request object
 - `options` (object)
-  - `hostnameIncludes` (string) - Protect URLs containing this hostname
+  - `hostnameIncludes` (string) - Substring match against the request URL hostname, the `Host` header, or `X-Forwarded-Host` (without port). `rewriteRequestToOrigin` sets `X-Forwarded-Host` when the URL is rewritten so `hostnameIncludes: "localhost"` works with `npx launch-edge-test-local` while `BACKEND_URL` uses `127.0.0.1`.
   - `username` (string) - Username for authentication
   - `password` (string) - Password for authentication
   - `realm` (string, optional) - Auth realm name (default: "Protected Area")
@@ -299,7 +405,7 @@ Add Basic Authentication to protect environments.
 **Returns:** `Promise<Response> | null`
 - Returns `401 Unauthorized` if auth fails
 - Returns authenticated response if credentials valid
-- Returns `null` if hostname doesn't match
+- Returns `null` if neither the URL hostname nor the `Host` header matches `hostnameIncludes`
 
 **Example:**
 ```javascript
@@ -922,6 +1028,60 @@ export default async function handler(request, context) {
 
 ---
 
+## 🧪 Local testing (Wrangler / Miniflare)
+
+Test your `functions/[proxy].edge.js` chain **locally** without deploying. Wrangler’s dev server uses **Miniflare**, which runs a Workers-compatible runtime on your machine.
+
+### Interactive wizard (easiest)
+
+From your **project root** (where `package.json` lives):
+
+```bash
+npx create-launch-edge local
+```
+
+Or the short alias:
+
+```bash
+npx launch-edge-local
+```
+
+You’ll get a numbered menu (redirect, JSON route, basic auth, bot block, or Next.js RSC). Pick one; the CLI writes `functions/[proxy].edge.js` for that scenario, ensures `dev-worker.edge.js` and `wrangler.toml` exist, then prints a short checklist (start your app, run the dev server, open the test URL). **Wrangler** is installed automatically as a dependency of this package. If `[proxy].edge.js` already exists, you’re asked before it’s overwritten.
+
+### Start the local Worker (no `wrangler` typing)
+
+From the **project root** (next to `wrangler.toml`):
+
+```bash
+npx launch-edge-test-local
+```
+
+This runs the bundled `wrangler dev` for you. Extra arguments are forwarded (for example `--port 8788` or `--var BACKEND_URL=http://127.0.0.1:5173`). It is equivalent to `npx wrangler dev`.
+
+### Manual setup
+
+1. Run `npx create-launch-edge` (or ensure you have `functions/dev-worker.edge.js` and `wrangler.toml`). The init script creates these only if they are missing; it does **not** overwrite an existing `wrangler.toml`.
+2. In `wrangler.toml`, set `[vars] BACKEND_URL` to your local app origin (default `http://127.0.0.1:3000`). Wrangler is **already a dependency** of `@aryanbansal-launch/edge-utils`—you do not need `npm install -D wrangler` separately unless you want a different version pinned at the project root.
+3. Start your app on that port, then run `npx launch-edge-test-local` (or `npx wrangler dev`) from the **project root**.
+4. Open the URL Wrangler prints (for example `http://localhost:8787`). Traffic flows: browser → local Worker → `rewriteRequestToOrigin` → your handler → `fetch` to `BACKEND_URL`.
+
+Override the backend URL for a single session if needed:
+
+```bash
+npx launch-edge-test-local --var BACKEND_URL=http://127.0.0.1:5173
+```
+
+### In-repo example
+
+See [`examples/local-dev/`](examples/local-dev/) for a minimal runnable project (`npm install` in that folder, then `npm run dev` while a server listens on port 3000).
+
+### Caveats
+
+- **Hostname-based rules** (`protectWithBasicAuth`): matching uses both the request URL host and the `Host` header, so `hostnameIncludes: "localhost"` works with `npx launch-edge-test-local` even when the rewritten URL points at `127.0.0.1` (BACKEND_URL).
+- **Geo and client IP** (`getGeoHeaders`, `getClientIP`): these read request headers. Miniflare does not inject Cloudflare `cf` metadata the way production does; values may be empty unless you set headers yourself or configure Wrangler where supported.
+
+---
+
 ## 🛠️ CLI Commands
 
 ### `npx create-launch-edge`
@@ -956,6 +1116,18 @@ Next Steps:
 
 ---
 
+### `npx launch-edge-test-local`
+
+Starts **Wrangler dev** using the Wrangler bundled with this package—no need to type `npx wrangler dev`. Run from the directory that contains `wrangler.toml` (usually your app root).
+
+```bash
+npx launch-edge-test-local
+```
+
+Arguments are passed through to `wrangler dev` (for example `--port 8788` or `--var BACKEND_URL=http://127.0.0.1:5173`).
+
+---
+
 ### `npx launch-config`
 
 Interactive CLI to manage `launch.json` configuration with support for bulk imports.
@@ -1057,6 +1229,27 @@ npx launch-help
 - Return types and examples
 - CLI commands
 - Quick links to documentation
+## 📖 API Reference
+
+### 🧰 Local development
+
+- **`rewriteRequestToOrigin(request, backendOrigin)`**: Builds a new `Request` whose URL points at `backendOrigin` while preserving path, query, and body. Used by `functions/dev-worker.edge.js` so `passThrough` reaches your local server.
+
+### 🛡️ Security
+- **`blockAICrawlers(request, bots?)`**: Blocks common AI crawlers.
+- **`ipAccessControl(request, { allow?, deny? })`**: Simple IP-based firewall.
+
+### 🔐 Authentication
+- **`protectWithBasicAuth(request, options)`**: Prompt for credentials based on hostname.
+
+### 🔀 Redirection
+- **`redirectIfMatch(request, options)`**: Perform SEO-friendly redirects at the edge.
+
+### 📍 Geo Location
+- **`getGeoHeaders(request)`**: Returns an object with `country`, `region`, `city`, `latitude`, `longitude`.
+
+### ⚛️ Next.js
+- **`handleNextJS_RSC(request, { affectedPaths })`**: Resolves RSC header issues on Contentstack Launch.
 
 ---