Arkiv TypeScript Starter

Purpose-built starter for the Arkiv TypeScript SDK with:

• Scaffolder CLI (create-arkiv-app) for bootstrapping Arkiv-ready projects
• Multiple templates for different use cases (CLI, REST API, React, local development)

TL;DR – Scaffold a project

npx @arkiv-network/create-app@latest --template crud
# or locally: npm run dev   # runs src/create-arkiv-app.ts
# follow prompts: project name, template, network, private key (generate or paste)
cd <your-project>
npm install
npm run dev  # or template-specific script

Templates Available

Templates available (--template <name>):

• crud — Minimal CLI application demonstrating CRUD operations

  • Create, read, update, delete, and query entities
  • Connects to Arkiv testnets (Mendoza, Rosario, Kaolin)
  • Perfect for learning the basics

• crud-rest-api — Express.js REST API server

  • HTTP endpoints for entity operations (POST /entities, GET /entities, GET /entities/search, DELETE /entities/:key)
  • CORS enabled for frontend integration
  • Ideal for building backend services

• crud-react-metamask — React application with MetaMask integration

  • Web interface for CRUD operations
  • Wallet connection via MetaMask
  • No private keys needed (MetaMask handles signing)
  • Built with Vite

• crud-local-dev — Local development with Testcontainers

  • Runs a local Arkiv node in Docker
  • Automatically generates and funds test accounts
  • No testnet connection required
  • Perfect for development and testing

Each template includes:

• Complete working code examples
• TypeScript configuration
• README with setup instructions
• .env file automatically generated by the CLI
• AGENTS.md with AI assistant instructions

Quick Start

1. Create a new project:

   npx @arkiv-network/create-app@latest

2. Choose a template when prompted (or use --template <name>)

3. Select a network:

   • mendoza — Mendoza testnet (default)
   • rosario — Rosario testnet
   • kaolin — Kaolin testnet
   • localhost — Local development (for crud-local-dev template)

4. Configure your account:

   • Generate a new private key (recommended for testing)
   • Or provide your own private key

5. Fund your account (for testnets):

   • The CLI will show your account address and faucet URL
   • Visit the faucet to get testnet funds

6. Run your project:

   cd <your-project>
   npm install
   npm run dev

Project Layout

templates/
├── crud/              # Basic CLI CRUD operations
├── crud-rest-api/     # Express REST API server
├── crud-react-metamask/ # React + MetaMask app
└── crud-local-dev/    # Local development with Testcontainers

bin/
└── create-arkiv-app.js  # Compiled CLI generator

src/
└── create-arkiv-app.ts # Source code for CLI

tests/
└── smoke.test.ts       # Smoke tests for templates

Common Tasks (this repo)

• Scaffold locally: npm run dev (runs the CLI in development mode)
• Type-check: npm run lint
• Run tests: npm test (smoke tests for all templates)
• Build: npm run build (compiles TypeScript to JavaScript)
• Package: npm run package (creates .tgz for publishing)

Client Setup in Generated Projects

Typical client setup in generated projects:

import { createWalletClient, createPublicClient, http, chainFromName } from "@arkiv-network/sdk"
import { privateKeyToAccount } from "@arkiv-network/sdk/accounts"

const chain = chainFromName(process.env.ARKIV_NETWORK || "mendoza")
const account = privateKeyToAccount(process.env.ARKIV_PRIVATE_KEY as `0x${string}`)

const walletClient = createWalletClient({
  chain,
  account,
  transport: http(),
})

const publicClient = createPublicClient({
  chain,
  transport: http(),
})

Important:

• Keep secrets in .env (automatically generated, not committed to git)
• Fund accounts via faucet for testnets
• For local development, use the crud-local-dev template

Environment Variables

The CLI automatically generates a .env file with:

• ARKIV_NETWORK — Network name (mendoza, rosario, kaolin, or localhost)
• ARKIV_PRIVATE_KEY — EVM private key (0x-prefixed)

For React projects (Vite), the network variable uses the VITE_ prefix:

• VITE_ARKIV_NETWORK — Network name

Learn More

• SDK Documentation: https://github.com/Arkiv-Network/arkiv-sdk-js/blob/main/docs/index.md
• Template READMEs: Each template includes detailed setup and usage instructions
• AGENTS.md: Comprehensive guide for AI coding assistants working with Arkiv

Notes

• Security: The CLI generates projects locally - you control the code and dependencies
• Networks: Supports Mendoza, Rosario, and Kaolin testnets, plus local development
• Faucets: Testnet faucets are network-specific (e.g., https://mendoza.hoodi.arkiv.network/faucet/)
• Publishing: This package is published as @arkiv-network/create-app on npm