@bwat47/joplin-plugin-scripts 1.0.0 → 1.1.0

package/README.md

@@ -40,13 +40,20 @@ Commands run from the plugin project root, which npm scripts do automatically.
 ```json
 {
     "extraScripts": ["contentScripts/codeMirror.ts"],
+    "webviewScripts": ["dialog/dialog.ts"],
     "mainBuildOptions": { "external": ["jsdom"] }
 }
 ```
 
-- `extraScripts`: content scripts relative to `src/`, bundled for the browser to the same
-  path under `dist/` with a `.js` extension. Joplin's CodeMirror and Lezer packages stay
-  external so they share the host's instances.
+- `extraScripts`: content scripts registered with `joplin.contentScripts.register`
+  (CodeMirror and Markdown-it plugins), relative to `src/`. Each is bundled for the browser
+  as CommonJS to the same path under `dist/` with a `.js` extension. Joplin's CodeMirror
+  and Lezer packages stay external so they share the host's instances.
+- `webviewScripts`: scripts loaded into a dialog or panel with `addScript`, relative to
+  `src/`. A webview loads them as plain `<script>` tags with no `module`, `exports`, or
+  `require`, so each is bundled as a self-contained IIFE with nothing external. Exports
+  are dropped, so the script must start itself, e.g. by calling its init function at the
+  top level. Plain `.js` files in `src/` are copied as-is and don't need listing.
 - `mainBuildOptions`: esbuild options merged over the main bundle's defaults. Relative
   `alias` targets resolve from the project root. `absWorkingDir`, `entryPoints`,
   `outfile`, and `outdir` cannot be overridden.
