Developing a Full-Stack Project on Stacks with Clarity Smart Contracts and Stacks.js Part I: Intro and Project Setup
Tags: clarity, stacks, web3, blockchain
Published: 2022-10-06 16:21:39

## 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](https://www.stacks.co/learn/introduction).

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](https://www.hiro.so/clarinet), a CLI package and developer environment for creating smart contracts, build a frontend using [Stacks.js Starters](https://docs.hiro.so/stacksjs-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](https://explorer.stacks.co/) 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](https://explorer.stacks.co/) 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](https://explorer.stacks.co/sandbox/deploy?chain=testnet) 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](https://www.hiro.so/) 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. :point_down:

### Clarinet
You'll need to install Clarinet. The detailed instructions can be found in the [Hiro docs](https://docs.hiro.so/smart-contracts/clarinet).

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](https://docs.docker.com/get-docker/).

## 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
```

<p>Initialize the frontend directory with:</p>

<pre class="wp-block-code"><code>npm create stacks --template frontend</code></pre>

<p>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.</p>

<p>Now to initialize the backend directory; for readability in separating the contracts from the client, I'll call this clarinet project "backend":</p>

```
clarinet new backend
```
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6mxfyn0vsa8faqguchj5.png)

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
```
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2s3zivux60de8y4otqf0.png)

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`