fix: use stable bundle name in dev mode to avoid CDN mismatch

.env

@@ -1,4 +1,8 @@
 NEXT_PUBLIC_CLUSTER=mainnet-beta
 
 # Local development is similar as next public preview
-NEXT_PUBLIC_IS_NEXT_PREVIEW=true
+NEXT_PUBLIC_IS_NEXT_PREVIEW=true
+
+# Enable plugin dev mode - uses local builds instead of CDN
+# This allows version bumps without waiting for CDN upload
+NEXT_PUBLIC_IS_PLUGIN_DEV=true

DEVELOPER_NOTES.md

@@ -1,7 +1,38 @@
 # Developer Notes
 
-To develop, `pnpm i && pnpm dev`
-To build, `pnpm build-widget`
+## Quick Start
+
+```bash
+pnpm i
+pnpm dev
+```
+
+## Building
+
+```bash
+pnpm build-widget    # Build versioned bundle (plugin-1.0.x.js) to /public/
+```
+
+## Local Development
+
+The `.env` file has `NEXT_PUBLIC_IS_PLUGIN_DEV=true` which tells the app to 
+load bundles from local `/public/` instead of CDN.
+
+**Workflow:**
+```bash
+pnpm build-widget   # Build once (creates /public/plugin-1.0.x.js)
+pnpm dev            # Homepage loads from localhost, not CDN
+# Bump version, rebuild, still works - loads new version from /public/
+```
+
+## Vercel Previews
+
+Automatically handled:
+- `vercel.json` runs `build-widget` before Next.js build
+- `NEXT_PUBLIC_VERCEL_ENV=preview` is set automatically by Vercel
+- App detects preview mode and loads from preview URL instead of CDN
+
+**Result:** PR previews always test the new code, no CDN needed.
 
 There's a few point of entry for Plugin, and each has specific reasons:
 

src/library.tsx

@@ -16,19 +16,13 @@ const containerId = 'jupiter-plugin-instance';
 const packageJson = require('../package.json');
 const bundleName = `plugin-${packageJson.version}`;
 
-const scriptDomain =
-  (() => {
-    if (!process.env.NEXT_PUBLIC_IS_PLUGIN_DEV) {
-         return null
-    }
-    if (typeof window === 'undefined' || typeof document === 'undefined') return '';
-
-    const url = (document.currentScript as HTMLScriptElement)?.src;
-    if (url) {
-      return new URL(url).origin;
-    }
-    return null;
-  })() || 'https://plugin.jup.ag';
+// In dev/preview: load from local /public (empty string = relative path)
+// In production: load from CDN
+const isLocalDev = process.env.NEXT_PUBLIC_IS_PLUGIN_DEV === 'true';
+const isVercelPreview = process.env.NEXT_PUBLIC_VERCEL_ENV === 'preview';
+const useLocalBundle = isLocalDev || isVercelPreview;
+
+const scriptDomain = useLocalBundle ? '' : 'https://plugin.jup.ag';
 
 async function loadRemote(id: string, href: string, type: 'text/javascript' | 'stylesheet') {
   return new Promise((res, rej) => {

vercel.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "buildCommand": "pnpm build-widget && pnpm build",
+  "framework": "nextjs"
+}

webpack.config.js

@@ -8,6 +8,8 @@ const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPl
 const packageJson = require("./package.json");
 
 const analyseBundle = process.env.ANALYSE === 'true';
+
+// Always use versioned bundle name
 const bundleName = `plugin-${packageJson.version}`;
 
 if (!bundleName) {