Skip to main content

Quick Start (5min)

We recommend using offCKB to quickly set up a local development environment using our pre-built boilerplates. This streamlined approach allows you to jumpstart your project efficiently without the hassle of manual configuration.

Install OffCKB​

OffCKB provides a one-line command to start a local blockchain (CKB Devnet) with pre-funded test accounts and built-in Scripts

A Script in Nervos CKB is a binary executable on the CKB-VM.
like Omnilock and Spore-contract.

npm install -g @offckb/cli
info

Throughout this documentation, we use offckb/cli version >=0.2.5. You can always run the above command to update to the latest version.

Create a New Project​

To setup a boilerplate for a full-stacked dApp, run the following command. Replace <my-dapp-project> with any name you like.

offckb create <my-dapp-project>

When prompted to select a bare template, use your arrow keys to select the frontend framework you prefer. If you wish to use a frontend framework not listed, please refer to this section.

? Select a bare template
  Remix-Vite Bare Templates
> Next.js Bare Templates
---
A full-stack template with Next.js framework and ckb-script-templates,
[next.js,tailwindcss,ckb-script-templates,typescript,rust]
How to create a Script-only project?

To create a project focused solely on Script development without any frontend work, you can run the following command. Replace <my-script-project> with any name you like.

offckb create --script <my-script-project>

Note that offckb essentially utilizes an underlying tool called ckb-script-templates to initialize Script projects. You can directly engage ckb-script-templates for more specific Script development tasks. For further details, refer to the Script tutorial.

Start the Devnet​

offckb node

Your local CKB blockchain is currently active with the RPC endpoint at localhost:8114. To stop the chain, press CTRL+C in the terminal. To resume where you left off, simply run offckb node again.

If you need to start fresh with a new chain, run the following command before starting the node:

offckb clean

Run the DApp Project​

The dApp is based on various JavaScript web frontend frameworks, such as Remix-Vite and Next.js, and is integrated with the CKB JavaScript framework, Lumos. All Lumos-related code is defined in the frontend/offckb.config.ts file.

To start development, navigate to the frontend workspace:

cd frontend

Now, run the following command to install dependencies and start the dApp:

npm i && npm run dev

Once the server is up and running, you can view the dApp by visiting localhost:3000. You can start editing the page by modifying app/page.tsx. As you make changes to the file, the page will automatically update to reflect your edits. For detailed instructions on how to start the dApp and explore additional config options, please see the README.md file.

dapp-screenshot

DApp Project Structure​

The boilerplate project for a full-stack CKB dApp comprises two main components:

By default, the Next.js template comes with a simple Script hello-world under contracts/hello-world/src/main.rs.

Tools You Need

  • git, make, sed, bash, sha256sum and others Unix utilities.

  • Rust with riscv64 target: rustup target add riscv64imac-unknown-none-elf

  • Clang 16+

    • Debian / Ubuntu: wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo./llvm.sh 16 && rm llvm.sh
    • Fedora 39+: sudo dnf -y install clang
    • Archlinux: sudo pacman --noconfirm -Syu clang
    • MacOS (with Homebrew): brew install llvm@16
    • Windows (with Scoop): scoop install llvm yasm

  • Cargo-generate

Check out the ckb-script-templates for more details.

  • Add a new Script: make generate
  • Build Script: make build
  • Run unit tests: make test

Deploy Scripts to Blockchain​

After building your Scripts, you can navigate to your frontend workspace and deploy your Scripts to the Devnet or Testnet by using the following command:

offckb deploy --network devnet

Use Scripts in Frontend​

If the deployment is successful, the offckb.config.ts file will contain the necessary details to import and utilize your Scripts in your frontend dApp. Here's how you can use your Scripts directly:

import offckb from "offckb.config";
import { CellDep } from "@ckb-lumos/lumos";

const lumosConfig = offckb.lumosConfig;
const myContractDep: CellDep = {
  outPoint: {
    txHash: lumosConfig.SCRIPTS.YOUR_SCRIPT_NAME!.TX_HASH,
    index: lumosConfig.SCRIPTS.YOUR_SCRIPT_NAME!.INDEX,
  },
  depType: lumosConfig.SCRIPTS.YOUR_SCRIPT_NAME!.DEP_TYPE,
};

Use a Different Frontend Framework?​

The frontend world is filled with numerous (perhaps too many) frameworks. New frameworks come out every day, and different developers have different preferences among these frameworks. So if you don't use the framework in the pre-defined boilerplate, like remix-vite and next.js, don't worry! You can still use offckb with the inject-config command.

First, simply initialize your dApp project with your preferred framework, such as CRA:

npx create-react-app my-cra-dapp --template typescript

Next, navigate to your dApp directory and initialize the offckb config within your framework:

cd my-cra-dapp
offckb inject-config

Now, when you deploy your Scripts with offckb deploy --network devnet --target <your-folder-to-your-script-binaries>, run the following command in your frontend root path where the offckb.config.ts file is located to update the deployed Scripts info for your frontend.

offckb sync-config

For switching between different networks, you might need to update the readEnvNetwork method in offckb.config.ts according to your framework.

function readEnvNetwork(): "devnet" | "testnet" | "mainnet" {
  // you may need to update the env method
  // according to your frontend framework
  const network = process.env.NETWORK;
  const defaultNetwork = "devnet";
  if (!network) return defaultNetwork;
  if (!["devnet", "testnet", "mainnet"].includes(network)) {
    return defaultNetwork;
  }

  return network as "devnet" | "testnet" | "mainnet";
}

About offckb.config.ts​

offckb.config.ts is a straightforward TypeScript file that encapsulates basic info and configs for Lumos. Everything is explicitly defined, making it easy to modify. This minimalistic approach ensures that offckb does not impose limitations on the tech selections and development processes of developers.

If you have any feedback you would like to share with us, feel free to contact us at github or discord.