From 2bfd4db678defc4ffc06e553ccfcc5aca70414ed Mon Sep 17 00:00:00 2001 From: William H Date: Thu, 12 Feb 2026 09:40:14 +0100 Subject: [PATCH 1/2] docs: add create-shape-app as primary quickstart method Rewrite the Builder Kit page to feature `create-shape-app` CLI as the recommended way to scaffold a new Shape project. Updates prerequisites, env vars, commands, and project structure to match the current Builder Kit monorepo layout. Also updates the AI page to reference create-shape-app instead of git clone. --- content/building-on-shape/ai.mdx | 2 +- content/building-on-shape/builder-kit.mdx | 120 ++++++++++++++-------- 2 files changed, 76 insertions(+), 46 deletions(-) diff --git a/content/building-on-shape/ai.mdx b/content/building-on-shape/ai.mdx index d9cffbe..158fd5a 100644 --- a/content/building-on-shape/ai.mdx +++ b/content/building-on-shape/ai.mdx @@ -33,7 +33,7 @@ For full tools and examples, see the [README](https://github.com/shape-network/m ### First Steps -1. **Setup a Next.js App**: `npx create-next-app my-shape-agent`. (Pro tip: If you want a head start, check out our [Builder Kit](https://github.com/shape-network/builder-kit)—it's a Next.js starter for Shape projects with wallet connect, RPC setup, and UI components. Great optional jumping-off point, but not required.) +1. **Setup a Next.js App**: `npx create-next-app my-shape-agent`. (Pro tip: If you want a head start, run `bun create shape-app my-shape-agent` to scaffold a full Shape project with wallet connect, RPC setup, smart contracts, and UI components. See the [Builder Kit](/building-on-shape/builder-kit) docs for details.) 2. **Install SDK**: `npm i ai @vercel/ai-sdk viem wagmi` (for onchain integration) — [more info](https://ai-sdk.dev/docs/introduction). 3. **Connect MCP**: In an API route (e.g., /api/agent.ts): diff --git a/content/building-on-shape/builder-kit.mdx b/content/building-on-shape/builder-kit.mdx index e40fceb..90650f2 100644 --- a/content/building-on-shape/builder-kit.mdx +++ b/content/building-on-shape/builder-kit.mdx @@ -1,69 +1,99 @@ # Shape Builder Kit for Developers -The Shape Builder Kit is your go-to Next.js starter for crafting dApps on Shape ecosystem. Batteries-included with wallet connect, NFT fetching, and more, all pre-wired. +The Shape Builder Kit is your go-to starter for crafting dApps on the Shape ecosystem. It's a monorepo with a Next.js frontend (wagmi, viem) and a Hardhat smart contract package, all pre-wired with sensible defaults. -## Why Use the Builder Kit? - -Starting from scratch can be a pain, the Builder Kit is here to save you from having to search for the right libraries and tools, all with sensible defaults: - -- **Batteries Included**: Comes with wallet connection (wagmi), Shape RPC integration, and NFT fetching out of the box. No reinventing the wheel. -- **AI-Ready**: Pairs seamlessly with the Shape MCP server and Vercel AI SDK for agentic apps. +- **Batteries Included**: Wallet connection, Shape RPC integration, and NFT fetching out of the box. No reinventing the wheel. +- **AI-Ready**: Pairs seamlessly with the [Shape MCP server](/building-on-shape/ai) and Vercel AI SDK for agentic apps. - **Fast Track to Deploy**: Built for Vercel, so you can deploy to prod in minutes and focus on getting your first users! It's completely open and composable: use it to kickstart, then tweak to your style & needs. Check it out: [github.com/shape-network/builder-kit](https://github.com/shape-network/builder-kit). -## How to Install and Get Started +## Quickstart with `create-shape-app` + +The fastest way to get started is [`create-shape-app`](https://github.com/shape-network/create-shape-app), a CLI that scaffolds a new project from the latest Builder Kit release. One command and you're in: + +```bash +bun create shape-app my-app +``` + +Or with other package managers: + +```bash +npx create-shape-app my-app +pnpm dlx create-shape-app my-app +yarn create shape-app my-app +``` + +The CLI will download the latest Builder Kit release, install dependencies, and initialize a git repository. + +### CLI Options + +| Option | Description | +| --- | --- | +| `-y, --yes` | Skip interactive confirmation prompts | +| `--pm ` | Select package manager (auto-detected if omitted) | +| `--skip-install` | Skip dependency installation | +| `--skip-git` | Skip git init and initial commit | +| `--template-ref ` | Pin a specific Builder Kit release tag (e.g. `v1.0.0`) | + +## Project Structure -### Prerequisites +The scaffolded project is a monorepo with two packages: -- Node.js 18+ (check with `node -v`) -- Yarn or npm -- A web3 wallet (e.g., MetaMask) with Shape network added (Chain ID `360` for Shape Mainnet, `11011` for Shape Testnet) -- Optional: Alchemy API key for NFT data +``` +my-app/ +├── apps/web/ # Next.js + wagmi frontend +└── packages/contract/ # Hardhat smart contracts +``` -### Installation +## Configuration -1. **Clone the Repo**: +Copy `.env.example` to `.env` and fill in your values: - ```bash - git clone https://github.com/shape-network/builder-kit.git my-shape-dapp - cd my-shape-dapp - ``` +```env +NEXT_PUBLIC_ALCHEMY_KEY=your-alchemy-key +NEXT_PUBLIC_CHAIN_ID=11011 # 11011 for Shape Sepolia, 360 for Shape Mainnet +NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID= # Optional +DEPLOYER_PRIVATE_KEY= # For contract deployment, must be funded on target network +``` -2. **Install Dependencies**: +Get an Alchemy API key from the [Alchemy Dashboard](https://www.alchemy.com/dashboard). - ```bash - yarn install - ``` +## Development - This pulls in Next.js, wagmi, viem, and other goodies. +```bash +bun dev # Run the web app locally +bun build # Build for production +bun lint # Lint +bun type-check # Type-check +``` -3. **Configure Environment**: +### Smart Contracts - - Create a `.env.local` file: - ```env - NEXT_PUBLIC_ALCHEMY_API_KEY=your-alchemy-key # For NFT metadata - NEXT_PUBLIC_SHAPE_RPC_URL=https://rpc.shape.network # Or your node - CHAIN_ID=360 # Mainnet; use 11011 for Sepolia - ``` +```bash +bun contracts:compile # Compile contracts and regenerate artifacts +bun contracts:test # Run contract tests +bun contracts:deploy:shape-sepolia # Deploy to Shape Sepolia +bun contracts:artifact # Regenerate deployment artifacts for the web app +bun wagmi:generate # Regenerate wagmi typed ABI hooks +``` -4. **Run Locally**: +## What's Included? - ```bash - yarn dev - ``` +- **Wallet Connection**: wagmi for MetaMask (or other wallet providers) integration. Connect with one click. +- **Shape RPC**: Pre-configured with Shape's RPC via Alchemy. Swap to your own node in `.env`. +- **Smart Contracts**: Hardhat setup with a sample `HelloShape` contract, deployment scripts, and typed wagmi hooks generated from your ABIs. +- **UI Components**: Based on [shadcn/ui](https://ui.shadcn.com/) & Tailwind CSS, customize to your heart's content. +- **AI-Ready**: Pairs with the [Shape MCP server](/building-on-shape/ai) and Vercel AI SDK for agentic apps. - Open [http://localhost:3000](http://localhost:3000) in your browser. You'll see the starter app with a connect button. +## Deploy to Vercel -5. **Deploy to Vercel** (Optional): - - Push to GitHub, import to [Vercel](https://vercel.com/new), set env vars in the UI, and deploy. Instant live app! +Push to GitHub, import to [Vercel](https://vercel.com/new), set env vars in the UI, and deploy. Instant live app! -### What's Included? +## Resources -- **Wallet Connection**: Uses wagmi for MetaMask (or other wallet providers) integration. Connect with one click—code in `/components/WalletConnect.tsx`. -- **Fetching Shape NFTs**: Pulls NFTs for the connected address using viem's `getNftsForOwner` (via Alchemy or RPC). Check `/utils/nft.ts` for the fetch logic. -- **Shape RPC Setup**: Pre-configured with Shape's public RPC (`https://rpc.shape.network`). Swap it with your own node in `.env`. -- **UI Components**: All the components you can dream of, based on [Shadcn/ui](https://ui.shadcn.com/) & Tailwind CSS, customize in `/ui` (pro tip: use CSS variables in `global.css` to make your own theme). -- **Extensibility**: Hooks for adding MCP tool calls or Vercel AI agents. See `/api` for API route examples. +- [Builder Kit repository](https://github.com/shape-network/builder-kit) +- [create-shape-app on npm](https://www.npmjs.com/package/create-shape-app) +- [Live demo](https://builder-kit.vercel.app/) -Questions? Hit up [@williamhzo](https://x.com/williamhzo) or Shape Discord. Let's build something epic on Shape! 🚀 +Questions? Hit up [@williamhzo](https://x.com/williamhzo) or [Shape Discord](https://discord.com/invite/shape-l2). Let's build! From 4412f17bcd0b328f7c6b241fbcd7df620bdec0cf Mon Sep 17 00:00:00 2001 From: William H Date: Thu, 12 Feb 2026 09:43:11 +0100 Subject: [PATCH 2/2] docs: promote npx as equal quickstart option --- content/building-on-shape/builder-kit.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/building-on-shape/builder-kit.mdx b/content/building-on-shape/builder-kit.mdx index 90650f2..83e76c7 100644 --- a/content/building-on-shape/builder-kit.mdx +++ b/content/building-on-shape/builder-kit.mdx @@ -13,13 +13,14 @@ It's completely open and composable: use it to kickstart, then tweak to you The fastest way to get started is [`create-shape-app`](https://github.com/shape-network/create-shape-app), a CLI that scaffolds a new project from the latest Builder Kit release. One command and you're in: ```bash +npx create-shape-app my-app +# or bun create shape-app my-app ``` -Or with other package managers: +Also works with pnpm and yarn: ```bash -npx create-shape-app my-app pnpm dlx create-shape-app my-app yarn create shape-app my-app ```