🚀 The ultimate TypeScript template for building CKB app from smart contracts to user interface. Powered by offckb, ckb-js-vm and CCC.

An all-in-one boilerplate for developing smart contracts app on the CKB blockchain using TypeScript. Write, test, deploy and interact with contracts using familiar JavaScript tooling.

CKB is unique - it allows smart contracts in any language that compiles to RISC-V. The ckb-js-vm is a JavaScript runtime (based on QuickJS) compiled to RISC-V, enabling you to write contracts in TypeScript instead of low-level languages.

• 📝 TypeScript Support - Full type checking and IDE support
• 🧪 Built-in Testing - Full test flow from Jest + ckb-testtool for mock testing to CCC + offckb for local node and testnet testing
• 🚀 One-Command Deploy - Deploy to devnet, testnet, or mainnet
• 🔄 Upgradable Contracts - Type ID pattern support for contract updates
• 🌐 Next.js Frontend - Ready-to-use dApp with CCC wallet integration
• 🤖 AI-Friendly - Documentation optimized for LLM assistants

# Clone the template
git clone https://github.com/cryptape/ckb-script-app my-ckb-project
cd my-ckb-project

# Install dependencies
pnpm install

# Build contracts
pnpm run build

# Run tests
pnpm test

# Start frontend (optional)
cd app && pnpm dev

ckb-script-app/
├── contracts/              # 📜 Smart contract source code
│   └── hello-world/
│       └── src/
│           └── index.ts    # Contract entry point
├── tests/                  # 🧪 Contract tests
│   ├── *.mock.test.ts      # Mock tests (no node required)
│   └── *.devnet.test.ts    # Integration tests
├── dist/                   # 📦 Compiled output
│   └── *.bc                # Bytecode for CKB
├── deployment/             # 🚀 Deployment artifacts
│   └── scripts.json        # Deployed contract info
├── app/                    # 🌐 Next.js frontend
│   ├── components/         # React components
│   └── utils/              # CKB utilities
├── .skills/                # 🤖 AI skill patterns
│   ├── ckb-contract-patterns/  # Contract patterns
│   └── ckb-ccc-frontend/       # Frontend patterns
├── scripts/                # 🔧 Build tooling
├── CLAUDE.md               # 🤖 AI assistant guide
├── AGENTS.md               # 🤖 AI assistant guide

import * as bindings from '@ckb-js-std/bindings';
import { log } from '@ckb-js-std/core';

function main(): number {
  log.setLevel(log.LogLevel.Debug);
  
  // Load current script info
  const script = bindings.loadScript();
  log.debug(`Script: ${JSON.stringify(script)}`);
  
  // Your validation logic here
  // Return 0 for success, non-zero for failure
  
  return 0;
}

bindings.exit(main());

pnpm run add-contract my-token

This creates:

• contracts/my-token/src/index.ts - Contract code
• tests/my-token.mock.test.ts - Mock test file

bindings.SOURCE_INPUT          // Input cells
bindings.SOURCE_OUTPUT         // Output cells
bindings.SOURCE_GROUP_INPUT    // Same-script input cells
bindings.SOURCE_GROUP_OUTPUT   // Same-script output cells

Test without running a CKB node:

import { Resource, Verifier } from 'ckb-testtool';

describe('my-contract', () => {
  test('should validate correctly', async () => {
    const resource = Resource.default();
    const tx = Transaction.default();
    
    // Setup transaction cells...
    
    const verifier = Verifier.from(resource, tx);
    await verifier.verifySuccess(true);
  });
});

pnpm test                    # Run all tests
pnpm test -- my-contract     # Run specific contract tests

For integration testing with a real node:

offckb node                  # Start local devnet
pnpm test -- devnet          # Run devnet tests

# Deploy to local devnet (default)
pnpm run deploy

# Deploy to testnet
pnpm run deploy -- --network testnet

# Deploy to mainnet
pnpm run deploy -- --network mainnet

# Deploy with upgradable Type ID
pnpm run deploy -- --network testnet --type-id

# Deploy with custom key
pnpm run deploy -- --network testnet --privkey 0x...

After deployment, deployment/scripts.json contains your contract info:

{
  "devnet": {
    "hello-world.bc": {
      "codeHash": "0x...",
      "hashType": "type",
      "cellDeps": [...]
    }
  }
}

The app/ directory contains a Next.js app with CCC wallet integration.

import scripts from "@/deployment/scripts.json";
import systemScripts from "@/deployment/system-scripts.json";

// Build script for ckb-js-vm contract
const myScript = {
  codeHash: systemScripts.devnet["ckb_js_vm"].script.codeHash,
  hashType: systemScripts.devnet["ckb_js_vm"].script.hashType,
  args: buildScriptArgs(scripts.devnet["hello-world.bc"]),
};

cd app
pnpm install
pnpm dev

Open http://localhost:3000

This template includes documentation for AI coding assistants:

The .skills/ folder contains detailed patterns:

When using AI assistants, share the repo URL and they'll understand the project structure.

• The Little Book of ckb-js-vm - Comprehensive guide
• CKB JS Quick Start - Official docs
• CCC Documentation - Wallet connector
• CKB RFCs - Protocol specs
• ckb-js-vm GitHub - VM source

• Node.js v20 or later
• pnpm package manager
• offckb (optional, for local devnet): npm install -g @offckb/cli

MIT

Built with ❤️ for the CKB ecosystem