From 622d282723f8a6ce95fd38ecda9e88c8351c2edc Mon Sep 17 00:00:00 2001 From: michaelbarnes Date: Wed, 28 Jan 2026 11:32:49 -0700 Subject: [PATCH 1/3] docs: Add Content Security Policy requirements for Web SDK Add CSP documentation explaining the wasm-unsafe-eval requirement for PowerSync Web SDK. This addresses a common production deployment issue where PowerSync fails in Safari due to missing CSP directives. Key additions: - Explanation of why wasm-unsafe-eval is required - Security considerations and comparison to unsafe-eval - Browser compatibility information - Links to official WASM CSP documentation Resolves customer support inquiry about CSP requirements. Co-Authored-By: Craft Agent --- client-sdks/reference/javascript-web.mdx | 35 ++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index bbfe1093..df2b5db3 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -80,6 +80,41 @@ The PowerSync [JavaScript Web SDK](../javascript-web) is compatible with popular +## Production Deployment Requirements + +### Content Security Policy (CSP) + + +**Required for Production:** Your Content Security Policy `script-src` directive must include `'wasm-unsafe-eval'` for PowerSync to work, particularly in Safari. + + +PowerSync Web SDK requires the `wasm-unsafe-eval` directive in your Content Security Policy headers to function correctly. + +**Why it's required:** + +PowerSync uses [wa-sqlite](https://www.npmjs.com/package/@journeyapps/wa-sqlite), which requires WebAssembly compilation at runtime to bind JavaScript functions to SQLite internals. Without `wasm-unsafe-eval`, browsers will block WebAssembly module instantiation, preventing PowerSync from functioning. + +**Proper CSP configuration:** + +``` +Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'; +``` + +**Security considerations:** + +- `wasm-unsafe-eval` only permits WebAssembly compilation (NOT JavaScript `eval()`) +- This is more secure than `unsafe-eval`, which permits both WASM and JavaScript eval +- It's the industry-standard directive for WASM-based applications +- WebAssembly has strong security boundaries and memory isolation + + +Safari's strict CSP enforcement will block PowerSync functionality if this directive is missing. Modern browsers (Safari 15.2+, Chrome 95+, Firefox 102+) all support `wasm-unsafe-eval`. + + +**Additional resources:** +- [SQLite WASM CSP Documentation](https://sqlite.org/wasm/doc/trunk/csp.md) +- [WebAssembly CSP Specification](https://github.com/WebAssembly/content-security-policy/blob/main/proposals/CSP.md) + ## Getting Started **Prerequisites**: To sync data between your client-side app and your backend source database, you must have completed the necessary setup for PowerSync, which includes connecting your source database to the PowerSync Service and deploying Sync Rules (steps 1-4 in the [Setup Guide](/intro/setup-guide)). From 26d06b93125023d6fb94d84e48f781a722f44c56 Mon Sep 17 00:00:00 2001 From: michaelbarnes Date: Wed, 28 Jan 2026 11:44:21 -0700 Subject: [PATCH 2/3] docs: Move CSP section to Developer Notes Relocate Content Security Policy documentation from early in the document to the Developer Notes section for better organization. Co-Authored-By: Craft Agent --- client-sdks/reference/javascript-web.mdx | 68 ++++++++++++------------ 1 file changed, 33 insertions(+), 35 deletions(-) diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index df2b5db3..e007f44b 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -80,41 +80,6 @@ The PowerSync [JavaScript Web SDK](../javascript-web) is compatible with popular -## Production Deployment Requirements - -### Content Security Policy (CSP) - - -**Required for Production:** Your Content Security Policy `script-src` directive must include `'wasm-unsafe-eval'` for PowerSync to work, particularly in Safari. - - -PowerSync Web SDK requires the `wasm-unsafe-eval` directive in your Content Security Policy headers to function correctly. - -**Why it's required:** - -PowerSync uses [wa-sqlite](https://www.npmjs.com/package/@journeyapps/wa-sqlite), which requires WebAssembly compilation at runtime to bind JavaScript functions to SQLite internals. Without `wasm-unsafe-eval`, browsers will block WebAssembly module instantiation, preventing PowerSync from functioning. - -**Proper CSP configuration:** - -``` -Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'; -``` - -**Security considerations:** - -- `wasm-unsafe-eval` only permits WebAssembly compilation (NOT JavaScript `eval()`) -- This is more secure than `unsafe-eval`, which permits both WASM and JavaScript eval -- It's the industry-standard directive for WASM-based applications -- WebAssembly has strong security boundaries and memory isolation - - -Safari's strict CSP enforcement will block PowerSync functionality if this directive is missing. Modern browsers (Safari 15.2+, Chrome 95+, Firefox 102+) all support `wasm-unsafe-eval`. - - -**Additional resources:** -- [SQLite WASM CSP Documentation](https://sqlite.org/wasm/doc/trunk/csp.md) -- [WebAssembly CSP Specification](https://github.com/WebAssembly/content-security-policy/blob/main/proposals/CSP.md) - ## Getting Started **Prerequisites**: To sync data between your client-side app and your backend source database, you must have completed the necessary setup for PowerSync, which includes connecting your source database to the PowerSync Service and deploying Sync Rules (steps 1-4 in the [Setup Guide](/intro/setup-guide)). @@ -386,6 +351,39 @@ pnpm upgrade @powersync/web @journeyapps/wa-sqlite ## Developer Notes +### Content Security Policy (CSP) + + +**Required for Production:** Your Content Security Policy `script-src` directive must include `'wasm-unsafe-eval'` for PowerSync to work, particularly in Safari. + + +PowerSync Web SDK requires the `wasm-unsafe-eval` directive in your Content Security Policy headers to function correctly. + +**Why it's required:** + +PowerSync uses [wa-sqlite](https://www.npmjs.com/package/@journeyapps/wa-sqlite), which requires WebAssembly compilation at runtime to bind JavaScript functions to SQLite internals. Without `wasm-unsafe-eval`, browsers will block WebAssembly module instantiation, preventing PowerSync from functioning. + +**Proper CSP configuration:** + +``` +Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'; +``` + +**Security considerations:** + +- `wasm-unsafe-eval` only permits WebAssembly compilation (NOT JavaScript `eval()`) +- This is more secure than `unsafe-eval`, which permits both WASM and JavaScript eval +- It's the industry-standard directive for WASM-based applications +- WebAssembly has strong security boundaries and memory isolation + + +Safari's strict CSP enforcement will block PowerSync functionality if this directive is missing. Modern browsers (Safari 15.2+, Chrome 95+, Firefox 102+) all support `wasm-unsafe-eval`. + + +**Additional resources:** +- [SQLite WASM CSP Documentation](https://sqlite.org/wasm/doc/trunk/csp.md) +- [WebAssembly CSP Specification](https://github.com/WebAssembly/content-security-policy/blob/main/proposals/CSP.md) + ### Connection Methods This SDK supports two methods for streaming sync commands: From a87220bfff294634b2c11ce815fe3778f2819404 Mon Sep 17 00:00:00 2001 From: michaelbarnes Date: Wed, 28 Jan 2026 12:52:31 -0700 Subject: [PATCH 3/3] chore: removed references as we use wa-sqlite and not the official wasm build --- client-sdks/reference/javascript-web.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index e007f44b..f35489ea 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -380,10 +380,6 @@ Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'; Safari's strict CSP enforcement will block PowerSync functionality if this directive is missing. Modern browsers (Safari 15.2+, Chrome 95+, Firefox 102+) all support `wasm-unsafe-eval`. -**Additional resources:** -- [SQLite WASM CSP Documentation](https://sqlite.org/wasm/doc/trunk/csp.md) -- [WebAssembly CSP Specification](https://github.com/WebAssembly/content-security-policy/blob/main/proposals/CSP.md) - ### Connection Methods This SDK supports two methods for streaming sync commands: