Building Clarity apps with Clarigen

Want to start building Stacks web apps using Clarigen? Here's how you can get up and running quickly:

Install Clarigen and setup your project

Follow the getting started guide for installation instructions and project setup.

Configure Clarigen to export a TypeScript file

In your Clarigen.toml file, set types.output:

Clarigen.toml

[types]
output = "src/clarigen.ts"

Refer to the configuration docs for more info.

Generate the TypeScript file

In your CLI, run:

clarigen

You should now have a Clarigen types file generated at src/clarigen.ts, or wherever you configured types.output.

Setup your `ClarigenClient`

src/clarigen-client.ts

import { ClarigenClient } from '@clarigen/core';
 
const stacksApiUrl = 'https://stacks-node-api.mainnet.stacks.co';
 
export const clarigen = new ClarigenClient(stacksApiUrl);

Create contract factories

Contract factories are ways to "connect" a contract definition with a contract identifier. These factories are designed to make it easy to work with your contracts on different environments.

Learn more about contract factories

src/clarigen-contracts.ts

// import from auto-generated types
import { contracts } from './clarigen';
import { contractFactory } from '@clarigen/core';
 
const nftContractId = 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.nft';
export const nftContract = contractFactory(contracts.nft, nftContractId);

Call read-only functions

When calling read-only functions using Clarigen, all responses are automatically converted to JS-native types from their associated Clarity values. In addition, the responses are correctly typed when using TypeScript.

Learn more about calling read-only functions

// import the client you just made
import { clarigen } from './clarigen-client';
// import your contract
import { nftContract } from './clarigen-contracts';
 
export async function getOwner(id: number | bigint) {
  // `response` is type:
  // `{ isOk: true; value: string } | { isOk: false, value: bigint }`
  const response = await clarigen.ro(nftContract.getOwner(id));
  if (response.isOk) {
    // `response.value` is a string
    return response.value;
  }
  // `response.value` is a bigint
  throw new Error(`Unexpected error: ${response.value}`);
}

Making contract call transactions

When making contract call transactions, you can almost always use the "spread" syntax to pass contract call parameters to whatever library you're using.

Learn more about signing transactions

Here's an example using React:

import { useOpenContractCall } from '@micro-stacks/react';
import { nftContract } from './clarigen-contracts';
 
export const TransferTx = () => {
  const { openContractCall } = useOpenContractCall();
  const id = 1;
  const sender = 'SP...';
  const recipient = 'SP...';
 
  const handleOpenContractCall = async () => {
    await openContractCall({
      ...nftContract.transfer({
        id,
        sender,
        recipient,
      }),
      onFinish: async data => {
        console.log('Finished!', data);
      },
    });
  };
 
  return <button onClick={() => handleOpenContractCall()}>Transfer</button>;
};