@nimbalyst/extension-sdk 0.1.0

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IAEf,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAkH3B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAmBpE"}

package/dist/validate.js

@@ -0,0 +1,128 @@
+/**
+ * Build-time validation for extension bundles.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Validates an extension bundle for common issues.
+ *
+ * Run this after building to catch configuration mistakes before runtime.
+ *
+ * @param distPath - Path to the dist directory containing the bundle
+ * @param bundleName - Name of the bundle file (default: 'index.js')
+ *
+ * @example
+ * ```ts
+ * const result = await validateExtensionBundle('./dist');
+ * if (!result.valid) {
+ *   console.error('Build failed:', result.errors);
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export async function validateExtensionBundle(distPath, bundleName = 'index.js') {
+    const errors = [];
+    const warnings = [];
+    const bundlePath = path.join(distPath, bundleName);
+    // Check bundle exists
+    if (!fs.existsSync(bundlePath)) {
+        errors.push(`Bundle not found at ${bundlePath}`);
+        return { valid: false, errors, warnings };
+    }
+    const bundle = fs.readFileSync(bundlePath, 'utf8');
+    // Check for dev runtime usage (jsxDEV)
+    // This is now just a warning since we have a shim, but it's still not ideal
+    if (bundle.includes('jsxDEV') && bundle.includes('jsx-dev-runtime')) {
+        warnings.push('Extension uses jsxDEV from react/jsx-dev-runtime. ' +
+            'This works but is not recommended. Set mode: "production" in vite config ' +
+            'and configure @vitejs/plugin-react with jsxRuntime: "automatic".');
+    }
+    // Check for bundled React (should be external)
+    if (bundle.includes('react.production.min.js') ||
+        bundle.includes('react.development.js') ||
+        bundle.includes('__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED')) {
+        errors.push('Extension appears to bundle React. This will cause runtime errors. ' +
+            'Add "react" and "react-dom" to rollupOptions.external, or use createExtensionConfig().');
+    }
+    // Check for bundled Lexical (should be external)
+    if (bundle.includes('$getRoot') &&
+        bundle.includes('$getSelection') &&
+        bundle.length > 500000 // Lexical adds significant size
+    ) {
+        warnings.push('Extension may be bundling Lexical. If you use Lexical nodes, ' +
+            'add "lexical" and "@lexical/*" to rollupOptions.external.');
+    }
+    // Check for unresolved process.env references
+    if (bundle.includes('process.env.NODE_ENV')) {
+        warnings.push('Bundle contains process.env.NODE_ENV references that were not replaced. ' +
+            'Add define: { "process.env.NODE_ENV": JSON.stringify("production") } to vite config.');
+    }
+    // Check for CommonJS artifacts that might cause issues
+    if (bundle.includes('require(') && !bundle.includes('require.resolve')) {
+        warnings.push('Bundle contains require() calls which may not work in the browser. ' +
+            'Ensure all dependencies are ESM-compatible or properly bundled.');
+    }
+    // Check manifest exists
+    const manifestPath = path.join(path.dirname(distPath), 'manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+        warnings.push(`No manifest.json found at ${manifestPath}. ` +
+            'Extensions need a manifest.json to be loaded by Nimbalyst.');
+    }
+    else {
+        // Validate manifest
+        try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+            if (!manifest.id) {
+                errors.push('manifest.json is missing required "id" field');
+            }
+            if (!manifest.name) {
+                errors.push('manifest.json is missing required "name" field');
+            }
+            if (!manifest.main) {
+                errors.push('manifest.json is missing required "main" field');
+            }
+            else {
+                // Check main points to existing file
+                const mainPath = path.join(path.dirname(manifestPath), manifest.main);
+                if (!fs.existsSync(mainPath)) {
+                    errors.push(`manifest.json "main" points to ${manifest.main} but file does not exist`);
+                }
+            }
+            if (manifest.styles) {
+                const stylesPath = path.join(path.dirname(manifestPath), manifest.styles);
+                if (!fs.existsSync(stylesPath)) {
+                    warnings.push(`manifest.json "styles" points to ${manifest.styles} but file does not exist`);
+                }
+            }
+        }
+        catch (e) {
+            errors.push(`Failed to parse manifest.json: ${e}`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Prints validation results to console with formatting.
+ */
+export function printValidationResult(result) {
+    if (result.valid && result.warnings.length === 0) {
+        console.log('\x1b[32m%s\x1b[0m', '  Extension bundle validation passed');
+        return;
+    }
+    if (result.errors.length > 0) {
+        console.log('\x1b[31m%s\x1b[0m', '  Validation FAILED:');
+        for (const error of result.errors) {
+            console.log('\x1b[31m%s\x1b[0m', `    - ${error}`);
+        }
+    }
+    if (result.warnings.length > 0) {
+        console.log('\x1b[33m%s\x1b[0m', '  Warnings:');
+        for (const warning of result.warnings) {
+            console.log('\x1b[33m%s\x1b[0m', `    - ${warning}`);
+        }
+    }
+}

