Back to Blog

Developing a Full-Stack Project on the Stacks Blockchain with Clarity Smart Contracts and Stacks.js Part I: Intro and Project Setup


The tech industry is a constantly changing environment. With the emergence of blockchain technology, and more recently web3, or decentralized, applications those changes appear to be happening at a more rapid pace. At Whitelabel, we have expanded our services to include smart contract development for multiple chains. I have personally taken an interest in the Stacks Blockchain, a layer 1 chain that aims to bring programmability to Bitcoin by implementing a consensus mechanism named Proof of Transfer(PoX) that allows for visibility into the Bitcoin state and uses the Bitcoin chain as a settlement layer.

In this post, I will walk through the fundamental steps of creating a front to back application on Stacks. I will demonstrate a simple smart contract in Clarity, the language used to write smart contracts on Stacks, go over unit testing, practice manual contract calls in clarinet console using Clarinet, a CLI package and developer environment for creating smart contracts, build a frontend using Stacks.js Starters to quickly bootstrap a frontend app, hook up the contract to the client, and run a local DevNet instance to demonstrate the application in action as if it was on-chain.

Mainnet vs Testnet vs DevNet

It’s important to understand the difference between the various “nets” and when you would interact with each one. For Stacks there are three “nets”, they are all separate chains and each hold their own data.

Mainnet is the main Stacks blockchain network. This is fully public and where users interact with deployed smart contracts. In web2 development lingo, you can think of an app on mainnet as in production, prior to which it will be in staging on testnet. The Stacks explorer is a browser based tool that allows users to access information on Stacks mainnet. Here you can see things like recent blocks, pending and confirmed transactions, as well as the deployed smart contracts themselves.

Testnet is a separate blockchain from the Stacks mainnet that can be thought of as a sort of staging environment. It is used by developers to test their apps and smart contracts and allows users to interact with the application using test STX tokens rather than their actual tokens. The Stacks explorer allows users to switch to testnet view by clicking Network on the top right of the page and selecting testnet. There is also a testnet Sandbox available for writing and deploying, making contract calls, and receiving test STX via the STX faucet.

DevNet is an integration feature provided by our friends at Hiro that allows us to spin up a simulated blockchain locally. This allows developers to perform frontend integration and testing without having to deploy to a public tesnet. DevNet is useful when you are in the early stages of development or buidling incognito.

In this example I will be using DevNet.


In order to run DevNet there are a few things that need to be installed.


The detailed instructions can be found in the Hiro docs.


brew install clarinet
winget install clarinet

You can verify whether it has successfully installed by running the following command:

clarinet --version


Docker is required to be on your machine for running DevNet. Instructions can be found in the Docker docs.

Project structure

From the terminal, in the desired starting directory run:

mkdir gm

This will create a main directory for the project which will hold the frontend and backend folders. Move into this directory with:

cd gm

Initialize the frontend directory with:

npm create stacks --template frontend

This will spin up a Next app called “frontend” with Stacks.js scaffolding which makes getting started a breeze. Writing the frontend code will be the final step in this example, so we will come back to that directory later.

Now to initialize the backend directory; for readability in separating the contracts from the client, I’ll call this clarinet project “backend”:

clarinet new backend
Screenshot of terminal depicting directories and files created after using the Clarinet new command. This should include twelve elements, the most important of which are described in the paragraph below the screenshot.

As you can see, running the clarinet new command will generate a number of files and directories. I’ll briefly describe the main ones.

cd backend

and create a contract with:

clarinet contract new gm
Screenshot of terminal depicting files created after using the Clarinet contract new command. This should include two files described in the paragraph below the screenshot.

Now, the /contracts and /tests directories have files.

With that the Clarity smart contract project is set up.
From here you can write your code inside of gm.clar and write unit tests inside of gm_test.ts


Thanks for reading Part I of this series! Move on to Part II: Backend.

We have more blog posts if you're interested.
How can a Subdomain Boost my Business?
Interact with Stacks blockchain on Testnet
Developing a Full-Stack Project on the Stacks Blockchain with Clarity Smart Contracts and Stacks.js Part III: Frontend