create-avalanche-app 0.1.0

package/templates/minimal/components/demo.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import { getWalletClient } from "@avakit/core";
+import {
+  Button,
+  ConnectAvalanche,
+  shortenAddress,
+  useAvaAccount,
+  useAvaChain,
+  useAvaKit,
+  useBalance,
+} from "@avakit/react";
+import { Moon, Sun } from "lucide-react";
+import { useTheme } from "next-themes";
+import { useState } from "react";
+import { formatEther } from "viem";
+
+function ThemeToggle() {
+  const { resolvedTheme, setTheme } = useTheme();
+  return (
+    <Button
+      variant="outline"
+      size="icon"
+      aria-label="Toggle theme"
+      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
+    >
+      <Sun className="hidden size-4 dark:block" />
+      <Moon className="block size-4 dark:hidden" />
+    </Button>
+  );
+}
+
+export function Demo() {
+  const { address, isConnected } = useAvaAccount();
+  const { chain } = useAvaChain();
+  const { provider } = useAvaKit();
+  const { data: balance, isLoading, refetch } = useBalance();
+  const [txHash, setTxHash] = useState<string | null>(null);
+  const [txError, setTxError] = useState<string | null>(null);
+  const [sending, setSending] = useState(false);
+
+  async function sendTestTx() {
+    if (!provider || !address) return;
+    setSending(true);
+    setTxError(null);
+    setTxHash(null);
+    try {
+      const wallet = getWalletClient(chain, provider);
+      const hash = await wallet.sendTransaction({
+        account: address,
+        to: address,
+        value: 0n,
+      } as Parameters<typeof wallet.sendTransaction>[0]);
+      setTxHash(hash);
+      void refetch();
+    } catch (e) {
+      setTxError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setSending(false);
+    }
+  }
+
+  return (
+    <div className="mx-auto flex min-h-dvh max-w-xl flex-col gap-8 px-6 py-16">
+      <header className="flex items-center justify-between">
+        <span className="font-mono text-sm font-semibold">__PROJECT_NAME__</span>
+        <div className="flex items-center gap-2">
+          <ConnectAvalanche />
+          <ThemeToggle />
+        </div>
+      </header>
+
+      <div className="flex flex-col gap-2">
+        <h1 className="text-3xl font-semibold tracking-tight">Your first transaction on Avalanche</h1>
+        <p className="text-muted-foreground text-sm">
+          Connect a wallet, read your balance, and send a 0-AVAX transaction to yourself on{" "}
+          {chain.name}.
+        </p>
+      </div>
+
+      {isConnected && address ? (
+        <div className="flex flex-col gap-4 rounded-xl border p-6">
+          <Row label="Network" value={chain.name} />
+          <Row label="Address" value={shortenAddress(address, 6)} mono />
+          <Row
+            label="Balance"
+            value={isLoading ? "…" : `${formatEther(balance ?? 0n)} ${chain.nativeCurrency.symbol}`}
+            mono
+          />
+
+          <div className="flex flex-col gap-2 pt-2">
+            <Button onClick={sendTestTx} disabled={sending}>
+              {sending ? "Sending…" : "Send 0 AVAX to myself"}
+            </Button>
+            {chain.faucetUrl ? (
+              <a
+                href={chain.faucetUrl}
+                target="_blank"
+                rel="noreferrer"
+                className="text-muted-foreground text-center text-xs underline underline-offset-4"
+              >
+                Need test AVAX? Open the faucet
+              </a>
+            ) : null}
+          </div>
+
+          {txHash ? (
+            <a
+              href={`${chain.explorerUrl}/tx/${txHash}`}
+              target="_blank"
+              rel="noreferrer"
+              className="text-sm break-all underline underline-offset-4"
+            >
+              ✓ Sent: {txHash}
+            </a>
+          ) : null}
+          {txError ? <p className="text-muted-foreground text-sm">{txError}</p> : null}
+        </div>
+      ) : (
+        <div className="text-muted-foreground rounded-xl border border-dashed p-10 text-center text-sm">
+          Connect a wallet to begin.
+        </div>
+      )}
+    </div>
+  );
+}
+
+function Row({ label, value, mono }: { label: string; value: string; mono?: boolean }) {
+  return (
+    <div className="flex items-center justify-between gap-4">
+      <span className="text-muted-foreground text-sm">{label}</span>
+      <span className={mono ? "font-mono text-sm" : "text-sm"}>{value}</span>
+    </div>
+  );
+}