@@ -63,7 +70,7 @@ const { mainBuildOptions } = await readPluginConfig(root);
 const result = await build({ ...createBuildOptions(root, mainBuildOptions), write: false });
 ```
 
-`contentScriptExternals` is also exported.
+`createWebviewScriptBuildOptions` and `contentScriptExternals` are also exported.
 
 ## Development
 

package/lib/build.mjs

@@ -5,21 +5,27 @@ import { build } from 'esbuild';
 import {
     createBuildOptions,
     createContentScriptBuildOptions,
+    createWebviewScriptBuildOptions,
     isRuntimeAsset,
     readPluginConfig,
+    scriptOutputPaths,
 } from './buildConfig.mjs';
 import { packagePlugin, readProject } from './packagePlugin.mjs';
 
 /**
  * Builds the plugin at `root`: validates the project, clears `dist/` and `publish/`, copies runtime
- * assets from `src/`, bundles the main entry point and extra scripts, and creates the `.jpl` archive.
+ * assets from `src/`, bundles the main entry point, extra scripts, and webview scripts, and creates
+ * the `.jpl` archive.
  */
 export async function buildPlugin(root) {
     const dist = path.join(root, 'dist');
     const publish = path.join(root, 'publish');
     const { manifest } = await readProject(root);
-    const { extraScripts, mainBuildOptions } = await readPluginConfig(root);
-    const extraBuilds = extraScripts.map((script) => createContentScriptBuildOptions(root, script));
+    const { extraScripts, webviewScripts, mainBuildOptions } = await readPluginConfig(root);
+    const scriptBuilds = [
+        ...extraScripts.map((script) => createContentScriptBuildOptions(root, script)),
+        ...webviewScripts.map((script) => createWebviewScriptBuildOptions(root, script)),
+    ];
 
     // Only these fixed, project-local output directories are removed.
     await rm(dist, { recursive: true, force: true });
@@ -33,12 +39,8 @@ export async function buildPlugin(root) {
     });
     await Promise.all([
         build(createBuildOptions(root, mainBuildOptions)),
-        ...extraBuilds.map((options) => build(options)),
+        ...scriptBuilds.map((options) => build(options)),
     ]);
 
-    await packagePlugin(
-        root,
-        manifest,
-        extraBuilds.map((options) => path.relative(dist, path.resolve(root, options.outfile)))
-    );
+    await packagePlugin(root, manifest, scriptOutputPaths(extraScripts, webviewScripts));
 }

package/lib/buildConfig.mjs

@@ -132,14 +132,41 @@ export function createContentScriptBuildOptions(root, script) {
     };
 }
 
+/**
+ * Returns the esbuild options for one webview script, e.g. `dialog/resizeDialog.ts` (relative to
+ * `src/`) to `dist/dialog/resizeDialog.js`. Webview scripts are loaded by a `<script>` tag in a
+ * dialog or panel, which has no `module`, `exports`, or `require`, so they are bundled as a
+ * self-contained IIFE. Their exports are dropped; the script runs for its side effects.
+ * @param {string} root Plugin project root.
+ * @param {string} script Script path relative to `src/`.
+ * @returns {import('esbuild').BuildOptions}
+ */
+export function createWebviewScriptBuildOptions(root, script) {
+    return {
+        ...createContentScriptBuildOptions(root, script),
+        format: 'iife',
+        // A webview has no host CodeMirror instance to share, so everything is bundled.
+        external: [],
+    };
+}
+
+/** Returns `dist/`-relative output paths for every script the plugin config registers. */
+export function scriptOutputPaths(extraScripts, webviewScripts) {
+    return [...extraScripts, ...webviewScripts].map((script) => script.replace(SCRIPT_EXTENSION_PATTERN, '.js'));
+}
+
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
 /**
  * Reads and validates `<root>/plugin.config.json`. The file is optional; a plugin without one
- * has no extra scripts and uses the default main build options.
- * @returns {Promise<{ extraScripts: string[], mainBuildOptions: import('esbuild').BuildOptions }>}
+ * has no extra or webview scripts and uses the default main build options.
+ * @returns {Promise<{ extraScripts: string[], webviewScripts: string[], mainBuildOptions: import('esbuild').BuildOptions }>}
  */
 export async function readPluginConfig(root) {
     const configPath = path.join(root, CONFIG_FILE);
@@ -147,17 +174,27 @@ export async function readPluginConfig(root) {
     try {
         config = JSON.parse(await readFile(configPath, 'utf8'));
     } catch (error) {
-        if (error.code === 'ENOENT') return { extraScripts: [], mainBuildOptions: {} };
+        if (error.code === 'ENOENT') return { extraScripts: [], webviewScripts: [], mainBuildOptions: {} };
         throw new Error(`Could not read ${configPath}: ${error.message}`, { cause: error });
     }
     if (!isPlainObject(config)) throw new Error(`${configPath} must contain a JSON object.`);
-    const { extraScripts = [], mainBuildOptions = {}, ...unknown } = config;
+    const { extraScripts = [], webviewScripts = [], mainBuildOptions = {}, ...unknown } = config;
     const unknownKeys = Object.keys(unknown);
     if (unknownKeys.length > 0) {
         throw new Error(`${configPath} has unknown keys: ${unknownKeys.join(', ')}.`);
     }
-    if (!Array.isArray(extraScripts) || extraScripts.some((script) => typeof script !== 'string')) {
-        throw new Error(`${configPath} "extraScripts" must be an array of paths relative to src/.`);
+    for (const [key, value] of [
+        ['extraScripts', extraScripts],
+        ['webviewScripts', webviewScripts],
+    ]) {
+        if (!isStringArray(value)) {
+            throw new Error(`${configPath} "${key}" must be an array of paths relative to src/.`);
+        }
+    }
+    const outputs = scriptOutputPaths(extraScripts, webviewScripts);
+    const duplicate = outputs.find((output, index) => outputs.indexOf(output) !== index);
+    if (duplicate !== undefined) {
+        throw new Error(`${configPath} lists more than one script that builds to dist/${duplicate}.`);
     }
     if (!isPlainObject(mainBuildOptions)) {
         throw new Error(`${configPath} "mainBuildOptions" must be an object of esbuild options.`);
@@ -166,5 +203,5 @@ export async function readPluginConfig(root) {
     if (reserved.length > 0) {
         throw new Error(`${configPath} "mainBuildOptions" cannot set ${reserved.join(', ')}.`);
     }
-    return { extraScripts, mainBuildOptions };
+    return { extraScripts, webviewScripts, mainBuildOptions };
 }

package/lib/index.mjs

@@ -3,5 +3,6 @@ export {
     contentScriptExternals,
     createBuildOptions,
     createContentScriptBuildOptions,
+    createWebviewScriptBuildOptions,
     readPluginConfig,
 } from './buildConfig.mjs';

package/package.json

@@ -1,9 +1,13 @@
 {
     "name": "@bwat47/joplin-plugin-scripts",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Shared esbuild build, packaging, version, and API-update scripts for Joplin plugins",
     "license": "MIT",
     "author": "bwat47",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/bwat47/joplin-plugin-scripts.git"
+    },
     "type": "module",
     "engines": {
         "node": ">=22"