SCHY-148 Use miniflare to test changes in a cloudflare-esque environment to catch issues (#92)

* use miniflare to test builds in a cloudflare environment ( to smoke test cloud flare issues early)

* add replicator/datastream readme

* use webassembly.compile over webassembly.module

* add mroe cloudflare tests cases

* remove console.log

* move cloudflare-compat job to a different workflow to avoid fern regeneration issues

* saving this here for later

* remove cloudflare check from ci for now

* Add cloudflare test script to CI (restoring from removing it in earlier PR)

---------

Co-authored-by: Christopher Brady <chris@schematichq.com>

Author: ryanechternacht

.fernignore

@@ -2,6 +2,7 @@
 
 .claude/
 .github/CODEOWNERS
+.github/workflows/cloudflare.yml
 CLAUDE.md
 LICENSE
 README.md
@@ -19,6 +20,7 @@ src/version.ts
 src/wasm/
 src/webhooks.ts
 src/wrapper.ts
+tests/cloudflare/
 tests/unit/cache/local.test.ts
 tests/unit/datastream/datastream-client.test.ts
 tests/unit/datastream/websocket-client.test.ts

.github/workflows/cloudflare.yml

@@ -0,0 +1,22 @@
+name: cloudflare-compat
+
+on: [push]
+
+jobs:
+  cloudflare-compat:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v6
+
+      - name: Set up node
+        uses: actions/setup-node@v6
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build
+        run: yarn build
+
+      - name: Test Cloudflare compatibility
+        run: yarn test:cloudflare

README.md

@@ -601,6 +601,97 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
 }
 ```
 
+## DataStream
+
+DataStream enables local flag evaluation by maintaining a WebSocket connection to Schematic and caching flag rules, company, and user data locally.
+
+> **Runtime compatibility:** DataStream requires Node.js APIs (`WebSocket`, `EventEmitter`) and is not supported in edge runtimes such as Cloudflare Workers, Vercel Edge Functions, or Deno Deploy. For these runtimes, use [Replicator Mode](#replicator-mode) instead.
+
+### Setup
+
+```ts
+import { SchematicClient } from "@schematichq/schematic-typescript-node";
+
+const client = new SchematicClient({
+    apiKey: process.env.SCHEMATIC_API_KEY,
+    useDataStream: true,
+});
+
+// Flag checks are now evaluated locally
+const flagValue = await client.checkFlag(
+    { company: { id: "your-company-id" } },
+    "some-flag-key",
+);
+
+client.close();
+```
+
+### Configuration options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `cacheTTL` | `number` | 24 hours | Cache TTL in milliseconds |
+| `redisClient` | `RedisClient` | — | Redis client for shared caching (uses in-memory cache if not provided) |
+| `redisKeyPrefix` | `string` | `schematic:` | Key prefix for Redis cache entries |
+
+```ts
+import { createClient } from "redis";
+import { SchematicClient } from "@schematichq/schematic-typescript-node";
+
+const redisClient = createClient({ url: "redis://localhost:6379" });
+await redisClient.connect();
+
+const client = new SchematicClient({
+    apiKey: process.env.SCHEMATIC_API_KEY,
+    useDataStream: true,
+    dataStream: {
+        redisClient,
+        redisKeyPrefix: "schematic:",
+        cacheTTL: 60 * 60 * 1000, // 1 hour
+    },
+});
+```
+
+## Replicator Mode
+
+Replicator mode is designed for environments where a separate process (the replicator) manages the WebSocket connection and populates a shared cache. The SDK reads from that cache and evaluates flags locally without establishing its own WebSocket connection.
+
+### Requirements
+
+Replicator mode requires a shared cache (Redis or custom cache providers) so the SDK can read data written by the external replicator process.
+
+### Setup
+
+```ts
+import { createClient } from "redis";
+import { SchematicClient } from "@schematichq/schematic-typescript-node";
+
+const redisClient = createClient({ url: "redis://localhost:6379" });
+await redisClient.connect();
+
+const client = new SchematicClient({
+    apiKey: process.env.SCHEMATIC_API_KEY,
+    useDataStream: true,
+    dataStream: {
+        replicatorMode: true,
+        redisClient,
+        replicatorHealthURL: "http://localhost:8080/health",
+        replicatorHealthCheck: 30000, // 30 seconds
+    },
+});
+```
+
+### Configuration options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `replicatorMode` | `boolean` | `false` | Enable replicator mode |
+| `redisClient` | `RedisClient` | — | **Required.** Redis client for reading from the shared cache |
+| `redisKeyPrefix` | `string` | `schematic:` | Key prefix for Redis cache entries |
+| `replicatorHealthURL` | `string` | — | URL to poll for replicator health status |
+| `replicatorHealthCheck` | `number` | 30000 | Health check polling interval in milliseconds |
+| `cacheTTL` | `number` | 24 hours | Cache TTL in milliseconds |
+
 ## Testing
 
 ### Offline mode

package.json

@@ -25,29 +25,29 @@
         "test:cloudflare": "node scripts/test-cloudflare.mjs"
     },
     "dependencies": {
+        "@types/ws": "^8.18.1",
         "form-data": "^4.0.4",
         "formdata-node": "^6.0.3",
         "node-fetch": "^2.7.0",
         "readable-stream": "^4.5.2",
-        "ws": "^8.18.1",
-        "@types/ws": "^8.18.1"
+        "ws": "^8.18.1"
     },
     "devDependencies": {
+        "@biomejs/biome": "2.3.1",
+        "@jest/globals": "^29.7.0",
+        "@types/jest": "^29.5.14",
+        "@types/node": "^18.19.70",
         "@types/node-fetch": "^2.6.12",
         "@types/readable-stream": "^4.0.18",
-        "webpack": "^5.97.1",
-        "ts-loader": "^9.5.1",
+        "esbuild": "^0.25.9",
         "jest": "^29.7.0",
-        "@jest/globals": "^29.7.0",
-        "@types/jest": "^29.5.14",
-        "ts-jest": "^29.3.4",
         "jest-environment-jsdom": "^29.7.0",
+        "miniflare": "^4.20260305.0",
         "msw": "2.11.2",
-        "@types/node": "^18.19.70",
+        "ts-jest": "^29.3.4",
+        "ts-loader": "^9.5.1",
         "typescript": "~5.7.2",
-        "@biomejs/biome": "2.3.1",
-        "esbuild": "^0.25.9",
-        "miniflare": "^4.20260305.0"
+        "webpack": "^5.97.1"
     },
     "browser": {
         "fs": false,

scripts/test-cloudflare.mjs

@@ -0,0 +1,33 @@
+import { build } from "esbuild";
+import { Miniflare } from "miniflare";
+
+// Bundle the worker entry + all external deps into a single ESM file.
+// platform: 'browser' mirrors how Wrangler bundles for Workers (no Node.js globals assumed).
+// nodejs_compat in Miniflare provides runtime polyfills for Node built-ins.
+const result = await build({
+  entryPoints: ["tests/cloudflare/worker.mjs"],
+  bundle: true,
+  format: "esm",
+  target: "esnext",
+  platform: "browser",
+  write: false,
+});
+
+const mf = new Miniflare({
+  modules: true,
+  script: result.outputFiles[0].text,
+  compatibilityFlags: ["nodejs_compat"],
+  compatibilityDate: "2024-09-23",
+});
+
+try {
+  const res = await mf.dispatchFetch("http://localhost/");
+  const text = await res.text();
+  if (!res.ok) {
+    console.error("❌ Cloudflare compatibility test failed:", text);
+    process.exit(1);
+  }
+  console.log("✅ Cloudflare compatibility test passed!");
+} finally {
+  await mf.dispose();
+}

src/rules-engine.ts

@@ -1,5 +1,5 @@
 import * as Schematic from './api/types';
-import { RulesEngineJS } from './wasm/rulesengine.js';
+import { RulesEngineJS, initWasm } from './wasm/rulesengine.js';
 
 /** Entitlement details returned by the WASM rules engine  */
 export interface WasmFeatureEntitlement {
@@ -50,6 +50,7 @@ export class RulesEngineClient {
         }
 
         try {
+            await initWasm();
             this.wasmInstance = new RulesEngineJS();
             this.initialized = true;
         } catch (error) {

src/wasm/rulesengine.d.ts

@@ -1,5 +1,6 @@
 /* tslint:disable */
 /* eslint-disable */
+export function initWasm(): Promise<void>;
 export class RulesEngineJS {
   free(): void;
   [Symbol.dispose](): void;

src/wasm/rulesengine.js

@@ -192,10 +192,14 @@ exports.__wbindgen_init_externref_table = function() {
     ;
 };
 
-const wasmBase64 = require('./rulesengine_bg_wasm_base64.js');
-const wasmBytes = Uint8Array.from(atob(wasmBase64), c => c.charCodeAt(0));
-const wasmModule = new WebAssembly.Module(wasmBytes);
-const wasm = exports.__wasm = new WebAssembly.Instance(wasmModule, imports).exports;
-
-wasm.__wbindgen_start();
+let wasm;
+
+exports.initWasm = async function() {
+    if (wasm) return;
+    const wasmBase64 = require('./rulesengine_bg_wasm_base64.js');
+    const wasmBytes = Uint8Array.from(atob(wasmBase64), c => c.charCodeAt(0));
+    const wasmModule = await WebAssembly.compile(wasmBytes);
+    wasm = exports.__wasm = (await WebAssembly.instantiate(wasmModule, imports)).exports;
+    wasm.__wbindgen_start();
+};
 

src/wrapper.ts

@@ -549,4 +549,4 @@ export class SchematicClient extends BaseClient {
     }
 }
 
-export class Schematic extends SchematicClient {}
+export class Schematic extends SchematicClient {}

tests/cloudflare/worker.mjs

@@ -0,0 +1,32 @@
+import { SchematicClient } from "../../dist/index.js";
+
+export default {
+  async fetch(request, env, ctx) {
+    const results = [];
+
+    // Test 1: Offline mode — basic import and instantiation
+    try {
+      const client = new SchematicClient({ offline: true });
+      await client.close();
+      results.push("offline-mode: ok");
+    } catch (e) {
+      return new Response("offline-mode: " + e.message, { status: 500 });
+    }
+
+    // Test 2: DataStream in non-replicator mode should be blocked in edge runtime
+    try {
+      const client = new SchematicClient({
+        apiKey: "test_key",
+        useDataStream: true,
+      });
+      // DataStream should have been disabled (no datastreamClient created)
+      // but the client should still be functional
+      await client.close();
+      results.push("datastream-blocked: ok");
+    } catch (e) {
+      return new Response("datastream-blocked: " + e.message, { status: 500 });
+    }
+
+    return new Response(results.join("\n"));
+  },
+};