create-solana-mobile-app 1.1.1

package/README.md

@@ -0,0 +1,109 @@
+# create-solana-mobile-app
+
+CLI to scaffold Expo + Solana Mobile starter apps with Mobile Wallet Adapter support.
+
+## What It Creates
+
+This tool generates a new Expo TypeScript app and injects Solana-ready starter code.
+
+You can choose one of two variants:
+
+- `--kit-only`: Solana Kit provider and logic only.
+- `--wallet-ui`: Solana Kit provider plus a ready-made wallet button UI.
+
+## Prerequisites
+
+- Node.js 18+
+- npm
+- Android development environment (for Solana Mobile testing)
+- Expo dev client workflow (`expo run:android`), not Expo Go
+
+## Usage
+
+### Create a New App
+
+```bash
+npx create-solana-mobile-app <app-name> --kit-only
+```
+
+or
+
+```bash
+npx create-solana-mobile-app <app-name> --wallet-ui
+```
+
+If no variant flag is provided, `--kit-only` is used by default.
+
+### Run the App
+
+```bash
+cd <app-name>
+npx expo run:android
+```
+
+## Environment
+
+You can optionally set a custom RPC URL:
+
+```bash
+EXPO_PUBLIC_RPC_URL=https://api.devnet.solana.com
+```
+
+If not set, the starter defaults to Solana devnet.
+
+## Generated Project Includes
+
+- `@solana/kit`
+- `@solana-mobile/mobile-wallet-adapter-protocol-web3js`
+- `react-native-quick-crypto`
+- `buffer`
+- Metro config updates for crypto/buffer compatibility
+- Buffer polyfill injection in app entry file
+
+## Local Development (This Repo)
+
+Run the CLI directly from source:
+
+```bash
+node index.js my-app --wallet-ui
+```
+
+## Publish to npm
+
+1. Update `package.json` version.
+2. Login to npm:
+
+```bash
+npm login
+```
+
+3. Check package contents:
+
+```bash
+npm pack --dry-run
+```
+
+4. Publish:
+
+```bash
+npm publish --access public
+```
+
+## Troubleshooting
+
+### "Wallet connected, but no valid base58 account address was returned"
+
+Use the latest package version. Recent updates normalize wallet account addresses returned in multiple formats (base58, base64/base64url, and raw bytes).
+
+### Android build issues
+
+- Confirm Android SDK and emulator/device are configured.
+- Rebuild the app after dependency changes:
+
+```bash
+npx expo run:android
+```
+
+## License
+
+ISC