package/dist/vite.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Vite configuration helpers for Nimbalyst extensions.
+ */
+import type { UserConfig, PluginOption, Plugin } from 'vite';
+/**
+ * Creates a Vite plugin that validates the build output matches the manifest.
+ * This catches issues like manifest.main pointing to a file that doesn't exist
+ * (e.g., manifest says "dist/index.mjs" but Vite outputs "dist/index.js").
+ *
+ * The plugin runs after the build completes and fails the build if validation fails.
+ *
+ * @example
+ * ```ts
+ * import { createManifestValidationPlugin } from '@nimbalyst/extension-sdk/vite';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     react(),
+ *     createManifestValidationPlugin(),
+ *   ],
+ *   // ... rest of config
+ * });
+ * ```
+ */
+export declare function createManifestValidationPlugin(): Plugin;
+export interface ExtensionConfigOptions {
+    /**
+     * Entry point for the extension (e.g., './src/index.tsx')
+     */
+    entry: string;
+    /**
+     * Output filename (without extension). Defaults to 'index'
+     */
+    fileName?: string;
+    /**
+     * Additional externals to add beyond the required ones.
+     * Use this for libraries accessed via window.__nimbalyst_extensions
+     */
+    additionalExternals?: (string | RegExp)[];
+    /**
+     * Additional Vite plugins to include
+     */
+    plugins?: PluginOption[];
+    /**
+     * Whether to generate sourcemaps. Defaults to true
+     */
+    sourcemap?: boolean;
+    /**
+     * Whether to inline dynamic imports into a single file. Defaults to true.
+     * Required because extensions load via blob URLs which don't support relative imports.
+     */
+    inlineDynamicImports?: boolean;
+}
+/**
+ * Creates a Vite configuration for building a Nimbalyst extension.
+ *
+ * This sets up:
+ * - Production mode and NODE_ENV for proper React JSX transform
+ * - ES module output format
+ * - Correct externals for host-provided dependencies
+ * - Inlined dynamic imports (required for blob URL loading)
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { createExtensionConfig } from '@nimbalyst/extension-sdk/vite';
+ *
+ * export default createExtensionConfig({
+ *   entry: './src/index.tsx',
+ * });
+ * ```
+ */
+export declare function createExtensionConfig(options: ExtensionConfigOptions): UserConfig;
+/**
+ * Merges a base extension config with custom overrides.
+ * Useful when you need to extend the base config.
+ *
+ * @example
+ * ```ts
+ * import { createExtensionConfig, mergeExtensionConfig } from '@nimbalyst/extension-sdk/vite';
+ *
+ * const baseConfig = createExtensionConfig({ entry: './src/index.tsx' });
+ *
+ * export default mergeExtensionConfig(baseConfig, {
+ *   resolve: {
+ *     alias: { '@': './src' }
+ *   }
+ * });
+ * ```
+ */
+export declare function mergeExtensionConfig(base: UserConfig, overrides: Partial<UserConfig>): UserConfig;
+//# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAK7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,CA+CvD;AAED,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAE1C;;OAEG;IACH,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IAEzB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,UAAU,CAsEjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,GAC7B,UAAU,CAqBZ"}

package/dist/vite.js

