Stacks.js

Overview

Stacks.js is a collection of JavaScript/TypeScript libraries that enable developers to build decentralized applications on the Stacks blockchain. Whether you're building a web app that connects to users' wallets or creating command-line tools for contract deployment, Stacks.js provides all the building blocks you need.

The ecosystem includes both the core stacks.js packages for transaction building and utilities, as well as @stacks/connect for seamless web wallet integrations.

Key features

• ✓ Web wallet integration - Connect to Hiro Wallet, Xverse, and other wallets with a unified API
• ✓ Transaction building - Construct any type of Stacks transaction with type-safe builders
• ✓ Smart contract calls - Call read-only functions and execute contract methods
• ✓ Post-conditions - Implement security checks to ensure transactions behave as expected

Installation

Install the packages you need for your use case:

$ 
npm install @stacks/connect @stacks/transactions @stacks/networkCopy

Quick example

Here's a simple example of connecting a wallet and sending STX:

import { showConnect } from '@stacks/connect';
import { StacksMainnet } from '@stacks/network';
import { AnchorMode, makeSTXTokenTransfer } from '@stacks/transactions';

// Connect wallet
showConnect({
  appDetails: {
    name: 'My App',
    icon: 'https://example.com/icon.png',
  },
  onFinish: () => {
    console.log('Wallet connected!');
  },
  userSession, // Your app's user session
});

// Send STX (user approves in wallet)
const tx = await makeSTXTokenTransfer({
  recipient: 'SP2J6Y09JMFWWZCT4VJX0BA5W7A9HZP5EX96Y6VZY',
  amount: 1000000, // 1 STX in microSTX
  anchorMode: AnchorMode.Any,
});

showConnect({
  transaction: tx,
  network: new StacksMainnet(),
  onFinish: (data) => {
    console.log('Transaction sent:', data.txId);
  },
});

Architecture overview

Core concepts

Wallet-based vs local key management

Stacks.js supports two primary modes of operation:

Wallet-based (Web Apps)

• Users control their private keys through wallet software
• Transactions require user approval in their wallet
• Best for user-facing applications
• Use @stacks/connect for wallet interactions

Local key management (Scripts/CLI)

• Your application manages private keys directly
• Transactions are signed programmatically
• Best for backend services and development tools
• Use @stacks/transactions with private keys

Understanding post-conditions

Post-conditions are a unique Stacks feature that add an extra layer of security to transactions. They ensure that a transaction will only succeed if certain conditions are met after execution.

// Ensure exactly 1 STX is transferred
const postConditions = [
  makeStandardSTXPostCondition(
    senderAddress,
    FungibleConditionCode.Equal,
    1000000 // 1 STX
  ),
];

Next steps