Managing your projects

Clarinet streamlines the entire lifecycle of Clarity smart contract development. From project initialization to contract management and code formatting, you'll have all the tools needed for professional development.

Creating a new project

The clarinet new command creates a complete project structure with all necessary configuration files:

Terminal

$ clarinet new my-defi-app
Create directory my-defi-app
Create directory contracts
Create directory settings
Create directory tests
Create file Clarinet.toml
Create file settings/Mainnet.toml
Create file settings/Testnet.toml
Create file settings/Devnet.toml
Create directory .vscode
Create file .vscode/settings.json
Create file .vscode/tasks.json
Create file .gitignore
Create file .gitattributes
Create file package.json
Create file tsconfig.json
Create file vitest.config.js

Option	Description	Example
`--disable-telemetry`	Opt out of telemetry collection	`clarinet new my-app --disable-telemetry`
`--no-vscode`	Skip VS Code configuration files	`clarinet new my-app --no-vscode`
`--clarity-version`	Set default Clarity version	`clarinet new my-app --clarity-version 3`

For a more in-depth look at the project structure generated, see the project structure guide.

Managing contracts

Creating new contracts

The clarinet contract new command generates both a contract file and its corresponding test file:

Terminal

$ clarinet contract new token
Created file contracts/token.clar
Created file tests/token.test.ts
Updated Clarinet.toml

The generated contract includes a minimal template:

contracts/token.clar

;; token
;; <add a description here>

;; constants
;;

;; data vars
;;

;; data maps
;;

;; public functions
;;

;; read only functions
;;

;; private functions
;;

Removing contracts

Clean up unused contracts with the rm command:

Terminal

$ clarinet contract rm old-token
Removed file contracts/old-token.clar
Removed file tests/old-token.test.ts
Updated Clarinet.toml

Code formatting

Clarinet includes a powerful code formatter to maintain consistent style across your project:

Terminal

$ clarinet format contracts/messy-contract.clar
Formatted contracts/messy-contract.clar

Formatting options

Customize formatting to match your team's style guide:

Option	Description	Example
`--dry-run`	Preview changes without modifying files	`clarinet format --dry-run`
`--in-place`	Replace file contents (required for actual formatting)	`clarinet format --in-place`
`--max-line-length`	Set maximum line length	`clarinet format --max-line-length 100`
`--indent`	Set indentation size	`clarinet format --indent 2`
`--tabs`	Use tabs instead of spaces	`clarinet format --tabs`

Batch formatting

Format all contracts in your project at once:

Terminal

$ clarinet format --all
Formatted 5 contracts

Format specific contracts using glob patterns:

Terminal

$ clarinet format contracts/token*.clar
Formatted contracts/token-trait.clar
Formatted contracts/token-impl.clar

Project configuration

Working with requirements

Add mainnet contracts as dependencies:

Terminal

$ clarinet requirements add SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait
Added requirement SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait
Updated Clarinet.toml

This updates your configuration:

Clarinet.toml

[project]
requirements = [
  { contract_id = "SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait" }
]

Now you can implement traits from mainnet contracts:

contracts/my-nft.clar

(impl-trait 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait.nft-trait)

(define-non-fungible-token my-nft uint)
;; ... implement required functions

Multi-contract projects

Organize larger projects with multiple related contracts:

Clarinet.toml

[contracts.token]
path = "contracts/token.clar"

[contracts.treasury]
path = "contracts/treasury.clar"
depends_on = ["token"]

[contracts.staking]
path = "contracts/staking.clar"
depends_on = ["token", "treasury"]

Clarinet automatically handles deployment order based on dependencies.

Environment settings

Configure different deployment accounts per network:

settings/Testnet.toml

[accounts.deployer]
mnemonic = "${TESTNET_MNEMONIC}"
balance = 1_000_000_000_000

[accounts.treasury]
mnemonic = "${TESTNET_TREASURY_MNEMONIC}"
balance = 500_000_000_000

Security notice

Never commit mainnet private keys or mnemonics to version control. Use environment variables for production deployments.

Checking project configuration

Validate your entire project setup:

Terminal

$ clarinet check --all
✔ 5 contracts checked
✔ No dependency cycles detected
✔ All requirements resolved

Check specific contracts:

Terminal

$ clarinet check contracts/token.clar
✔ Contract 'token' is valid

Next steps

Now that you've mastered project management:

Learn to interact with your contracts using the console
Write comprehensive tests for your contracts
Prepare for deployment to testnet and mainnet