Creating a Clarinet project

Ready to build your first smart contract? Clarinet makes it simple to generate a new project, write Clarity code, and test everything locally. You'll have a working counter contract up and running in minutes.

Think of Clarinet as your smart contract workshop. It gives you project structure, testing tools, and a local blockchain—everything you need to build confidently before deploying to mainnet.

What You'll Learn

Generate a new Clarinet project
Create your first smart contract
Write basic Clarity functions
Validate your contract code
Test contract interactions locally

What You'll Need

Clarinet installed
Basic terminal knowledge
10 minutes for the walkthrough

Step 1: Generate Your Project

Create a new Clarinet project called counter. This sets up everything you need for smart contract development.

Terminal

$ clarinet new counter
Creating directory counter
Created file counter/Clarinet.toml
Created file counter/.gitignore
Created directory counter/contracts
Created directory counter/tests
Created file counter/settings/Devnet.toml
Created file counter/settings/Mainnet.toml  
Created file counter/settings/Testnet.toml
Created file counter/package.json
Created file counter/tsconfig.json
Created file counter/vitest.config.js

Navigate into your new project:

Terminal

$ cd counter

You now have a complete Clarinet workspace with:

contracts/: Where your Clarity files live
tests/: JavaScript test files
settings/: Network configurations
Clarinet.toml: Project configuration

Step 2: Create Your First Contract

Generate a new smart contract called counter inside your project:

Terminal

$ clarinet contract new counter
Created contracts/counter.clar

This command:

Creates the contract file contracts/counter.clar
Updates Clarinet.toml with contract configuration
Sets up the proper folder structure

Your Clarinet.toml now includes:

[contracts.counter]
path = 'contracts/counter.clar'
clarity_version = 2
epoch = 2.5

Step 3: Write Your Smart Contract

Open contracts/counter.clar and add this code:

;; Define a map to store counters for each user
(define-map Counters principal uint)

;; Public function to increment a user's counter
(define-public (count-up)
  (ok (map-set Counters tx-sender (+ (get-count tx-sender) u1)))
)

;; Read-only function to get a user's current count
(define-read-only (get-count (who principal))
  (default-to u0 (map-get? Counters who))
)

What this contract does:

Counters map: Stores a number for each user (principal)
count-up function: Increases the caller's count by 1
get-count function: Returns anyone's current count

Each user gets their own counter that starts at 0 and increments when they call count-up.

Step 4: Validate Your Contract

Check your contract for syntax errors and issues:

Terminal

$ clarinet check
✅ 1 contract checked, no problems found.

See the checkmark? Your contract is valid! If you see errors:

Check for typos in function names
Make sure parentheses are balanced
Verify correct Clarity syntax

Common fixes:

Missing or extra parentheses
Incorrect function signatures
Typos in built-in functions

Step 5: Test Your Contract Locally

Start the Clarinet console to interact with your contract:

Terminal

$ clarinet console
Welcome to Clarinet console.
Type (help) for available commands.
>>

Test the count-up function:

>> (contract-call? .counter count-up)
(ok true)

Check your count:

>> (contract-call? .counter get-count tx-sender)
u1

Increment again:

>> (contract-call? .counter count-up)
(ok true)

>> (contract-call? .counter get-count tx-sender)
u2

Perfect! Your counter is working. Each call to count-up increases your count by 1.

Hit Ctrl+C twice to leave the console.

Project Structure: Your Clarinet project includes contracts for your Clarity code, tests for JavaScript unit tests, settings for network configurations, and Clarinet.toml for project configuration. For a complete breakdown of each file and configuration options, see our Anatomy of a Clarinet Project guide.

Verification

Let's confirm everything is working:

1Project created: ls shows all the project files
2Contract valid: clarinet check passes with no errors
3Contract interactive: Console commands return expected results
4Functions work: Counter increments correctly

If any step fails, double-check the contract code and try clarinet check again.

Troubleshooting

"Command not found: clarinet"

Make sure Clarinet is installed
Restart your terminal after installation

"Contract validation failed"

Check for syntax errors in your .clar file
Ensure parentheses are balanced
Look for typos in function names

"Console not responding"

Exit with Ctrl+C and try clarinet console again
Make sure you're in your project directory

"Contract call failed"

Verify the contract name matches your file (.counter)
Check function names for typos
Ensure you're using correct Clarity syntax

Next Steps

Excellent work! You've created your first smart contract project. Here's what to tackle next:

Write comprehensive tests: Learn unit testing with Clarinet JS SDK to ensure your contracts work perfectly.

Explore advanced patterns: Check out Advanced Clarity Patterns to write more sophisticated contracts.

Run a local blockchain: Set up Devnet for local development to test with multiple accounts and realistic scenarios.

Pro tip: Keep your contracts simple at first. Master the basics like maps, public functions, and read-only functions before moving to complex features like traits and inter-contract calls.