Installation Guide

Complete setup guide for Trustless Work React blocks with detailed configuration and best practices.

Install Trustless Work Blocks

Install the main library package:

1npm install @trustless-work/blocks

Run the CLI Setup

Initialize your project with the Trustless Work CLI:

1npx trustless-work init

What the init command does:

Installs shadcn/ui components (with interactive prompts)
Installs required dependencies: @tanstack/react-query, @trustless-work/escrow, axios, zod, react-hook-form, @creit.tech/stellar-wallets-kit, react-day-picker, etc.
Creates .twblocks.json configuration file
Optionally wires providers into your Next.js app/layout.tsx

Environment Configuration

Create a .env file in your project root:

.env

1# Required: Your Trustless Work API key 
2NEXT_PUBLIC_API_KEY=your_api_key_here

Configuration Files (Optional)

.twblocks.json

The CLI creates a configuration file to manage UI component paths:

.twblocks.json

1{
2  "uiBase": "@/components/ui"
3}

Custom UI Base Path

If your UI components are in a different location, specify the path when adding blocks:

1npx trustless-work add escrows/escrows-by-role/cards --ui-base "@/lib/ui"

Wrap your App with Providers

If you want to use some blocks, you should wrap your app with their providers. See more in: Dependencies

Absolutely must be used: ReactQueryClientProvider | TrustlessWorkProvider | WalletProvider.

Add Your First Component

Add wallet connectivity to your app:

1npx trustless-work add wallet-kit

Example usage in a page:

app/home/page.tsx

1import { WalletButton } from "@/components/tw-blocks/wallet-kit/WalletButtons";
2
3export default function HomePage() {
4  return (
5    <div className="container mx-auto py-8">
6      <div className="flex justify-between items-center mb-8">
7        <h1 className="text-3xl font-bold">My Escrows</h1>
8        <WalletButton />
9      </div>
10    </div>
11  );
12}

Now, you are able to interact with the wallet.

Common Issues

API Key

Ensure your NEXT_PUBLIC_API_KEY is set in your environment variables.

Provider Order

Make sure providers are nested in the correct order: ReactQueryClientProvider → TrustlessWorkProvider → WalletProvider → EscrowProvider.

Component Imports

If you have import issues, check your .twblocks.json configuration and ensure the uiBase path is correct.

Missing Dependencies

If you are using some blocks, you'll need to check the dependencies section of the block you are using. For example, if you are trying to use the escrows-by-role/table block, you'll need to add the escrow-context, wallet-kit, escrows, handle-errors and helpers block to your project.

Server Side Error

When you are using some blocks, you might get a server side error, so you should write "use client" on the top of your component. (Most usually happens with form blocks)

@trustless-work/blocks not installed

Before you add a block, you should install the @trustless-work/blocks package with npm install @trustless-work/blocks.

@trustless-work/blocks not initialized

Before you add a block, you should initialize the @trustless-work/blocks package with npx trustless-work init.

Still have issues? Contact support

Introduction

Start from Scratch