improving docs, and test UX (errors/toasts)

Author: getify

BUNDLERS.md

@@ -2,11 +2,11 @@
 
 This project has non-ESM dependencies, which unfortunately cannot be *bundled* in with your other app code. Modern bundlers unfortunately don't out-of-the-box support configurations that can handle such a situation.
 
-As such, this project provides plugins for webpack and vite, to take care of the various steps needed to get these non-ESM dependencies into an otherwise bundled web app built by those tools.
+As such, this project provides plugins for Vite and Webpack, to take care of the various steps needed to get these non-ESM dependencies into an otherwise bundled web app built by those tools.
 
 ## Bundler Plugins
 
-The plugins for vite and webpack are included in the `bundler-plugins/` directory. They should handle all necessary steps to load the dependencies.
+The plugins for Vite and Webpack are included in the `bundler-plugins/` directory. They should handle all necessary steps to load the dependencies.
 
 **Note:** You should not need to manually copy any files out of the `dist/bundlers/` directory, as the plugins access the `qr-data-sync` dependency (in `node_modules`) directly to pull the files needed. But for reference, the files these plugins access are:
 
@@ -24,7 +24,7 @@ The plugins for vite and webpack are included in the `bundler-plugins/` director
 
 ### Vite Plugin
 
-If using Vite 5+, it's strongly suggested to import this library's vite-plugin to manage the loading of its non-ESM dependencies. Add something like the following to your `vite.config.js` file:
+If using Vite 5+, it's strongly suggested to import this library's Vite-plugin to manage the loading of its non-ESM dependencies. Add something like the following to your `vite.config.js` file:
 
 ```js
 import { defineConfig } from "vite";
@@ -39,19 +39,25 @@ export default defineConfig({
 });
 ```
 
-This plugin works for both the `vite dev` (dev-server) mode and the `vite build` mode. In both cases, it copies the `dist/bundlers/qrds-external-bundle.js` file into the `public/` directory of your project root. It also injects a `<script src="qrds-external-bundle.js"></script>` tag into the markup of the `index.html` file that vite produces for your app.
+This plugin works for the `vite dev` (dev-server), `vite preview` (also dev-server), and `vite build` modes. In all cases, it copies the `dist/bundlers/qrds-external-bundle.js` file into the `public/` directory of your project root. It also injects a `<script src="/qrds-external-bundle.js"></script>` tag into the markup of the `index.html` file that Vite produces for your app.
 
-**Note:** At present, this plugin is not configurable in any way (i.e., calling `QRDS()` above with no arguments). If something about its behavior is not compatible with your vite project setup -- which can vary widely and be quite complex to predict or support by a basic plugin -- it's recommended you simply copy over the `qr-data-sync/bundler-plugins/vite.mjs` plugin and make necessary changes.
+**Note:** At present, this plugin is not configurable in any way (i.e., calling `QRDS()` above with no arguments). If something about its behavior is not compatible with your Vite project setup -- which can vary widely and be quite complex to predict or support by a basic plugin -- it's recommended you simply copy over the `qr-data-sync/bundler-plugins/vite.mjs` plugin and make necessary changes.
+
+#### SSR Breakage
+
+An unfortunate gotcha of tools that wrap Vite (e.g., Astro, Nuxt, etc) and do SSR (server-side rendering) is that they *break* a key assumption/behavior of this module's Vite plugin: the HTML injection of `<script src="/qrds-external-bundle.js"></script>`.
+
+As such, you'll likely need to manually add that `<script>` tag to your HTML pages/templates. The Vite plugin still copies that file into the `public/` folder for you, so it should load once the tag is added to your HTML.
 
 ### Webpack Plugin
 
 If using Webpack 5+, make sure you're already using the [HTML Webpack Plugin](https://github.com/jantimon/html-webpack-plugin/) to manage building your `index.html` (and/or other HTML pages).
 
-Then import this library's webpack-plugin to manage the loading of its non-ESM dependencies. Add something like the following to your `webpack.config.js`:
+Then import this library's Webpack-plugin to manage the loading of its non-ESM dependencies. Add something like the following to your `webpack.config.js`:
 
 ```js
 // 'HtmlWebpackPlugin' is a required dependency of the
-// qr-data-sync webpack plugin
+// qr-data-sync Webpack plugin
 import HtmlWebpackPlugin from "html-webpack-plugin";
 import QRDS from "qr-data-sync/bundlers/webpack";
 
@@ -71,9 +77,9 @@ export default {
 };
 ```
 
-This plugin copies the `dist/bundlers/qrds-external-bundle.js` file into the build root (default `dist/`), along with the other bundled files. It also injects a `<script src="qrds-external-bundle.js"></script>` tag into the markup of the `index.html` file (and any other HTML files) that webpack produces for your app.
+This plugin copies the `dist/bundlers/qrds-external-bundle.js` file into the build root (default `dist/`), along with the other bundled files. It also injects a `<script src="qrds-external-bundle.js"></script>` tag into the markup of the `index.html` file (and any other HTML files) that Webpack produces for your app.
 