package/templates/minimal/cursor/rules/avakit.mdc

@@ -0,0 +1,28 @@
+---
+description: AvaKit + Avalanche conventions for this project
+globs: ["**/*.ts", "**/*.tsx", "**/*.css"]
+alwaysApply: true
+---
+
+# AvaKit project rules
+
+This is an Avalanche dapp built with AvaKit (`@avakit/react` + `@avakit/core`).
+
+## UI
+
+- Use **shadcn/ui only**. `@avakit/react` ships shadcn-styled components — match that style.
+- **Black & white only** for now. Dark/light is wired via `next-themes`; every screen must work in both. Add brand colors later by editing the tokens in `app/globals.css`.
+- Animations: **Framer Motion** or **GSAP** only.
+
+## Wallet & chain
+
+- Wallet button: `<ConnectAvalanche />`.
+- Read state with hooks: `useAvaAccount`, `useAvaChain`, `useBalance`, `useContract`.
+- For raw transactions, get a viem wallet client: `getWalletClient(chain, provider)` where `provider` comes from `useAvaKit()`.
+- Default chain is Fuji testnet. Mainnet requires explicit opt-in.
+
+## Safety
+
+- Never hardcode RPC URLs or secrets. Use the chain config and `.env.local`.
+- Private keys live in the wallet provider, never in app code.
+- Social login requires `NEXT_PUBLIC_WEB3AUTH_CLIENT_ID` (free, dashboard.web3auth.io).

package/templates/minimal/env.example

@@ -0,0 +1,4 @@
+# Web3Auth (MetaMask Embedded Wallets) — free client ID for social login.
+# Get one at https://dashboard.web3auth.io (Sapphire Devnet, EVM).
+# Public value, safe to expose. Leave empty to use only the browser wallet.
+NEXT_PUBLIC_WEB3AUTH_CLIENT_ID=

package/templates/minimal/gitignore

@@ -0,0 +1,10 @@
+node_modules/
+.next/
+out/
+*.tsbuildinfo
+next-env.d.ts
+.env
+.env.*
+!.env.example
+.DS_Store
+*.log

package/templates/minimal/llms.txt

@@ -0,0 +1,30 @@
+# __PROJECT_NAME__
+
+> An Avalanche dapp scaffolded with AvaKit (https://github.com/mericcintosun/AvaKit). Next.js + @avakit/react + shadcn/ui. Social-login onboarding, deploy-ready, black & white with dark/light from day one.
+
+## Project map
+
+- [app/providers.tsx](app/providers.tsx): AvaKitProvider (chains + wallet adapters) and theme provider.
+- [app/layout.tsx](app/layout.tsx): root layout and fonts.
+- [app/page.tsx](app/page.tsx): renders the demo.
+- [components/demo.tsx](components/demo.tsx): connect wallet, read balance, send a transaction.
+- [app/globals.css](app/globals.css): shadcn tokens (black & white) + dark/light.
+- [CLAUDE.md](CLAUDE.md): agent guide with the AvaKit API and project rules.
+
+## Key APIs (@avakit/react)
+
+- `<AvaKitProvider chains={[...]} adapters={[...]}>`
+- `<ConnectAvalanche />` — drop-in wallet button
+- `useAvaAccount()`, `useAvaChain()`, `useBalance()`, `useContract()`, `useAvaDeploy()`, `useAvaKit()`
+
+## Key APIs (@avakit/core)
+
+- `fuji`, `cChain`, `defineChain` from `@avakit/core/chains`
+- `injectedAdapter()`, `web3authAdapter({ clientId })` (from `@avakit/core/web3auth`)
+- `getPublicClient`, `getWalletClient`, `ensureChain`, `deployContract`, `getBalance`, `readContract`
+
+## External docs
+
+- Avalanche Builder Hub: https://build.avax.network/llms.txt
+- Web3Auth dashboard (free client ID): https://dashboard.web3auth.io
+- Fuji faucet: https://core.app/tools/testnet-faucet

package/templates/minimal/manifest.json

@@ -0,0 +1,6 @@
+{
+  "id": "minimal",
+  "title": "Minimal",
+  "description": "Social-login wallet, balance, and a first transaction",
+  "contracts": false
+}

package/templates/minimal/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+};
+
+export default nextConfig;

