Merge branch 'vite-plugin' (#94)

Author: DallasHoff

README.md

@@ -125,36 +125,29 @@ pnpm install sqlocal
 
 ### Cross-Origin Isolation
 
-In order to persist data to the origin private file system, this package relies on APIs that require cross-origin isolation, so the page you use this package on must be served with the following HTTP headers. Otherwise, the browser will block access to the origin private file system.
+In order to persist data to the origin private file system, this package relies on APIs that require [cross-origin isolation](https://developer.mozilla.org/en-US/docs/Web/API/Window/crossOriginIsolated), so the page you use this package on must be served with the following HTTP headers. Otherwise, the browser will block access to the origin private file system.
 
 ```http
 Cross-Origin-Embedder-Policy: require-corp
 Cross-Origin-Opener-Policy: same-origin
 ```
 
-If your development server uses Vite, you can do this by adding the following to your Vite configuration.
-
-```javascript
-plugins: [
-  {
-    name: 'configure-response-headers',
-    configureServer: (server) => {
-      server.middlewares.use((_req, res, next) => {
-        res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
-        res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
-        next();
-      });
-    },
-  },
-],
-```
+How this is configured will depend on what web server or hosting service your application uses. If your development server uses Vite, [see the configuration below](#vite-configuration).
 
 ### Vite Configuration
 
-Vite currently has an issue that prevents it from loading web worker files correctly with the default configuration. If you use Vite, please add the below to your Vite configuration to fix this.
+Vite needs some additional configuration to handle web worker files correctly. If you or your framework uses Vite as your build tool, you can use SQLocal's Vite plugin to set this up.
+
+The plugin will also enable [cross-origin isolation](#cross-origin-isolation) (required for origin private file system persistence) for the Vite development server by default. Just don't forget to also configure your _production_ web server to use the same HTTP headers.
+
+Import the plugin from `sqlocal/vite` and add it to your [Vite configuration](https://vitejs.dev/config/).
 
 ```javascript
-optimizeDeps: {
-  exclude: ['sqlocal'],
-},
+import { defineConfig } from 'vite';
+import sqlocal from 'sqlocal/vite';
+
+export default defineConfig({
+  plugins: [sqlocal()],
+});
 ```
+

docs/guide/setup.md

@@ -24,7 +24,7 @@ pnpm install sqlocal
 
 ## Cross-Origin Isolation
 
-In order to persist data to the origin private file system, this package relies on APIs that require cross-origin isolation, so the page you use this package on must be served with the following HTTP headers. Otherwise, the browser will block access to the origin private file system.
+In order to persist data to the origin private file system, this package relies on APIs that require [cross-origin isolation](https://developer.mozilla.org/en-US/docs/Web/API/Window/crossOriginIsolated), so the page you use this package on must be served with the following HTTP headers. Otherwise, the browser will block access to the origin private file system.
 
 ```http
 Cross-Origin-Embedder-Policy: require-corp
@@ -80,27 +80,84 @@ export const db = new SQLocal({
 
 ## Vite Configuration
 
-Vite currently has an issue that prevents it from loading web worker files correctly with the default configuration. If you use Vite, please add the below to your [Vite configuration](https://vitejs.dev/config/) to fix this. Don't worry: it will have no impact on production performance.
+Vite needs some additional configuration to handle web worker files correctly. If you or your framework uses Vite as your build tool, you can use SQLocal's Vite plugin to set this up.
 
-```javascript
-optimizeDeps: {
-  exclude: ['sqlocal'],
-},
-```
+The plugin will also enable [cross-origin isolation](#cross-origin-isolation) (required for origin private file system persistence) for the Vite development server by default. Just don't forget to also configure your _production_ web server to use the same HTTP headers.
 
-To enable cross-origin isolation (required for origin private file system persistence) for the Vite development server, you can add this to your Vite configuration. Just don't forget to also configure your _production_ web server to use the same HTTP headers.
+Import the plugin from `sqlocal/vite` and add it to your [Vite configuration](https://vitejs.dev/config/).
 
 ```javascript
-plugins: [
-  {
-    name: 'configure-response-headers',
-    configureServer: (server) => {
-      server.middlewares.use((_req, res, next) => {
-        res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
-        res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
-        next();
-      });
+import { defineConfig } from 'vite';
+import sqlocal from 'sqlocal/vite';
+
+export default defineConfig({
+	plugins: [sqlocal()],
+});
+```
+
+::: details Angular
+
+Since Angular does not expose its Vite configuration, you will need to configure it differently than other Vite-based frameworks. You can reference the [SQLocal Shell codebase](https://github.com/DallasHoff/sqlocal-shell) as an example.
+
+First, it's important to disable prebundling in the development server so that Vite compiles the web workers correctly. You can do this in your serve architect in `angular.json`. This is also where you can set the headers for cross-origin isolation in development.
+
+```json{8-12}
+"architect": {
+  "build": { ... },
+  "serve": {
+    "builder": "@angular/build:dev-server",
+    "configurations": {
+      "development": {
+        "buildTarget": "my-app:build:development",
+        "headers": {
+          "Cross-Origin-Embedder-Policy": "require-corp",
+          "Cross-Origin-Opener-Policy": "same-origin"
+        },
+        "prebundle": false
+      }
     },
+    "defaultConfiguration": "development"
+  }
+}
+```
+
+You will also need to serve `sqlite3.wasm` from the root of your site. You can configure this in your build architect in `angular.json`.
+
+```json{10-13}
+"architect": {
+  "build": {
+    "builder": "@angular/build:application",
+    "options": {
+      "outputPath": "dist/my-app",
+      "index": "src/index.html",
+      "browser": "src/main.ts",
+      "tsConfig": "tsconfig.app.json",
+      "assets": [
+        {
+          "glob": "**/*",
+          "input": "node_modules/@sqlite.org/sqlite-wasm/sqlite-wasm/jswasm"
+        },
+        {
+          "glob": "**/*",
+          "input": "public"
+        }
+      ],
+      "styles": ["src/styles.scss"],
+      "scripts": [],
+      "webWorkerTsConfig": "tsconfig.worker.json"
+    }
   },
-],
+  "serve": { ... }
+}
 ```
+
+Finally, you will need to create your own web worker file and pass it to the `SQLocal` constructor, rather than use the built-in worker. Run `ng create web-worker sqlocal` to make a web worker file, add [this code](https://github.com/DallasHoff/sqlocal-shell/blob/main/src/sqlocal.worker.ts), and pass the worker to SQLocal's `processor` option.
+
+```typescript
+const db = new SQLocal({
+	databasePath: 'database.sqlite3',
+	processor: new Worker(new URL('../sqlocal.worker', import.meta.url)),
+});
+```
+
+:::