@miden-sdk/react 0.14.2 → 0.14.4

package/README.md

@@ -119,6 +119,64 @@ function App() {
 }
 ```
 
+## Next.js & SSR
+
+The React SDK is Next.js-compatible out of the box: it ships two bundle variants built from a single source tree, and both internally import `@miden-sdk/miden-sdk/lazy` — the lazy entry point that does **not** use a top-level `await`. Nothing initializes WASM at module evaluation, so server-side rendering never hangs.
+
+- Default (`@miden-sdk/react`) — internally consumes the eager SDK. Use this in plain browser apps, Vite, CRA.
+- `@miden-sdk/react/lazy` — internally consumes the lazy SDK. Use this in Next.js (app router or pages), SSR, or inside a Capacitor iOS/Android WKWebView host (the wallet shell uses this).
+
+Both exports have identical APIs. The choice only affects which `@miden-sdk/miden-sdk` variant your bundler ends up resolving.
+
+```tsx
+// Next.js: app/providers.tsx
+"use client";
+
+import { MidenProvider } from "@miden-sdk/react/lazy";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <MidenProvider config={{ rpcUrl: "testnet" }}>{children}</MidenProvider>;
+}
+```
+
+`MidenProvider` gates child rendering on `isReady`, so you don't have to await anything manually in components — hooks already fire only after WASM is initialized.
+
+### Constructing wasm-bindgen types directly in Next.js
+
+Hooks accept strings for account IDs, asset IDs, and note IDs (auto-detecting hex vs. bech32) and parse them internally inside async callbacks, so **most apps never touch wasm-bindgen types directly**. If you do need to (e.g. to inspect an ID's prefix/suffix, validate a pasted string, or use a low-level API like `new Felt(…)`), import from `@miden-sdk/miden-sdk/lazy` and gate the call on `isReady`:
+
+```tsx
+import { useEffect, useState } from "react";
+import { useMiden } from "@miden-sdk/react/lazy";
+import { AccountId } from "@miden-sdk/miden-sdk/lazy";
+
+function IdInspector({ idString }: { idString: string }) {
+  const { isReady } = useMiden();
+  const [isFaucet, setIsFaucet] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    if (!isReady) return;
+    // AccountId.fromBech32/fromHex is synchronous but touches WASM — run it
+    // only after the provider reports ready.
+    const id = idString.startsWith("miden1")
+      ? AccountId.fromBech32(idString)
+      : AccountId.fromHex(idString);
+    setIsFaucet(id.isFaucet());
+  }, [isReady, idString]);
+
+  return <span>{isFaucet === null ? "…" : isFaucet ? "faucet" : "wallet"}</span>;
+}
+```
+
+Alternatively, await `MidenClient.ready()` directly — it's idempotent and shares its in-flight promise with `MidenProvider`, so calling it from tutorial helpers or ad-hoc code has no cost:
+
+```ts
+import { MidenClient, AccountId } from "@miden-sdk/miden-sdk/lazy";
+
+await MidenClient.ready();
+const id = AccountId.fromBech32("miden1…"); // safe
+```
+
 ## Hooks Reference
 
 ### Core Hooks

package/dist/index.d.mts

@@ -1,10 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { AccountId, Account, AccountHeader, AccountStorageMode, AccountComponent, NoteId, InputNoteRecord, Note, StorageMode, AuthScheme, TransactionScript, AdviceInputs, AccountStorageRequirements, TransactionRequest, WasmWebClient, AccountFile, NoteVisibility, ConsumableNoteRecord, TransactionId, TransactionFilter, TransactionRecord, TransactionProver, CompileComponentOptions, CompileTxScriptOptions, CompileNoteScriptOptions, NoteScript, NoteAttachment } from '@miden-sdk/miden-sdk';
-export { Account, AccountFile, AccountHeader, AccountId, AccountStorageMode, AuthScheme, ConsumableNoteRecord, InputNoteRecord, Note, NoteType, TransactionFilter, TransactionId, TransactionRecord, TransactionRequest, WasmWebClient as WebClient } from '@miden-sdk/miden-sdk';
+import { AccountId, Account, AccountHeader, AccountStorageMode, AccountComponent, NoteId, InputNoteRecord, Note, StorageMode, AuthScheme, TransactionScript, AdviceInputs, AccountStorageRequirements, TransactionRequest, WasmWebClient, AccountFile, NoteVisibility, ConsumableNoteRecord, TransactionId, TransactionFilter, TransactionRecord, TransactionProver, CompileComponentOptions, CompileTxScriptOptions, CompileNoteScriptOptions, NoteScript, NoteAttachment } from '@miden-sdk/miden-sdk/lazy';
+export { Account, AccountFile, AccountHeader, AccountId, AccountStorageMode, AuthScheme, ConsumableNoteRecord, InputNoteRecord, Note, NoteType, TransactionFilter, TransactionId, TransactionRecord, TransactionRequest, WasmWebClient as WebClient } from '@miden-sdk/miden-sdk/lazy';
 
-declare module "@miden-sdk/miden-sdk" {
+declare module "@miden-sdk/miden-sdk/lazy" {
     interface Account {
         /** Returns the bech32-encoded account id using the configured network. */
         bech32id(): string;

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { AccountId, Account, AccountHeader, AccountStorageMode, AccountComponent, NoteId, InputNoteRecord, Note, StorageMode, AuthScheme, TransactionScript, AdviceInputs, AccountStorageRequirements, TransactionRequest, WasmWebClient, AccountFile, NoteVisibility, ConsumableNoteRecord, TransactionId, TransactionFilter, TransactionRecord, TransactionProver, CompileComponentOptions, CompileTxScriptOptions, CompileNoteScriptOptions, NoteScript, NoteAttachment } from '@miden-sdk/miden-sdk';
-export { Account, AccountFile, AccountHeader, AccountId, AccountStorageMode, AuthScheme, ConsumableNoteRecord, InputNoteRecord, Note, NoteType, TransactionFilter, TransactionId, TransactionRecord, TransactionRequest, WasmWebClient as WebClient } from '@miden-sdk/miden-sdk';
+import { AccountId, Account, AccountHeader, AccountStorageMode, AccountComponent, NoteId, InputNoteRecord, Note, StorageMode, AuthScheme, TransactionScript, AdviceInputs, AccountStorageRequirements, TransactionRequest, WasmWebClient, AccountFile, NoteVisibility, ConsumableNoteRecord, TransactionId, TransactionFilter, TransactionRecord, TransactionProver, CompileComponentOptions, CompileTxScriptOptions, CompileNoteScriptOptions, NoteScript, NoteAttachment } from '@miden-sdk/miden-sdk/lazy';
+export { Account, AccountFile, AccountHeader, AccountId, AccountStorageMode, AuthScheme, ConsumableNoteRecord, InputNoteRecord, Note, NoteType, TransactionFilter, TransactionId, TransactionRecord, TransactionRequest, WasmWebClient as WebClient } from '@miden-sdk/miden-sdk/lazy';
 
-declare module "@miden-sdk/miden-sdk" {
+declare module "@miden-sdk/miden-sdk/lazy" {
     interface Account {
         /** Returns the bech32-encoded account id using the configured network. */
         bech32id(): string;