package/templates/minimal/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@avakit/core": "__AVAKIT_DEP__",
+    "@avakit/react": "__AVAKIT_DEP__",
+    "lucide-react": "1.22.0",
+    "next": "16.2.9",
+    "next-themes": "0.4.6",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "viem": "2.54.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "4.3.2",
+    "@types/node": "26.0.1",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "postcss": "8.5.16",
+    "tailwindcss": "4.3.2",
+    "tw-animate-css": "1.4.0",
+    "typescript": "6.0.3"
+  }
+}

package/templates/minimal/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/templates/minimal/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/nft-mint/CLAUDE.md

@@ -0,0 +1,45 @@
+# __PROJECT_NAME__ — Avalanche NFT dapp (scaffolded with AvaKit)
+
+Operational guide for AI agents (Claude Code / Cursor) working in this project.
+
+## Stack
+
+Next.js 16 (App Router) · React 19 · `@avakit/react` · `@avakit/core` · viem · shadcn/ui · next-themes · Foundry (contract)
+
+## Architecture
+
+- `contracts/src/AvaKitNFT.sol` — a minimal, self-contained ERC-721 mint contract
+- `lib/nft-artifact.ts` — the compiled ABI + bytecode (so the app deploys from the browser with no Foundry at runtime)
+- `app/providers.tsx` — `<AvaKitProvider>` (chains + wallet adapters) + `ThemeProvider`
+- `components/demo.tsx` — deploy the contract, then mint
+
+## The flow
+
+1. Connect a wallet (`<ConnectAvalanche />`).
+2. Deploy: `useAvaDeploy().deploy({ abi, bytecode })` → returns the contract address.
+3. Mint: `useContract({ address, abi }).write("mint", [])`.
+4. Read state: `useContract(...).read("totalSupply")`, `.read("balanceOf", [address])`.
+
+## Editing the contract
+
+The bundled `lib/nft-artifact.ts` is generated from the Solidity source. After changing `contracts/src/AvaKitNFT.sol`:
+
+```bash
+cd contracts && forge build
+# then copy out/AvaKitNFT.sol/AvaKitNFT.json's abi + bytecode.object into lib/nft-artifact.ts
+```
+
+## Rules
+
+- UI uses **shadcn/ui only** (components from `@avakit/react` are shadcn-styled).
+- **Black & white only** for now; dark/light via `next-themes`. Add brand colors later in `app/globals.css`.
+- Animations: **Framer Motion** or **GSAP** only.
+- Never hardcode secrets; private keys live in the wallet provider.
+- Deploying/minting costs gas — fund the wallet on Fuji first (in-app faucet link).
+- Social login needs `NEXT_PUBLIC_WEB3AUTH_CLIENT_ID` in `.env.local` (free, dashboard.web3auth.io).
+
+## Commands
+
+- `pnpm dev` — dev server (http://localhost:3000)
+- `pnpm build` — production build
+- `cd contracts && forge build` — recompile the contract

package/templates/nft-mint/README.md

@@ -0,0 +1,36 @@
+# __PROJECT_NAME__
+
+An Avalanche **NFT mint** dapp scaffolded with [AvaKit](https://github.com/mericcintosun/AvaKit). Deploy an ERC-721 from your browser, then mint — no Foundry required to run it.
+
+## Getting started
+
+```bash
+# 1. (social login, optional) add a free Web3Auth client ID
+cp .env.example .env.local
+#    → https://dashboard.web3auth.io (Sapphire Devnet, EVM)
+
+# 2. run it
+pnpm dev    # http://localhost:3000
+```
+
+Then: connect a wallet → **Deploy NFT contract** → **Mint NFT**. Deploying and minting cost gas, so fund your wallet on Fuji first (in-app faucet link).
+
+## How the contract works
+
+- `contracts/src/AvaKitNFT.sol` — a minimal, self-contained ERC-721 (no external deps; compiles with `forge build` out of the box).
+- `lib/nft-artifact.ts` — the compiled ABI + bytecode, bundled so the app can deploy straight from the browser via `useAvaDeploy()`.
+
+To change the contract:
+
+```bash
+cd contracts && forge build
+# copy out/AvaKitNFT.sol/AvaKitNFT.json (abi + bytecode.object) into lib/nft-artifact.ts
+```
+
+## Stack
+
+Next.js 16 · `@avakit/react` · `@avakit/core` · viem · shadcn/ui · Foundry
+
+## AI-native
+
+Ships with `CLAUDE.md`, `llms.txt`, and `.cursor/rules` so Claude Code / Cursor understand AvaKit, the deploy/mint flow, and the contract workflow.

package/templates/nft-mint/app/globals.css

@@ -0,0 +1,95 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+
+/* Scan @avakit/react's shadcn-style classes from node_modules. */
+@source "../node_modules/@avakit/react/dist";
+
+@custom-variant dark (&:is(.dark *));
+
+/*
+ * Black & white only (oklch chroma 0 = pure grayscale). Dark/light wired from
+ * day one via next-themes. Add brand colors later by editing these tokens —
+ * components never hardcode colors.
+ */
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.3 0 0);
+  --destructive-foreground: oklch(0.985 0 0);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.985 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.7 0 0);
+  --destructive-foreground: oklch(0.205 0 0);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+
+@layer base {
+  * {
+    border-color: var(--border);
+  }
+  body {
+    background-color: var(--background);
+    color: var(--foreground);
+  }
+}

