Skip to content

Project Setup

StxScript provides scaffolding tools to create new projects with best-practice structure and configuration.

Creating a Project

Use stxscript new to scaffold a new project:

stxscript new my-project

Project Templates

Four templates are available:

Template Description Use Case
basic Simple counter contract Learning, general contracts
token SIP-010 fungible token Fungible token contracts
nft SIP-009 NFT Non-fungible token contracts
defi AMM/DeFi protocol Decentralized finance 
stxscript new my-token --template token
stxscript new my-nft --template nft
stxscript new my-amm --template defi

Custom Directory

Specify where to create the project:

stxscript new my-project --path /path/to/projects/

Project Structure

A scaffolded project follows this layout:

my-project/
├── src/
│   └── main.stx           # Main contract source
├── tests/
│   └── test_main.py       # Contract tests
├── build/                  # Compiled Clarity output
├── stxscript.toml          # Package manifest
└── README.md               # Project documentation

src/

Contains your .stx source files. You can organize into subdirectories:

src/
├── main.stx                # Entry point contract
├── traits/
│   └── sip-010.stx         # Trait definitions
└── lib/
    └── math.stx            # Utility contracts

build/

Output directory for compiled .clar files. Generated by stxscript build:

stxscript build src/ build/

tests/

Contract test files using the StxScript testing framework:

stxscript test tests/

Package Manifest

stxscript.toml defines project metadata and dependencies:

[package]
name = "my-project"
version = "0.1.0"
description = "A StxScript smart contract project"
authors = ["Your Name <[email protected]>"]
license = "MIT"

[dependencies]
# package-name = "^1.0.0"

[dev-dependencies]
# test-utils = "^0.1.0"

Fields

Field Description
name Package identifier
version Semantic version (major.minor.patch)
description Short project description
authors List of author strings
license License identifier

Dependencies

Add dependencies with the CLI:

stxscript pkg add some-library --version "^1.0.0"
stxscript pkg add test-helpers --dev

Or edit stxscript.toml directly:

[dependencies]
token-utils = "^1.0.0"
math-lib = "^0.5.0"

[dev-dependencies]
test-helpers = "^0.2.0"

Install all dependencies:

stxscript pkg install

Development Workflow

1. Create the project

stxscript new my-token --template token
cd my-token

2. Edit your contract

Edit src/main.stx with your contract logic.

3. Watch mode

Auto-rebuild on file changes during development:

stxscript watch src/ --output build/

4. Quality checks

stxscript fmt src/         # Format code
stxscript lint src/        # Check for issues
stxscript check src/       # Validate syntax

5. Test

stxscript test tests/

6. Build for deployment

stxscript build src/ build/

Template Contents

Basic Template

A simple counter contract demonstrating variables, constants, and functions:

const MAX_COUNT: uint = 1000u;
let counter: uint = 0u;

@public
function increment(): Response<uint, uint> {
    if (counter >= MAX_COUNT) {
        return err(1u);
    }
    counter = counter + 1u;
    return ok(counter);
}

@readonly
function get_counter(): uint {
    return counter;
}

Token Template

A SIP-010 compliant fungible token with transfer, mint, and balance tracking.

NFT Template

A SIP-009 compliant NFT with minting, transfers, and metadata URIs.

DeFi Template

An AMM (Automated Market Maker) with liquidity pools, swaps, and fee calculations.

Next Steps