@iblai/iblai-js 1.0.8 → 1.0.9

package/README.md

@@ -30,6 +30,39 @@ npm install react react-dom @reduxjs/toolkit react-redux @iblai/iblai-api
 
 `next` (>= 15) is an **optional** peer dependency, required only when using `@iblai/iblai-js/web-containers/next`.
 
+## Framework Configuration
+
+### Next.js
+
+The SDK ships pre-compiled with `'use client'` directives already applied to client components. **Do not** add `@iblai/iblai-js` or its sub-packages (`@iblai/data-layer`, `@iblai/web-containers`, `@iblai/web-utils`) to `transpilePackages` in your `next.config.ts` — they are ready to use as-is.
+
+```typescript
+// next.config.ts
+const nextConfig = {
+  // Do NOT add @iblai packages here — they ship pre-built dist files
+  // transpilePackages: ['@iblai/iblai-js'], // ← Don't do this
+};
+```
+
+### Node.js 25+
+
+If you're running Node.js 25 or later, you **must** disable the experimental Web Storage API in Node.js. Without this flag, Node.js provides a server-side `localStorage` that conflicts with the SDK's browser-only storage guards, causing hydration errors and runtime failures.
+
+Add this to your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "NODE_OPTIONS='--no-experimental-webstorage' next dev",
+    "start": "NODE_OPTIONS='--no-experimental-webstorage' next start"
+  }
+}
+```
+
+### Vite / CRA / Other React Frameworks
+
+No special configuration required. Install and import directly.
+
 ## Quick Start
 
 ### 1. Initialize the data layer
@@ -328,6 +361,27 @@ pnpm build
 
 Produces CommonJS, ESM, and TypeScript declaration files under `dist/`.
 
+## Publishing (Maintainers)
+
+This package uses `workspace:*` references for its dependencies on `@iblai/data-layer`, `@iblai/web-containers`, and `@iblai/web-utils`. These are automatically converted to real version numbers during publish.
+
+**You must use `pnpm publish` (not `npm publish`) to publish this package.** Only `pnpm publish` converts `workspace:` references to actual version numbers. Using `npm publish` will publish with raw `workspace:*` strings, which breaks installation for all external consumers.
+
+```bash
+# Correct — converts workspace:* to resolved versions
+pnpm publish --no-git-checks
+
+# Wrong — leaves workspace:* in published package.json
+npm publish  # ← Never use this for workspace packages
+```
+
+Publish the underlying packages first (in dependency order), then this package:
+
+1. `@iblai/data-layer` — no internal deps
+2. `@iblai/web-utils` — depends on data-layer
+3. `@iblai/web-containers` — depends on data-layer and web-utils
+4. `@iblai/iblai-js` — depends on all three
+
 ## License
 
 ISC

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iblai/iblai-js",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Unified JavaScript SDK for IBL.ai — re-exports data-layer, web-containers, and web-utils under a single package",
   "type": "module",
   "engines": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iblai/iblai-js",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Unified JavaScript SDK for IBL.ai — re-exports data-layer, web-containers, and web-utils under a single package",
   "type": "module",
   "engines": {
@@ -47,7 +47,7 @@
   "author": "iblai",
   "license": "ISC",
   "dependencies": {
-    "@iblai/data-layer": "1.1.4",
+    "@iblai/data-layer": "1.1.5",
     "@iblai/web-containers": "1.1.7",
     "@iblai/web-utils": "1.1.8"
   },