package/templates/nft-mint/app/layout.tsx

@@ -0,0 +1,23 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import type { ReactNode } from "react";
+import { Providers } from "./providers";
+import "./globals.css";
+
+const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"] });
+const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"] });
+
+export const metadata: Metadata = {
+  title: "__PROJECT_NAME__",
+  description: "An Avalanche dapp scaffolded with AvaKit.",
+};
+
+export default function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={`${geistSans.variable} ${geistMono.variable} font-sans antialiased`}>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}

package/templates/nft-mint/app/page.tsx

@@ -0,0 +1,5 @@
+import { Demo } from "@/components/demo";
+
+export default function Home() {
+  return <Demo />;
+}

package/templates/nft-mint/app/providers.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { type WalletAdapter, injectedAdapter } from "@avakit/core";
+import { __CHAIN_CONST__ } from "@avakit/core/chains";
+import { web3authAdapter } from "@avakit/core/web3auth";
+import { AvaKitProvider } from "@avakit/react";
+import { ThemeProvider } from "next-themes";
+import { type ReactNode, useMemo } from "react";
+
+export function Providers({ children }: { children: ReactNode }) {
+  const adapters = useMemo(() => {
+    const list: WalletAdapter[] = [];
+    // Social login appears only when a Web3Auth client ID is configured.
+    const clientId = process.env.NEXT_PUBLIC_WEB3AUTH_CLIENT_ID;
+    if (clientId) {
+      list.push(web3authAdapter({ clientId }));
+    }
+    // Injected (Core / MetaMask) is always available.
+    list.push(injectedAdapter());
+    return list;
+  }, []);
+
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+      <AvaKitProvider chains={[__CHAIN_CONST__]} adapters={adapters}>
+        {children}
+      </AvaKitProvider>
+    </ThemeProvider>
+  );
+}