Compare commits

...
Author SHA1 Message Date
Antigravity AI 7f587b5e36 docs(plugin): add bundle footguns -- CSP/CSS, inlineDynamicImports, process.env, CORS 2026-05-29 10:40:16 +12:00
Antigravity AI ee0559a52f fix(sync): add process.env replacement, inlineDynamicImports, and CSS copy to syncToPublic
- Inline replace-process-env Rollup plugin transforms process.env.NODE_ENV to "production"
  to prevent ReferenceError in browser bundles that lack a Node.js environment
- Switch codeSplitting to inlineDynamicImports: true so the build produces a single
  self-contained ES module with no bare chunk specifiers that the browser cannot resolve
- Add rollup-plugin-external-globals to remap shared host deps (react, cesium, zustand, SDK)
  to globalThis.__WWV_HOST__.* at bundle time
- syncToPublic now copies any .css files emitted alongside the .mjs bundle (e.g. from
  gridstack or other CSS-importing libs) into public/plugins-local/<id>/
2026-05-29 10:40:16 +12:00
3 changed files with 760 additions and 2 deletions

No files matched your search

+93
View File
@@ -486,3 +486,96 @@ Seeders in `wwv-data-engine/src/seeders/` provide the backend data.
- **Cron Seeder**: Uses `registerSeeder({ name: "plugin-id", cron: "..." })` and pushes to Redis via `setLiveSnapshot()`.
- **Init Seeder**: High-frequency or persistent websockets via `init: () => void`.
- **Constraint**: Seeder `name` MUST exactly match the frontend plugin `id`. Do not bundle workspace dependencies like `ws` or `zod` into the seeder `dist`.
---
## Plugin Bundle Footguns
### 1. CSP blocks CDN stylesheets -- use `?inline` + `<style>` injection
The host app's `style-src` policy includes `'unsafe-inline'` but does **not** include external CDN origins like `unpkg.com` or `cdn.jsdelivr.net`. Any plugin that loads CSS via a runtime `<link href="https://unpkg.com/...">` will have that stylesheet **silently blocked** by the browser -- no console error, just broken styling and broken layout (elements fall back to `position: static`).
**Wrong:**
```typescript
// In useEffect:
link.href = "https://unpkg.com/gridstack@11/dist/gridstack.min.css";
document.head.appendChild(link);
```
**Correct -- bundle CSS as inline string and inject via `<style>` tag:**
```typescript
import gridstackCSS from "gridstack/dist/gridstack.min.css?inline";
// In useEffect:
const style = document.createElement("style");
style.textContent = gridstackCSS;
document.head.appendChild(style);
```
Vite's `?inline` suffix imports CSS as a plain string. The `<style>` tag is allowed by `'unsafe-inline'`. This is the only CSP-safe pattern for third-party CSS in plugin bundles.
---
### 2. `inlineDynamicImports: true` -- not `codeSplitting: false`
`codeSplitting: false` is **not a valid Rollup option**. It is silently ignored, and Rollup will still produce code-split chunks. The host can only load a single `frontend.mjs` -- any sibling chunk (e.g. `gridstack-XXXXX.js`) will 404.
**Wrong:**
```js
rollupOptions: {
output: { codeSplitting: false } // silently ignored
}
```
**Correct:**
```js
rollupOptions: {
output: { inlineDynamicImports: true } // prevents all code splitting
}
```
Both `vite.config.ts` (for manual `pnpm build`) and `scripts/sync-local-plugins.mjs` must use `inlineDynamicImports: true`.
---
### 3. `process.env.NODE_ENV` in CJS deps -- needs inline Rollup transform, not Vite `define`
CJS dependencies like `recharts`, `prop-types`, and `react-is` reference `process.env.NODE_ENV` inside their CommonJS module body. Vite's top-level `define: { 'process.env.NODE_ENV': '"production"' }` does NOT reach inside Rollup's `__commonJSMin()` wrappers -- those run after the `define` substitution phase.
**Wrong:**
```js
// In vite.config.ts or sync-local-plugins.mjs:
define: { 'process.env.NODE_ENV': '"production"' } // doesn't reach CJS wrappers
```
**Correct -- add an inline Rollup transform plugin inside `rollupOptions.plugins`:**
```js
rollupOptions: {
plugins: [
{
name: 'replace-process-env',
transform(code) {
if (!code.includes('process.env.NODE_ENV')) return null;
return {
code: code.replace(/process\.env\.NODE_ENV/g, '"production"'),
map: null,
};
},
},
// ... other plugins
]
}
```
This plugin runs on each module source before Rollup wraps it, so it correctly replaces `process.env.NODE_ENV` in CJS sub-dependencies.
---
### 4. Yahoo Finance and third-party data APIs -- CORS from the browser
Yahoo Finance's chart API (`query1.finance.yahoo.com`) does **not** return `Access-Control-Allow-Origin` headers. Direct `fetch()` from a plugin bundle running in the browser will be CORS-blocked.
**Architectural preference (in order):**
1. **Best:** Have the wwv-data-engine seeder fetch the data server-side and stream it to the plugin via WebSocket -- no CORS issue.
2. **Acceptable stopgap:** Use `corsproxy.io` relay: `fetch('https://corsproxy.io/?url=' + encodeURIComponent(apiUrl))`. This adds a third-party relay dependency.
3. **Do not do:** Assume browser `fetch()` to third-party financial APIs will work -- most do not send CORS headers.
+646
View File
File diff suppressed because it is too large. Load diff
+21 -2
View File
@@ -251,10 +251,22 @@ export async function buildPlugin({ dir, manifest, pkg, pluginDir }) {
external: Object.keys(EXTERNAL_GLOBALS),
output: {
globals: EXTERNAL_GLOBALS,
codeSplitting: false,
inlineDynamicImports: true,
banner: '"use client";',
},
plugins: [(await import("rollup-plugin-external-globals")).default(EXTERNAL_GLOBALS)],
plugins: [
{
name: 'replace-process-env',
transform(code) {
if (!code.includes('process.env.NODE_ENV')) return null;
return {
code: code.replace(/process\.env\.NODE_ENV/g, '"production"'),
map: null,
};
},
},
(await import("rollup-plugin-external-globals")).default(EXTERNAL_GLOBALS),
],
onwarn(warning, warn) {
if (warning.code === 'MODULE_LEVEL_DIRECTIVE' && warning.message.includes('"use client"')) {
return;
@@ -292,6 +304,13 @@ export function syncToPublic({ dir, manifest, pluginDir }, { quiet = false } = {
if (fs.existsSync(distMap)) {
fs.copyFileSync(distMap, path.join(targetDir, "frontend.mjs.map"));
}
// Copy any CSS files emitted alongside the bundle (e.g. from gridstack imports)
const distDir = path.join(pluginDir, "dist");
for (const f of fs.readdirSync(distDir)) {
if (f.endsWith(".css")) {
fs.copyFileSync(path.join(distDir, f), path.join(targetDir, f));
}
}
// Generate plugin.json manifest for the marketplace load route
const pluginJson = {