@@ -0,0 +1,179 @@
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import { ROLLUP_EXTERNALS } from './externals.js';
+/**
+ * Creates a Vite plugin that validates the build output matches the manifest.
+ * This catches issues like manifest.main pointing to a file that doesn't exist
+ * (e.g., manifest says "dist/index.mjs" but Vite outputs "dist/index.js").
+ *
+ * The plugin runs after the build completes and fails the build if validation fails.
+ *
+ * @example
+ * ```ts
+ * import { createManifestValidationPlugin } from '@nimbalyst/extension-sdk/vite';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     react(),
+ *     createManifestValidationPlugin(),
+ *   ],
+ *   // ... rest of config
+ * });
+ * ```
+ */
+export function createManifestValidationPlugin() {
+    let outDir = 'dist';
+    let rootDir = process.cwd();
+    return {
+        name: 'nimbalyst-manifest-validation',
+        configResolved(config) {
+            outDir = config.build.outDir;
+            rootDir = config.root;
+        },
+        closeBundle() {
+            const manifestPath = resolve(rootDir, 'manifest.json');
+            if (!existsSync(manifestPath)) {
+                return; // No manifest to validate against
+            }
+            try {
+                const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+                const errors = [];
+                // Validate main JS file
+                if (manifest.main) {
+                    const mainPath = resolve(rootDir, manifest.main);
+                    if (!existsSync(mainPath)) {
+                        errors.push(`manifest.main "${manifest.main}" not found in build output`);
+                    }
+                }
+                // Validate styles CSS file
+                if (manifest.styles) {
+                    const stylesPath = resolve(rootDir, manifest.styles);
+                    if (!existsSync(stylesPath)) {
+                        errors.push(`manifest.styles "${manifest.styles}" not found in build output`);
+                    }
+                }
+                if (errors.length > 0) {
+                    console.error('\n\x1b[31m[nimbalyst-extension] Build validation failed:\x1b[0m');
+                    errors.forEach((err) => console.error(`  - ${err}`));
+                    console.error('\nMake sure your vite.config.ts output filenames match manifest.json\n');
+                    process.exitCode = 1;
+                }
+            }
+            catch {
+                // Ignore JSON parse errors - manifest might be invalid for other reasons
+            }
+        },
+    };
+}
+/**
+ * Creates a Vite configuration for building a Nimbalyst extension.
+ *
+ * This sets up:
+ * - Production mode and NODE_ENV for proper React JSX transform
+ * - ES module output format
+ * - Correct externals for host-provided dependencies
+ * - Inlined dynamic imports (required for blob URL loading)
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { createExtensionConfig } from '@nimbalyst/extension-sdk/vite';
+ *
+ * export default createExtensionConfig({
+ *   entry: './src/index.tsx',
+ * });
+ * ```
+ */
+export function createExtensionConfig(options) {
+    const { entry, fileName = 'index', additionalExternals = [], plugins = [], sourcemap = true, inlineDynamicImports = true, } = options;
+    // Combine required externals with any additional ones
+    const external = [...ROLLUP_EXTERNALS, ...additionalExternals];
+    return {
+        // Ensure production mode for proper JSX transform (jsx vs jsxDEV)
+        mode: 'production',
+        // Replace process.env.NODE_ENV at build time
+        // Required for libraries that use conditional exports
+        define: {
+            'process.env.NODE_ENV': JSON.stringify('production'),
+        },
+        plugins: [
+            // Note: User must add @vitejs/plugin-react themselves with proper config:
+            // react({ jsxRuntime: 'automatic', jsxImportSource: 'react' })
+            ...plugins,
+            // Validate build output matches manifest.json
+            createManifestValidationPlugin(),
+        ],
+        build: {
+            lib: {
+                entry,
+                formats: ['es'],
+                fileName: () => `${fileName}.js`,
+            },
+            rollupOptions: {
+                external,
+                output: {
+                    // Required: Extensions load via blob URLs which can't resolve relative imports
+                    inlineDynamicImports,
+                    // Standard globals for externals
+                    globals: {
+                        react: 'React',
+                        'react-dom': 'ReactDOM',
+                        'react/jsx-runtime': 'jsxRuntime',
+                    },
+                    // Name CSS output consistently
+                    // Vite 7 changed assetInfo.name to assetInfo.names (array)
+                    assetFileNames: (assetInfo) => {
+                        if (assetInfo.names?.some((name) => name.endsWith('.css'))) {
+                            return `${fileName}.css`;
+                        }
+                        return assetInfo.names?.[0] || 'asset';
+                    },
+                },
+            },
+            // Output directory
+            outDir: 'dist',
+            emptyOutDir: true,
+            // Sourcemaps for debugging
+            sourcemap,
+        },
+    };
+}
+/**
+ * Merges a base extension config with custom overrides.
+ * Useful when you need to extend the base config.
+ *
+ * @example
+ * ```ts
+ * import { createExtensionConfig, mergeExtensionConfig } from '@nimbalyst/extension-sdk/vite';
+ *
+ * const baseConfig = createExtensionConfig({ entry: './src/index.tsx' });
+ *
+ * export default mergeExtensionConfig(baseConfig, {
+ *   resolve: {
+ *     alias: { '@': './src' }
+ *   }
+ * });
+ * ```
+ */
+export function mergeExtensionConfig(base, overrides) {
+    return {
+        ...base,
+        ...overrides,
+        define: {
+            ...base.define,
+            ...overrides.define,
+        },
+        build: {
+            ...base.build,
+            ...overrides.build,
+            rollupOptions: {
+                ...base.build?.rollupOptions,
+                ...overrides.build?.rollupOptions,
+            },
+        },
+        resolve: {
+            ...base.resolve,
+            ...overrides.resolve,
+        },
+    };
+}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@nimbalyst/extension-sdk",
+  "version": "0.1.0",
+  "description": "SDK for building Nimbalyst extensions",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nimbalyst/nimbalyst.git",
+    "directory": "packages/extension-sdk"
+  },
+  "homepage": "https://docs.nimbalyst.com/extensions",
+  "bugs": {
+    "url": "https://github.com/nimbalyst/nimbalyst/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "nimbalyst": {
+    "minAppVersion": "0.58.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./tailwind": {
+      "types": "./dist/tailwind.d.ts",
+      "import": "./dist/tailwind.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "vite": "^7.1.12",
+    "@vitejs/plugin-react": "^5.1.2",
+    "tailwindcss": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "@vitejs/plugin-react": {
+      "optional": true
+    },
+    "tailwindcss": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "typescript": "^5.0.0",
+    "vite": "^7.1.12",
+    "@vitejs/plugin-react": "^5.1.2"
+  },
+  "keywords": [
+    "nimbalyst",
+    "extension",
+    "sdk",
+    "plugin",
+    "custom-editor",
+    "ai-tools"
+  ],
+  "license": "MIT"
+}