Merge remote-tracking branch 'template/main' into merge-webpack-changes-from-template

.gitignore

@@ -9,6 +9,7 @@ lerna-debug.log*
 
 node_modules
 dist
+release
 dist-ssr
 *.local
 
@@ -21,5 +22,5 @@ dist-ssr
 *.sln
 *.sw?
 
-# Vite-built temp WebView files
-temp-vite
+# Temporary intermediate build files
+temp-build

.vscode/launch.json

@@ -1,41 +1,72 @@
 {
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-    "version": "0.2.0",
-    "configurations": [
-      {
-        "name": "Watch and Build Extension",
-        "type": "node",
-        "request": "launch",
-        "runtimeExecutable": "npm",
-        "skipFiles": ["<node_internals>/**"],
-        "runtimeArgs": ["run", "start:vite"]
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Watch and Build Extension",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "skipFiles": ["<node_internals>/**"],
+      "runtimeArgs": ["run", "watch"]
+    },
+    {
+      "name": "Build WebViews",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "skipFiles": ["<node_internals>/**"],
+      "runtimeArgs": ["run", "build:web-view"]
+    },
+    {
+      "name": "Build Main",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "skipFiles": ["<node_internals>/**"],
+      "runtimeArgs": ["run", "build:main"]
+    },
+    {
+      "name": "Build Extension",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "skipFiles": ["<node_internals>/**"],
+      "runtimeArgs": ["run", "build"]
+    },
+    {
+      "name": "Debug Platform with Extension",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "start"],
+      "skipFiles": ["<node_internals>/**"],
+      "env": {
+        "MAIN_ARGS": "--inspect=5858 --remote-debugging-port=9223",
+        "IN_VSCODE": "true"
       },
-      {
-        "name": "Build Extension",
-        "type": "node",
-        "request": "launch",
-        "runtimeExecutable": "npm",
-        "skipFiles": ["<node_internals>/**"],
-        "runtimeArgs": ["run", "build:vite"]
-      },
-      {
-        "name": "Debug Paranext Core with Extension",
-        "type": "node",
-        "request": "launch",
-        "runtimeExecutable": "npm",
-        "runtimeArgs": ["run", "start"],
-        "skipFiles": ["<node_internals>/**"],
-        "env": {
-          "MAIN_ARGS": "--inspect=5858 --remote-debugging-port=9223",
-          "IN_VSCODE": "true"
-        },
-        "presentation": {
-          "hidden": false,
-          "group": "",
-          "order": 1
-        }
+      "presentation": {
+        "hidden": false,
+        "group": "",
+        "order": 1
       }
-    ]
-}
+    },
+    {
+      "name": "Attach to Platform app",
+      "type": "node",
+      "request": "attach",
+      "port": 5858,
+      "timeout": 15000
+    },
+    {
+      "name": "Attach to Renderer",
+      "type": "chrome",
+      "request": "attach",
+      "port": 9223,
+      "webRoot": "${workspaceFolder}",
+      "timeout": 15000
+    }
+  ]
+}

.vscode/settings.json

@@ -3,6 +3,36 @@
   "editor.wordWrapColumn": 100,
 
   "files.eol": "\n",
+  "cSpell.words": [
+    "asyncs",
+    "endregion",
+    "papi",
+    "paranext",
+    "sillsdev",
+    "unsub",
+    "unsubscriber",
+    "usfm"
+  ],
 
-  "cSpell.words": ["asyncs", "papi", "paranext", "unsub", "unsubscriber", "unsubscribers"]
+  "todohighlight.keywords": [
+    {
+      "text": "WARNING:",
+      "isWholeLine": true,
+      "color": "#FF0000",
+      "backgroundColor": "none",
+      "overviewRulerColor": "#FF000000"
+    },
+    {
+      "text": "#region",
+      "color": "#6cf5ff",
+      "backgroundColor": "none",
+      "overviewRulerColor": "#6cf5ff60"
+    },
+    {
+      "text": "#endregion",
+      "color": "#6cf5ff",
+      "backgroundColor": "none",
+      "overviewRulerColor": "#6cf5ff60"
+    }
+  ]
 }

README.md

@@ -3,16 +3,18 @@ Example Paranext extension to display a Sneeze Board
 
 ## Summary
 
-This is a sample Paranext extension project: Sneeze Board to track team members' work-related sneezes.
-
- - `lib` contains the source code for the extension
-   - `lib/main.ts` is the main entry file for the Sneeze Board extension
-   - `sneeze-board.web-view.tsx` file defines a React WebView that Paranext displays
- - `public` contains static files that are transferred to the build folder
-   - `public/manifest.json` is the manifest file that defines the extension
-   - `public/package.json` defines the npm package for this extension and is required for Paranext to use it appropriately
-   - `public/paranext-extension-sneeze-board.d.ts` is this extension's types file that other extensions can use
- - `dist` is a generated folder containing the built extension files
+This is a sample webpack Platform.Bible extension project: Sneeze Board to track team members' work-related sneezes.
+- `package.json` contains information about this extension npm package. It is required for Platform.Bible to use the extension properly. It is copied into the build folder
+- `src` contains the source code for the extension
+  - `src/main.ts` is the main entry file for the Sneeze Board extension
+  - `src/types/sneeze-board.d.ts` is this extension's types file that defines how other extensions can use this extension through the `papi`. It is copied into the build folder
+  - `sneeze-board.web-view.tsx` file defines a React WebView that Platform.Bible displays
+- `public` contains static files that are copied into the build folder
+  - `public/manifest.json` is the manifest file that defines the Sneeze Board extension and important properties for Platform.Bible
+  - `public/package.json` defines the npm package for this extension and is required for Platform.Bible to use it appropriately
+  - `public/assets` contains asset files the extension and its WebViews can retrieve using the `papi-extension:` protocol
+- `dist` is a generated folder containing the built extension files
+- `release` is a generated folder containing a zip of the built extension files
 
 ## To install
 
@@ -35,41 +37,64 @@ To run Paranext with your extension:
 
 `npm start`
 
-Note: The built extension will be in the `dist` folder. In order for Paranext to run your extension, you must provide the directory to your built extension to Paranext via a command-line argument. This command-line argument is already provided in this `package.json`'s `start` script. If you want to start Paranext and use your extension any other way, you must provide this command-line argument or put the `dist` folder into Paranext's `extensions` folder.
+Note: The built extension will be in the `dist` folder. In order for Platform.Bible to run your extension, you must provide the directory to your built extension to Platform.Bible via a command-line argument. This command-line argument is already provided in this `package.json`'s `start` script. If you want to start Platform.Bible and use the Sneeze Board extension any other way, you must provide this command-line argument or put the `dist` folder into Platform.Bible's `extensions` folder.
 
 ### Building your extension independently
 
-To watch extension files (in `lib`) for changes:
+To watch extension files (in `src`) for changes:
+
+`npm run watch`
+
+To build the Sneeze Board extension once:
+
+`npm run build`
+
+## To package for distribution
+
+To package the Sneeze Board extension into a zip file for distribution:
+
+`npm run package`
+
+## Special features of the template
 
-`npm run start:vite`
+The paranext-extension-template has special features and specific configuration to make building an extension for Platform.Bible easier. Following are a few important notes:
 
-To build the extension once:
+### React WebView files - `.web-view.tsx`
 
-`npm run build:vite`
+Platform.Bible WebViews must be treated differently than other code, so the template makes doing that simpler:
 
-## Vite Build Explanation
+- WebView code must be bundled and can only import specific packages provided by Platform.Bible (see `externals` in `webpack.config.base.ts`), so this template bundles React WebViews before bundling the main extension file to support this requirement. The template discovers and bundles files that end with `.web-view.tsx` in this way.
+  - Note: while watching for changes, if you add a new `.web-view.tsx` file, you must either restart webpack or make a nominal change and save in an existing `.web-view.tsx` file for webpack to discover and bundle this new file.
+- WebView code and styles must be provided to the `papi` as strings, so you can import WebView files with [`?inline`](#special-imports) after the file path to import the file as a string.
 
-This extension sneeze-board is built by Vite in two steps: a WebView transpilation step and a packaging step:
+### Special imports
 
-## Build 1: TypeScript WebView transpilation
+- Adding `?inline` to the end of a file import causes that file to be imported as a string after being transformed by webpack loaders but before bundling dependencies (except if that file is a React WebView file, in which case dependencies will be bundled). The contents of the file will be on the file's default export.
+  - Ex: `import myFile from './file-path?inline`
+- Adding `?raw` to the end of a file import treats a file the same way as `?inline` except that it will be imported directly without being transformed by webpack.
 
-Vite prepares TypeScript WebViews for use and outputs them into `temp-vite` folders adjacent to the WebView files:
-- Formats WebViews to match how they should look to work in Paranext
+### Misc features
+
+- Platform.Bible extension code must be bundled all together in one file, so webpack bundles all the code together into one main extension file.
+- Platform.Bible extensions can interact with other extensions, but they cannot import and export like in a normal Node environment. Instead, they interact through the `papi`. As such, the `src/types` folder contains this extension's declarations file that tells other extensions how to interact with it through the `papi`.
+
+### Two-step webpack build
+
+This extension template is built by webpack (`webpack.config.ts`) in two steps: a WebView bundling step and a main bundling step:
+
+#### Build 1: TypeScript WebView bundling
+
+Webpack (`./webpack/webpack.config.web-view.ts`) prepares TypeScript WebViews for use and outputs them into temporary build folders adjacent to the WebView files:
+- Formats WebViews to match how they should look to work in Platform.Bible
 - Transpiles React/TypeScript WebViews into JavaScript
-- Packages dependencies into the WebViews
+- Bundles dependencies into the WebViews
 - Embeds Sourcemaps into the WebViews inline
 
-## Built 2: Packaging
+#### Build 2: Main and final bundling
 
-Vite packages the extension together into the `dist` folder:
+Webpack (`./webpack/webpack.config.main.ts`) prepares the main extension file and bundles the extension together into the `dist` folder:
 - Transpiles the main TypeScript file and its imported modules into JavaScript
-- Injects the WebViews into the main file
-- Packages dependencies into the main file
-- Generates sourcemaps for the file
-- Packages everything up into an extension folder in `dist`
-
-Note: When performing the second build step, the following line may occur in your console. Please feel free to ignore it as it is a false positive. It is likely showing because WebViews are embedded in the entry file:
-
-```bash
-transforming (1) lib\main.ts[plugin:ImportManager] It seems like there are multiple imports of module 'react'. You should examine that.
-```
+- Injects the bundled WebViews into the main file
+- Bundles dependencies into the main file
+- Embeds Sourcemaps into the file inline
+- Packages everything up into an extension folder `dist`