diff --git a/packages/plugins/driver-turso/README.md b/packages/plugins/driver-turso/README.md
index 9d130f10e..7e5e185af 100644
--- a/packages/plugins/driver-turso/README.md
+++ b/packages/plugins/driver-turso/README.md
@@ -38,6 +38,29 @@ TursoDriver extends SqlDriver (dual transport)
 pnpm add @objectstack/driver-turso
 ```
 
+### Dependencies by Mode
+
+The `driver-turso` package has different dependency requirements based on the connection mode:
+
+| Mode | Required Dependencies | Notes |
+|:---|:---|:---|
+| **Remote** | `@libsql/client` only | ✅ Vercel/Edge compatible — no native dependencies |
+| **Local** | `@libsql/client` + `better-sqlite3` | Requires `better-sqlite3` for local SQLite access |
+| **Replica** | `@libsql/client` + `better-sqlite3` | Requires `better-sqlite3` for local SQLite + sync |
+
+**For Vercel/Edge deployments (remote mode only):**
+```bash
+pnpm add @objectstack/driver-turso
+# better-sqlite3 is NOT required
+```
+
+**For local/replica modes:**
+```bash
+pnpm add @objectstack/driver-turso better-sqlite3
+```
+
+The `better-sqlite3` package is an **optional peer dependency**. If you're only using remote mode (e.g., on Vercel), you don't need to install it. npm/pnpm will show a warning that can be safely ignored.
+
 ## Connection Modes
 
 ### Local File (Embedded SQLite)
diff --git a/packages/plugins/driver-turso/package.json b/packages/plugins/driver-turso/package.json
index 901136f45..832cb1b40 100644
--- a/packages/plugins/driver-turso/package.json
+++ b/packages/plugins/driver-turso/package.json
@@ -33,11 +33,19 @@
     "@objectstack/core": "workspace:*",
     "@objectstack/driver-sql": "workspace:*",
     "@objectstack/spec": "workspace:*",
-    "better-sqlite3": "^12.9.0",
     "nanoid": "^5.1.7"
   },
+  "peerDependencies": {
+    "better-sqlite3": "^12.9.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^25.6.0",
+    "better-sqlite3": "^12.9.0",
     "typescript": "^6.0.2",
     "vitest": "^4.1.4"
   }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d50c0cdb5..13a6faaa3 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -846,9 +846,6 @@ importers:
       '@objectstack/spec':
         specifier: workspace:*
         version: link:../../spec
-      better-sqlite3:
-        specifier: ^12.9.0
-        version: 12.9.0
       nanoid:
         specifier: ^5.1.7
         version: 5.1.7
@@ -856,6 +853,9 @@ importers:
       '@types/node':
         specifier: ^25.6.0
         version: 25.6.0
+      better-sqlite3:
+        specifier: ^12.9.0
+        version: 12.9.0
       typescript:
         specifier: ^6.0.2
         version: 6.0.2