wasm loading docs

Author: pyramation

LOADING_WASM.md

@@ -0,0 +1,22 @@
+### ⚙️ TL;DR — Serving the `.wasm` File
+
+The core issue isn’t the library — it’s that the **`.wasm` file lives in `node_modules` and isn’t automatically served** by Next.js, Webpack, or Turbopack.
+You just need to make sure it’s fetchable at runtime.
+
+#### ✅ Easiest Fix
+
+Copy the `.wasm` file once and serve it from `/public`:
+
+```bash
+cp node_modules/libpg-query/wasm/libpg-query.wasm public/
+```
+
+#### ⚠️ Why
+
+Bundlers don’t emit `.wasm` files by default — they stay inside `node_modules`, so the runtime can’t fetch them.
+
+#### 🧩 Workarounds
+
+* **Next.js + Webpack:** Add a `.wasm` asset rule or use the copy method.
+* **Turbopack:** Only the copy method works for now.
+* **Dev mode:** Optionally use a watcher script to auto-copy on rebuilds.

README.md

@@ -185,6 +185,10 @@ pnpm run test
 - Ensure Emscripten SDK is properly installed and configured
 - Check that all required build dependencies are available
 
+**`.wasm` not found**
+- Usually occurs in Next.js/Webpack/Turbopack
+- see **[LOADING_WASM.md](./LOADING_WASM.md)**
+
 ### Template System
 
 To avoid duplication across PostgreSQL versions, common files are maintained in the `templates/` directory: