@miden-sdk/create-miden-para-react 0.10.10

package/README.md

@@ -0,0 +1,20 @@
+# @miden-sdk/create-miden-para-react
+
+`npm create @miden-sdk/miden-para-react@latest my-app` scaffolds the latest Vite `react-ts` starter, overwrites it with this repo's `vite.config.ts`, swaps in a Para + Miden-ready `App.tsx`, and adds the deps needed to run it out of the box. The scaffold always runs `create-vite` with `--yes --no-install` and pipes “no” to the install prompt to prevent upstream installs from overwriting the template before we patch it.
+
+## What it does
+- Runs `npm create vite@latest <target> -- --template react-ts` so you always start from the upstream default.
+- Replaces `vite.config.ts` with the Para + Miden-friendly config (dedupe/exclude and WASM asset handling).
+- Replaces `src/App.tsx` with a ParaProvider + `useParaMiden` starter that reports the account ID and client readiness.
+- Adds Para/Miden + connector deps (matching `examples/react`) so Para SDK peers resolve: `@miden-sdk/miden-para`, `@miden-sdk/use-miden-para-react`, `@getpara/react-sdk-lite`, `@getpara/evm-wallet-connectors`, `@demox-labs/miden-sdk`, `@tanstack/react-query`, `@wagmi/core`, `viem`, `wagmi`, plus dev plugins `vite-plugin-node-polyfills`, `vite-plugin-wasm`, and `vite-plugin-top-level-await`.
+- Installs dependencies using your detected package manager (`pnpm`, `yarn`, `bun`, or falls back to `npm`); `create-vite` is invoked with `--yes --no-install` and auto-answers “no” to install prompts to avoid reverting the patched files.
+- Writes `.npmrc` with `legacy-peer-deps=true` so `npm install` works despite a known peer mismatch between `@miden-sdk/use-miden-para-react` and `@miden-sdk/miden-para`.
+- Adds `src/polyfills.ts` and injects it into `src/main.tsx` to provide `Buffer`/`process` in the browser.
+
+## Usage
+- Standard: `npm create @miden-sdk/miden-para-react@latest my-new-app`
+- Skip install: add `--skip-install` if you want to install later.
+- Set `VITE_PARA_API_KEY` in a `.env.local` (or similar) file so the generated `App.tsx` can initialize Para. **Production deployments require a Para production API key.**
+- Recommended next steps: `cd my-new-app && npm install && npm run dev` (`.npmrc` opts into legacy peer deps so npm works).
+
+Publish from this folder with `npm publish --access public` when you're ready. For local testing, run `node ./packages/create-miden-para-react/bin/create-miden-para-react.mjs my-app`.

package/bin/create-miden-para-react.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const templateConfigPath = resolve(__dirname, "..", "template", "vite.config.ts");
+const templateAppPath = resolve(__dirname, "..", "template", "src", "App.tsx");
+const templatePolyfillsPath = resolve(__dirname, "..", "template", "src", "polyfills.ts");
+const templateOptionalConnectorsPath = resolve(
+  __dirname,
+  "..",
+  "template",
+  "src",
+  "optional-connectors.ts"
+);
+const repoRoot = resolve(__dirname, "..", "..", "..");
+const localMidenParaPath =
+  process.env.MIDEN_PARA_LOCAL_MIDEN_PARA_PATH ?? repoRoot;
+const localUseMidenParaReactPath =
+  process.env.MIDEN_PARA_LOCAL_USE_PARA_REACT_PATH ??
+  resolve(repoRoot, "packages", "use-miden-para-react");
+const useLocalDeps = process.env.MIDEN_PARA_LOCAL_DEPS === "1";
+
+const args = process.argv.slice(2);
+const target = args.find((arg) => !arg.startsWith("-")) ?? "miden-para-react-app";
+const skipInstall = args.some(
+  (flag) => flag === "--skip-install" || flag === "--no-install",
+);
+const skipScaffold =
+  args.some((flag) => flag === "--skip-scaffold" || flag === "--no-scaffold") ||
+  process.env.MIDEN_PARA_TEST_MODE === "1";
+const targetDir = resolve(process.cwd(), target);
+const targetParent = dirname(targetDir);
+const targetName = basename(targetDir);
+const baseEnv = {
+  ...process.env,
+  CI: process.env.CI ?? "true",
+  npm_config_yes: process.env.npm_config_yes ?? "true",
+};
+
+ensureTargetParent();
+if (skipScaffold) {
+  scaffoldMinimalProject(targetDir, targetName);
+} else {
+  runCreateVite(targetName);
+}
+overrideViteConfig(targetDir);
+overrideApp(targetDir);
+ensurePolyfills(targetDir);
+ensureOptionalConnectorsShim(targetDir);
+ensurePolyfillDependency(targetDir);
+ensureMidenParaDependencies(targetDir);
+ensureNpmRc(targetDir);
+logEnvReminder(targetName);
+
+if (!skipInstall) {
+  installDependencies(targetDir);
+} else {
+  logStep("Skipped dependency installation (--skip-install)");
+}
+
+function ensureTargetParent() {
+  mkdirSync(targetParent, { recursive: true });
+}
+
+function runCreateVite(targetArg) {
+  const scaffoldArgs = [
+    "create",
+    "vite@latest",
+    targetArg,
+    "--",
+    "--template",
+    "react-ts",
+    "--yes", // avoid interactive prompts that might install/revert files
+    "--no-install", // we handle installs after patching package.json
+  ];
+  runOrExit("npm", scaffoldArgs, targetParent, baseEnv, "n\n");
+}
+
+function scaffoldMinimalProject(targetRoot, name) {
+  mkdirSync(targetRoot, { recursive: true });
+  const pkgPath = join(targetRoot, "package.json");
+  if (!existsSync(pkgPath)) {
+    const pkg = {
+      name,
+      private: true,
+      version: "0.0.0",
+      type: "module",
+      scripts: {
+        dev: "vite",
+        build: "vite build",
+        preview: "vite preview",
+      },
+      dependencies: {
+        react: "^18.2.0",
+        "react-dom": "^18.2.0",
+      },
+      devDependencies: {
+        "@types/react": "^18.2.0",
+        "@types/react-dom": "^18.2.0",
+        "@vitejs/plugin-react": "^4.2.0",
+        typescript: "^5.2.2",
+        vite: "^5.2.0",
+      },
+    };
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  }
+
+  const srcDir = join(targetRoot, "src");
+  mkdirSync(srcDir, { recursive: true });
+  const mainPath = join(srcDir, "main.tsx");
+  if (!existsSync(mainPath)) {
+    writeFileSync(
+      mainPath,
+      `import React from "react";\nimport ReactDOM from "react-dom/client";\nimport App from "./App";\n\nReactDOM.createRoot(document.getElementById("root")!).render(<App />);\n`
+    );
+  }
+  const appPath = join(srcDir, "App.tsx");
+  if (!existsSync(appPath)) {
+    writeFileSync(appPath, "export default function App() { return null; }\n");
+  }
+}
+
+function overrideViteConfig(targetRoot) {
+  const dest = join(targetRoot, "vite.config.ts");
+  copyFileSync(templateConfigPath, dest);
+}
+
+function overrideApp(targetRoot) {
+  const dest = join(targetRoot, "src", "App.tsx");
+  mkdirSync(join(targetRoot, "src"), { recursive: true });
+  logStep(`Replacing App.tsx with Para + Miden starter at ${dest}`);
+  copyFileSync(templateAppPath, dest);
+}
+
+function ensurePolyfills(targetRoot) {
+  const dest = join(targetRoot, "src", "polyfills.ts");
+  mkdirSync(join(targetRoot, "src"), { recursive: true });
+  copyFileSync(templatePolyfillsPath, dest);
+
+  const mainPath = join(targetRoot, "src", "main.tsx");
+  if (existsSync(mainPath)) {
+    const main = readFileSync(mainPath, "utf8");
+    if (!main.includes('./polyfills') && !main.includes("./polyfills")) {
+      writeFileSync(mainPath, `import "./polyfills";\n${main}`);
+      logStep(`Injected polyfills import into ${mainPath}`);
+    }
+  }
+}
+
+function ensureOptionalConnectorsShim(targetRoot) {
+  const dest = join(targetRoot, "src", "optional-connectors.ts");
+  mkdirSync(join(targetRoot, "src"), { recursive: true });
+  copyFileSync(templateOptionalConnectorsPath, dest);
+}
+
+function ensurePolyfillDependency(targetRoot) {
+  const pkgPath = join(targetRoot, "package.json");
+  if (!existsSync(pkgPath)) {
+    logStep("No package.json found after scaffolding; nothing to patch");
+    return;
+  }
+
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  pkg.devDependencies = pkg.devDependencies ?? {};
+  pkg.devDependencies["vite-plugin-node-polyfills"] ??= "^0.24.0";
+  pkg.devDependencies["vite-plugin-wasm"] ??= "^3.5.0";
+  pkg.devDependencies["vite-plugin-top-level-await"] ??= "^1.6.0";
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  logStep("Added Vite plugin deps (polyfills/wasm/top-level-await)");
+}
+
+function ensureNpmRc(targetRoot) {
+  const npmrcPath = join(targetRoot, ".npmrc");
+  const line = "legacy-peer-deps=true";
+  if (existsSync(npmrcPath)) {
+    const contents = readFileSync(npmrcPath, "utf8");
+    if (contents.includes(line)) {
+      logStep("Existing .npmrc already opts into legacy-peer-deps");
+      return;
+    }
+    writeFileSync(npmrcPath, `${contents.trim()}\n${line}\n`);
+    logStep("Updated .npmrc to include legacy-peer-deps");
+    return;
+  }
+  writeFileSync(npmrcPath, `${line}\n`);
+  logStep("Created .npmrc with legacy-peer-deps=true");
+}
+
+function ensureMidenParaDependencies(targetRoot) {
+  const pkgPath = join(targetRoot, "package.json");
+  if (!existsSync(pkgPath)) {
+    logStep("No package.json found after scaffolding; cannot add dependencies");
+    return;
+  }
+
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  pkg.dependencies = pkg.dependencies ?? {};
+  pkg.devDependencies = pkg.devDependencies ?? {};
+  pkg.resolutions = pkg.resolutions ?? {};
+  pkg.scripts = pkg.scripts ?? {};
+  const midenParaVersion = useLocalDeps
+    ? `file:${localMidenParaPath}`
+    : "0.10.10";
+  const useMidenParaReactVersion = useLocalDeps
+    ? `file:${localUseMidenParaReactPath}`
+    : "^0.10.10";
+  // Align with examples/react so Para SDK connector peers are satisfied
+  Object.assign(pkg.dependencies, {
+    ...pkg.dependencies,
+    "@getpara/react-sdk-lite": "2.0.0-alpha.73",
+    "@getpara/evm-wallet-connectors": "^2.3.0",
+    "@tanstack/react-query": "^5.90.12",
+    "@wagmi/core": "^3.0.0",
+    "@demox-labs/miden-sdk": "^0.12.5",
+    "@miden-sdk/miden-para": midenParaVersion,
+    "@miden-sdk/use-miden-para-react": useMidenParaReactVersion,
+    viem: "^2.41.2",
+    wagmi: "^3.1.0",
+  });
+
+  Object.assign(pkg.devDependencies, {
+    ...pkg.devDependencies,
+    "vite-plugin-node-polyfills": "^0.24.0",
+    "vite-plugin-wasm": "^3.5.0",
+    "vite-plugin-top-level-await": "^1.6.0",
+  });
+
+
+  Object.assign(pkg.resolutions, {
+    "@getpara/react-sdk": "2.0.0-alpha.73",
+    "@getpara/web-sdk": "2.0.0-alpha.73",
+  });
+
+  Object.assign(pkg.scripts, {
+    ...pkg.scripts,
+    'postinstall': 'setup-para'
+  });
+
+  delete pkg.peerDependencies;
+
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  logStep("Added Para + Miden starter dependencies");
+}
+
+function installDependencies(targetRoot) {
+  const pm = detectPackageManager();
+  logStep(`Installing dependencies with ${pm.command}`);
+  runOrExit(pm.command, pm.args, targetRoot);
+}
+
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent || "";
+  if (ua.startsWith("pnpm")) return { command: "pnpm", args: ["install"] };
+  if (ua.startsWith("yarn")) return { command: "yarn", args: [] };
+  if (ua.startsWith("bun")) return { command: "bun", args: ["install"] };
+  return { command: "npm", args: ["install"] };
+}
+
+function runOrExit(command, args, cwd, env, input) {
+  const result = spawnSync(command, args, {
+    stdio: input ? ["pipe", "inherit", "inherit"] : "inherit",
+    input,
+    cwd,
+    env,
+  });
+
+  if (result.error) {
+    console.error(result.error);
+    process.exit(1);
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function logStep(message) {
+  console.log(`\n> ${message}`);
+}
+
+function logEnvReminder(dirName) {
+  logStep(
+    `Remember to use VITE_PARA_API_KEY like this:\n  cd ${dirName}\n  VITE_PARA_API_KEY=... npm run dev`,
+  );
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@miden-sdk/create-miden-para-react",
+  "version": "0.10.10",
+  "description": "Create a Vite react-ts app preconfigured with Miden + Para's Vite setup",
+  "type": "module",
+  "bin": {
+    "create-miden-para-react": "./bin/create-miden-para-react.mjs"
+  },
+  "files": [
+    "bin",
+    "template",
+    "README.md",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Miden Labs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0xMiden/miden-para",
+    "directory": "packages/create-miden-para-react"
+  },
+  "bugs": {
+    "url": "https://github.com/0xMiden/miden-para/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "create-vite",
+    "vite",
+    "react",
+    "typescript",
+    "miden",
+    "para"
+  ],
+  "scripts": {
+    "publish": "npm publish"
+  }
+}

package/template/src/App.tsx

@@ -0,0 +1,46 @@
+import './App.css';
+import '@getpara/react-sdk-lite/styles.css';
+import { ParaProvider, useAccount, useModal } from '@getpara/react-sdk-lite';
+import { useParaMiden } from '@miden-sdk/use-miden-para-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ParaProvider
+        paraClientConfig={{
+          apiKey: import.meta.env.VITE_PARA_API_KEY,
+        }}
+        config={{ appName: 'Starter for MidenxPara' }}
+      >
+        <Content />
+      </ParaProvider>
+    </QueryClientProvider>
+  );
+}
+
+function Content() {
+  const { client, accountId, para } = useParaMiden(
+    'https://rpc.testnet.miden.io'
+  );
+  const { isConnected } = useAccount();
+  const { openModal } = useModal();
+
+  return (
+    <div>
+      <button onClick={() => (isConnected ? para?.logout() : openModal?.())}>
+        {isConnected ? 'Disconnect Para' : 'Connect with Para'}
+      </button>
+      {isConnected && (
+        <>
+          <p>Account: {accountId ?? '—'}</p>
+          <p>Client ready: {client ? 'yes' : 'no'}</p>
+        </>
+      )}
+    </div>
+  );
+}
+
+export default App;

package/template/src/optional-connectors.ts

@@ -0,0 +1 @@
+export {};

package/template/src/polyfills.ts

@@ -0,0 +1,11 @@
+import { Buffer } from "buffer";
+import process from "process";
+
+// Ensure Node globals exist when dependencies expect them in the browser.
+if (!globalThis.Buffer) {
+  globalThis.Buffer = Buffer;
+}
+
+if (!globalThis.process) {
+  globalThis.process = process;
+}

package/template/vite.config.ts

@@ -0,0 +1,64 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { nodePolyfills } from 'vite-plugin-node-polyfills';
+import wasm from 'vite-plugin-wasm';
+import topLevelAwait from 'vite-plugin-top-level-await';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const optionalConnectorsPath = path.resolve(
+  __dirname,
+  'src',
+  'optional-connectors.ts'
+);
+
+// Keep the miden SDK unbundled so its WASM asset path stays valid in dev.
+export default defineConfig({
+  plugins: [
+    wasm(),
+    topLevelAwait(),
+    react(),
+    nodePolyfills({
+      include: ['buffer', 'crypto', 'stream', 'util'],
+    }),
+  ],
+  optimizeDeps: {
+    // Keep Miden SDK unbundled and avoid prebundling Para's Stencil component bundles
+    // to prevent multiple runtimes in dev.
+    exclude: [
+      '@demox-labs/miden-sdk',
+      '@getpara/solana-wallet-connectors',
+      '@getpara/cosmos-wallet-connectors',
+    ],
+    esbuildOptions: {
+      target: 'esnext',
+    },
+  },
+  build: {
+    target: 'esnext',
+    rollupOptions: {
+      external: [
+        '@getpara/solana-wallet-connectors',
+        '@getpara/cosmos-wallet-connectors',
+      ],
+    },
+  },
+  worker: {
+    format: 'es',
+  },
+  resolve: {
+    dedupe: ['@getpara/web-sdk', '@getpara/react-sdk-lite'],
+    alias: {
+      '@getpara/solana-wallet-connectors': optionalConnectorsPath,
+      '@getpara/cosmos-wallet-connectors': optionalConnectorsPath,
+    },
+  },
+  // Ensure Vite treats wasm as a static asset with the correct MIME type.
+  assetsInclude: ['**/*.wasm'],
+  server: {
+    fs: {
+      allow: [process.cwd()],
+    },
+  },
+});