package/index.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+const fs = require("fs-extra");
+const path = require("path");
+
+const args = process.argv.slice(2);
+const appName = args[0];
+const flags = {
+  kitOnly: args.includes("--kit-only"),
+  walletUI: args.includes("--wallet-ui"),
+};
+
+const TEMPLATE_DIR = "template";
+const DEFAULT_RPC_URL = "https://api.devnet.solana.com";
+
+async function loadDeps() {
+  const { execa } = await import("execa");
+  const { default: chalk } = await import("chalk");
+  return { execa, chalk };
+}
+
+function makeAndroidPackageId(name) {
+  const safe = name.toLowerCase().replace(/[^a-z0-9]+/g, "");
+  const suffix = safe.length > 0 ? safe : "app";
+  return `com.solanamobile.${suffix}`;
+}
+
+async function ensureAndroidPackage(appPath, appNameArg) {
+  const appJsonPath = path.join(appPath, "app.json");
+  if (!(await fs.pathExists(appJsonPath))) {
+    return;
+  }
+
+  const appJson = await fs.readJson(appJsonPath);
+  appJson.expo = appJson.expo || {};
+  appJson.expo.android = appJson.expo.android || {};
+
+  if (!appJson.expo.android.package) {
+    appJson.expo.android.package = makeAndroidPackageId(appNameArg);
+    await fs.writeJson(appJsonPath, appJson, { spaces: 2 });
+  }
+}
+
+async function injectBufferPolyfill(appPath) {
+  const candidates = [
+    "App.tsx",
+    "App.js",
+    path.join("app", "_layout.tsx"),
+    path.join("app", "_layout.js"),
+    path.join("app", "index.tsx"),
+    path.join("app", "index.js"),
+  ];
+
+  let targetFile = null;
+  for (const relativePath of candidates) {
+    const filePath = path.join(appPath, relativePath);
+    if (await fs.pathExists(filePath)) {
+      targetFile = filePath;
+      break;
+    }
+  }
+
+  if (!targetFile) {
+    throw new Error(
+      "Could not find an app entry file for Buffer polyfill injection.",
+    );
+  }
+
+  const content = await fs.readFile(targetFile, "utf-8");
+  if (content.includes("global.Buffer = Buffer")) {
+    return;
+  }
+
+  const withPolyfill = `import { Buffer } from 'buffer';\nglobal.Buffer = Buffer;\n\n${content}`;
+  await fs.writeFile(targetFile, withPolyfill);
+}
+
+async function createApp() {
+  const { execa, chalk } = await loadDeps();
+
+  if (!appName) {
+    console.log(
+      "Please provide app name. Usage: create-solana-mobile-app <app-name> [--kit-only|--wallet-ui]",
+    );
+    process.exit(1);
+  }
+
+  if (flags.kitOnly && flags.walletUI) {
+    console.log(
+      chalk.red("Choose only one variant: --kit-only or --wallet-ui."),
+    );
+    process.exit(1);
+  }
+
+  const variant = flags.walletUI ? "wallet-ui" : "kit-only";
+  const templatePath = path.join(__dirname, TEMPLATE_DIR, variant, "src");
+  if (!(await fs.pathExists(templatePath))) {
+    throw new Error(`Template variant not found: ${variant}`);
+  }
+
+  console.log(chalk.blue(`Creating ${appName} (${variant})...`));
+
+  await execa(
+    "npx",
+    [
+      "create-expo-app@latest",
+      appName,
+      "--template",
+      "blank-typescript",
+      "--yes",
+    ],
+    { stdio: "inherit" },
+  );
+
+  const appPath = path.join(process.cwd(), appName);
+
+  await ensureAndroidPackage(appPath, appName);
+
+  console.log(chalk.yellow("Installing Solana mobile dependencies..."));
+  await execa(
+    "npm",
+    [
+      "install",
+      "@solana/kit",
+      "@solana-mobile/mobile-wallet-adapter-protocol-web3js",
+      "react-native-quick-crypto",
+      "buffer",
+    ],
+    { cwd: appPath, stdio: "inherit" },
+  );
+
+  console.log(chalk.yellow("Configuring Metro..."));
+  const metroConfig = `const { getDefaultConfig } = require('expo/metro-config');
+
+const config = getDefaultConfig(__dirname);
+
+config.resolver.extraNodeModules = {
+  ...(config.resolver.extraNodeModules || {}),
+  crypto: require.resolve('react-native-quick-crypto'),
+  buffer: require.resolve('buffer'),
+};
+
+module.exports = config;
+`;
+  await fs.writeFile(path.join(appPath, "metro.config.js"), metroConfig);
+
+  await injectBufferPolyfill(appPath);
+
+  console.log(chalk.yellow("Injecting starter template..."));
+  await fs.copy(templatePath, path.join(appPath, "src"), { overwrite: true });
+
+  const rootApp = `import App from './src/App';
+
+export default App;
+`;
+  await fs.writeFile(path.join(appPath, "App.tsx"), rootApp);
+
+  await fs.writeFile(
+    path.join(appPath, ".env"),
+    `EXPO_PUBLIC_RPC_URL=${DEFAULT_RPC_URL}\n`,
+  );
+
+  console.log(chalk.yellow("Installing Expo Dev Client..."));
+  await execa("npx", ["expo", "install", "expo-dev-client"], {
+    cwd: appPath,
+    stdio: "inherit",
+  });
+
+  console.log(
+    chalk.green(
+      `\nSolana mobile starter is ready.\n\nNext steps:\ncd ${appName}\nnpx expo run:android\n`,
+    ),
+  );
+}
+
+createApp().catch((error) => {
+  console.error("Failed to scaffold Solana mobile app.");
+  if (error && error.shortMessage) {
+    console.error(error.shortMessage);
+  } else {
+    console.error(error && error.message ? error.message : error);
+  }
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "create-solana-mobile-app",
+  "version": "1.1.1",
+  "description": "",
+  "main": "index.js",
+  "bin": {
+    "create-solana-mobile-app": "index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "execa": "^9.6.1",
+    "expo": "^55.0.8",
+    "fs-extra": "^11.3.4",
+    "ora": "^9.3.0"
+  }
+}

package/template/kit-only/src/App.tsx

@@ -0,0 +1,312 @@
+import React, { useMemo, useState } from "react";
+import {
+  ActivityIndicator,
+  Alert,
+  Pressable,
+  ScrollView,
+  StyleSheet,
+  Text,
+  View,
+} from "react-native";
+import { SolanaProvider } from "./provider/SolanaProvider";
+import { useWallet } from "./hooks/useWallet";
+
+const LAMPORTS_PER_SOL = 1_000_000_000;
+
+function shortAddress(value: string | null): string {
+  if (!value) {
+    return "-";
+  }
+  if (value.length < 12) {
+    return value;
+  }
+  return `${value.slice(0, 6)}...${value.slice(-6)}`;
+}
+
+function PrimaryButton({
+  label,
+  onPress,
+  disabled,
+  subtle,
+}: {
+  label: string;
+  onPress: () => void | Promise<void>;
+  disabled?: boolean;
+  subtle?: boolean;
+}) {
+  return (
+    <Pressable
+      onPress={onPress}
+      disabled={disabled}
+      style={({ pressed }) => [
+        styles.button,
+        subtle ? styles.subtleButton : styles.primaryButton,
+        pressed && !disabled ? styles.buttonPressed : null,
+        disabled ? styles.buttonDisabled : null,
+      ]}
+    >
+      <Text style={[styles.buttonText, subtle ? styles.subtleText : null]}>
+        {label}
+      </Text>
+    </Pressable>
+  );
+}
+
+function Home() {
+  const { wallet, connectWallet, getBalance } = useWallet();
+  const [balance, setBalance] = useState<bigint | null>(null);
+  const [busy, setBusy] = useState<false | "connect" | "balance">(false);
+
+  const balanceSol = useMemo(() => {
+    if (balance === null) {
+      return "-";
+    }
+    return (Number(balance) / LAMPORTS_PER_SOL).toFixed(6);
+  }, [balance]);
+
+  const runAction = async (
+    op: "connect" | "balance",
+    action: () => Promise<void>,
+  ) => {
+    setBusy(op);
+    try {
+      await action();
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Unexpected wallet error.";
+      Alert.alert("Solana Starter", message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <ScrollView contentContainerStyle={styles.container}>
+      <View style={styles.backdropOrbA} />
+      <View style={styles.backdropOrbB} />
+
+      <View style={styles.heroCard}>
+        <Text style={styles.eyebrow}>Solana Mobile Starter</Text>
+        <Text style={styles.title}>Kit-first Wallet Starter</Text>
+        <Text style={styles.subtitle}>
+          Production-lean starter with Mobile Wallet Adapter auth and Solana Kit
+          RPC.
+        </Text>
+      </View>
+
+      <View style={styles.panel}>
+        <Text style={styles.panelTitle}>Wallet</Text>
+        <View style={styles.rowBetween}>
+          <Text style={styles.label}>Status</Text>
+          <Text style={styles.value}>
+            {wallet.connected ? "Connected" : "Disconnected"}
+          </Text>
+        </View>
+        <View style={styles.rowBetween}>
+          <Text style={styles.label}>Address</Text>
+          <Text style={styles.mono}>{shortAddress(wallet.address)}</Text>
+        </View>
+        <View style={styles.rowBetween}>
+          <Text style={styles.label}>Balance</Text>
+          <Text style={styles.value}>{balanceSol} SOL</Text>
+        </View>
+
+        <View style={styles.buttonRow}>
+          <PrimaryButton
+            label={busy === "connect" ? "Connecting..." : "Connect Wallet"}
+            onPress={() => runAction("connect", connectWallet)}
+            disabled={busy !== false}
+          />
+          <PrimaryButton
+            label={busy === "balance" ? "Refreshing..." : "Get Balance"}
+            onPress={() =>
+              runAction("balance", async () => {
+                const bal = await getBalance();
+                setBalance(bal);
+              })
+            }
+            disabled={!wallet.connected || busy !== false}
+            subtle
+          />
+        </View>
+      </View>
+
+      <View style={styles.panelMuted}>
+        <Text style={styles.panelMutedTitle}>Dev Build Only</Text>
+        <Text style={styles.helper}>
+          This app requires a custom dev build because Solana mobile
+          dependencies use native modules.
+        </Text>
+      </View>
+
+      {busy !== false ? (
+        <View style={styles.loadingPill}>
+          <ActivityIndicator color="#f6f8fb" />
+        </View>
+      ) : null}
+    </ScrollView>
+  );
+}
+
+export default function App() {
+  return (
+    <SolanaProvider>
+      <Home />
+    </SolanaProvider>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    minHeight: "100%",
+    backgroundColor: "#07111f",
+    padding: 18,
+    gap: 14,
+  },
+  backdropOrbA: {
+    position: "absolute",
+    width: 220,
+    height: 220,
+    borderRadius: 999,
+    right: -70,
+    top: -40,
+    backgroundColor: "rgba(0, 204, 255, 0.18)",
+  },
+  backdropOrbB: {
+    position: "absolute",
+    width: 180,
+    height: 180,
+    borderRadius: 999,
+    left: -60,
+    top: 210,
+    backgroundColor: "rgba(255, 163, 26, 0.14)",
+  },
+  heroCard: {
+    marginTop: 8,
+    backgroundColor: "#0c1b31",
+    borderWidth: 1,
+    borderColor: "#214167",
+    borderRadius: 24,
+    padding: 18,
+    gap: 8,
+  },
+  eyebrow: {
+    color: "#8ec5ff",
+    fontSize: 12,
+    letterSpacing: 1.2,
+    textTransform: "uppercase",
+    fontWeight: "700",
+  },
+  title: {
+    color: "#f6f8fb",
+    fontSize: 30,
+    lineHeight: 34,
+    fontWeight: "800",
+  },
+  subtitle: {
+    color: "#bdd5ee",
+    fontSize: 14,
+    lineHeight: 21,
+  },
+  panel: {
+    backgroundColor: "#112744",
+    borderRadius: 20,
+    padding: 16,
+    borderWidth: 1,
+    borderColor: "#295381",
+    gap: 10,
+  },
+  panelTitle: {
+    color: "#f6f8fb",
+    fontSize: 18,
+    fontWeight: "700",
+  },
+  panelMuted: {
+    backgroundColor: "#0e1c31",
+    borderRadius: 18,
+    padding: 14,
+    borderWidth: 1,
+    borderColor: "#273d5a",
+    gap: 8,
+  },
+  panelMutedTitle: {
+    color: "#f6f8fb",
+    fontSize: 15,
+    fontWeight: "700",
+  },
+  helper: {
+    color: "#aac3dd",
+    fontSize: 13,
+    lineHeight: 19,
+  },
+  rowBetween: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    alignItems: "center",
+    gap: 10,
+  },
+  label: {
+    color: "#9ec0df",
+    fontSize: 12,
+    textTransform: "uppercase",
+    letterSpacing: 0.8,
+  },
+  value: {
+    color: "#eff6ff",
+    fontSize: 14,
+    fontWeight: "700",
+  },
+  mono: {
+    color: "#e8f1fb",
+    fontFamily: "monospace",
+    fontSize: 13,
+    maxWidth: "66%",
+  },
+  buttonRow: {
+    flexDirection: "row",
+    gap: 10,
+    marginTop: 6,
+  },
+  button: {
+    minHeight: 46,
+    borderRadius: 14,
+    paddingHorizontal: 14,
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  primaryButton: {
+    backgroundColor: "#00a8e8",
+  },
+  subtleButton: {
+    backgroundColor: "#1c3a5c",
+    borderWidth: 1,
+    borderColor: "#3c628c",
+  },
+  buttonText: {
+    color: "#032038",
+    fontWeight: "800",
+    fontSize: 13,
+  },
+  subtleText: {
+    color: "#d6e8fa",
+  },
+  buttonPressed: {
+    opacity: 0.9,
+    transform: [{ scale: 0.98 }],
+  },
+  buttonDisabled: {
+    opacity: 0.45,
+  },
+  loadingPill: {
+    position: "absolute",
+    right: 16,
+    bottom: 16,
+    paddingVertical: 10,
+    paddingHorizontal: 12,
+    borderRadius: 999,
+    backgroundColor: "rgba(4, 17, 31, 0.95)",
+    borderWidth: 1,
+    borderColor: "#2c5078",
+  },
+});

package/template/kit-only/src/components/WalletButton.tsx

@@ -0,0 +1,9 @@
+import React from "react";
+import { Button } from "react-native";
+import { useWallet } from "../hooks/useWallet";
+
+export default function WalletButton() {
+  const { connectWallet } = useWallet();
+
+  return <Button title="Connect Wallet UI" onPress={connectWallet} />;
+}

package/template/kit-only/src/hooks/useWallet.ts

@@ -0,0 +1,8 @@
+import { useContext } from "react";
+import { SolanaContext } from "../provider/SolanaProvider";
+
+export const useWallet = () => {
+  const ctx = useContext(SolanaContext);
+  if (!ctx) throw new Error("Wrap app in SolanaProvider");
+  return ctx;
+};