-**Note:** At present, this plugin is not configurable in any way (i.e., calling `QRDS()` above with no arguments). If something about its behavior is not compatible with your webpack project setup -- which can vary widely and be quite complex to predict or support by a basic plugin -- it's recommended you simply copy over the `qr-data-sync/bundler-plugins/webpack.mjs` plugin and make necessary changes.
+**Note:** At present, this plugin is not configurable in any way (i.e., calling `QRDS()` above with no arguments). If something about its behavior is not compatible with your Webpack project setup -- which can vary widely and be quite complex to predict or support by a basic plugin -- it's recommended you simply copy over the `qr-data-sync/bundler-plugins/webpack.mjs` plugin and make necessary changes.
 
 ## Import/Usage
 
@@ -83,4 +89,4 @@ To import and use **qr-data-sync** in a *bundled* browser app:
 import { todo } from "qr-data-sync";
 ```
 
-When `import`ed like this, both vite and webpack should (via these plugins) properly find and bundle the `dist/bundlers/qrds.js` ESM library module with the rest of your app code, without any further steps necessary.
+When `import`ed like this, both Vite and Webpack should (via these plugins) properly find and bundle the `dist/bundlers/qrds.js` ESM library module with the rest of your app code, hopefully without any further steps necessary.

README.md

@@ -1,6 +1,6 @@
 # QR Data Sync
 
-[![npm Module](https://badge.fury.io/mylofi/qr-data-sync.svg)](https://www.npmjs.org/package/qr-data-sync)
+[![npm Module](https://badge.fury.io/@lofi%2fqr-data-sync.svg)](https://www.npmjs.org/package/@lofi/qr-data-sync)
 [![License](https://img.shields.io/badge/license-MIT-a1356a)](LICENSE.txt)
 
 **QR Data Sync** is a browser library with utils for sharing/synchronizing data via "animated" QR codes.
@@ -13,11 +13,15 @@
 
 ## Deployment / Import
 
-The [**qr-data-sync** npm package](https://npmjs.com/package/webauthn-local-client) includes a `dist/` directory with all files you need to deploy **qr-data-sync** (and its dependencies) into your application/project.
+```cmd
+npm install @lofi/qr-data-sync
+```
+
+The [**qr-data-sync** npm package](https://npmjs.com/package/@lofi/webauthn-local-client) includes a `dist/` directory with all files you need to deploy **qr-data-sync** (and its dependencies) into your application/project.
 
 If you obtain this library via git instead of npm, you'll need to [build `dist/` manually](#re-building-dist) before deployment.
 
-* **USING A WEB BUNDLER?** (vite, webpack, etc) Use the `dist/bundlers/*` files and see [Bundler Deployment](BUNDLERS.md) for instructions.
+* **USING A WEB BUNDLER?** (Vite, Webpack, etc) Use the `dist/bundlers/*` files and see [Bundler Deployment](BUNDLERS.md) for instructions.
 
 * Otherwise, use the `dist/auto/*` files and see [Non-Bundler Deployment](NON-BUNDLERS.md) for instructions.
 

test/test.js

@@ -153,8 +153,8 @@ async function showQRCodes(name,note,randomString) {
 			}
 			catch (err) {
 				if (!closing) {
-					Swal.showValidationMessage(err.toString());
-					console.log(err);
+					console.error(err);
+					await showError(`Generating QR codes failed: ${err.toString()}`);
 				}
 			}
 		},
@@ -229,11 +229,13 @@ async function promptReceiveData() {
 
 				// render received data
 				renderReceivedData(data);
+
+				return showToast("Data received successfully.");
 			}
 			catch (err) {
 				if (!closing) {
-					Swal.showValidationMessage(err.toString());
-					console.log(err);
+					console.error(err);
+					await showError(`Reading QR codes failed: ${err.toString()}`);
 				}
 			}
 		},
@@ -285,3 +287,26 @@ function randomString(length) {
 	var rv = crypto.getRandomValues(new Uint8Array(length));
 	return btoa(String.fromCharCode.apply(null,rv));
 }
+
+function showError(errMsg) {
+	return Swal.fire({
+		title: "Error!",
+		text: errMsg,
+		icon: "error",
+		confirmButtonText: "ok",
+	});
+}
+
+function showToast(toastMsg) {
+	return Swal.fire({
+		text: toastMsg,
+		showConfirmButton: false,
+		showCloseButton: true,
+		timer: 5000,
+		toast: true,
+		position: "top-end",
+		customClass: {
+			popup: "toast-popup",
+		},
+	});
+}