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

Intro

I am a software developer at Whitelabel Co and a current Resident with the Stacks Foundation to deliver and scale developer education around the Clarity smart contract language and building on Stacks. I became involved in the Stacks community late Spring of 2021 under a pseudonym and have since been involved with multiple projects throughout the ecosystem as a web developer and advisor. Since starting the residency, one of the most common pieces of feedback I've received from new developers to Stacks is a desire for more comprehensive walkthroughs of the full-stack development process.

I won't get into the Stacks blockchain itself as part of this series, but if you are not familiar with the network check out this intro.

We'll 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 stacks.co 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 tutorial we will be using DevNet.

Prerequisites

In order to run DevNet there are a few things you'll need to have installed. 👇

Clarinet

You'll need to install Clarinet. The detailed instructions can be found in the Hiro docs.

Quickstart:

• macOS

brew install clarinet

• windows

winget install clarinet

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

clarinet --version

Docker

You'll also need Docker on your machine for running DevNet. Instructions can be found in the Docker docs.

Project structure

From the terminal, make sure you are in your desired starting directory and run:

mkdir gm

This will create a main directory for our project which will hold our 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

As you can see, running the clarinet new command will generate a number of files and directories. Let's briefly look at the main ones.

• Clarinet.toml: This is your configuration file. Within this file you'll notice [contracts.gm] path = "contracts/gm.clar", any contract dependencies whether from contracts you create or import from those deployed on mainnet will show up here.

• /settings/Devnet.toml: This file contains dummy data which you can use for testing your contract. It provides you with a deployer and a number of wallets. We will be interacting closely with this file throughout this example.

• /contracts and /tests: These directories are initialized but remain empty until you create your first contract. We'll come back to these after the next step.
  

cd backend

and create your contract with:

clarinet contract new gm

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

• contracts/gm.clar: This is where the Clarity code goes.

• tests/gm_test.ts: This is where the Typescript unit tests that correspond to each contract go.

Great! Your 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