A starter repository for building full stack Ethereum dApps with Solidity and Next.js.

This code is for anyone looking to quickly bootstrap an EVM dApp using modern best practices. In particular, developers with existing JavaScript/TypeScript experience who're newer to Solidity.

If you want to learn how to interact with a simple smart contract from the client side, this repository is for you.

• Get started
• Read changelog

packages/contracts - All smart contract files.

• Alchemy
• Hardhat
• Mocha
• Chai
• Solidity
• TypeScript
• Prettier

• yarn start - Starts your local Hardhat network
• yarn test - Tests Greeter.sol's functionality
• yarn deploy - Deploys Greeter.sol to your local Hardhat network
• yarn deploy:sepolia - Deploys Greeter.sol to the Sepolia test network
• yarn format - Formats all code using Prettier

packages/app - All client application files.

• Alchemy
• Next.js
• Tailwind CSS
• viem
• wagmi
• RainbowKit
• TypeScript
• Prettier

• yarn dev - Starts the Next.js local development environment
• yarn build - Creates an optimised production build of your app
• yarn start - Starts the Next.js application in production mode
• yarn lint - Checks for problems in your code using ESLint
• yarn format - Formats all code using Prettier

• Node
• MetaMask

How to get running on your local machine:

Use git clone https://github.com/tomhirst/solidity-nextjs-starter.git to clone this repository to your local machine.

Enter the repository folder with cd solidity-nextjs-starter, then install all dependencies using yarn.

Solidity Next.js Starter uses Yarn workspaces, so this will install the relevant dependencies for each packages in one command.

Enter the contracts folder with cd packages/contracts and start your local hardhat node with yarn start. If you're successful, you'll be presented with a number of accounts (one of which you'll need later). Here's an example:

Account #0: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000 ETH)
Private Key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

In a new terminal window, deploy the Greeter contract using yarn deploy. If you're successful, you'll get a contract address (that you'll also need later) like this:

Greeter with greeting "Hello, world!" deployed to 0x5FbDB2315678afecb367f032d93F642f64180aa3

Enter the app folder with cd packages/app from the root directory.

You'll need a RainbowKit project ID. You can get one from WalletConnect Cloud and it will look something like this: 206a512b7abd9c469123b45fb272b68e (not a real key).

Afterwards, duplicate .env.example and rename the file .env. Then add your RainbowKit project ID like this: NEXT_PUBLIC_RAINBOWKIT_PROJECT_ID=[your-project-id].

NEXT_PUBLIC_CHAIN_ID should already be set to the Hardhat local network ID of 31337 (change this when you want your app to run on other chains).

Finally, set NEXT_PUBLIC_CONTRACT_ADDRESS using the contract address you recieved when you deployed. For example: NEXT_PUBLIC_CONTRACT_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3

Once your environment variables are set, run the application using yarn dev. To view, open up localhost:3000 (or whatever port Next.js has assigned) in your browser.

To fully demo the apps' features, you'll need a web3 wallet extension. If you don't have MetaMask installed already, you can get it here.

If you haven't used Hardhat before, you'll need to add a test account to write to the smart contract that you deployed. Do this by importing one of the accounts you noted down earlier to MetaMask using the accounts' private key (for example, 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80).

Once connected to the app with the test account, you can set a new greeting on the blockchain by using the form on page. You'll get a confirmation message if you're successful.

Instructions for deploying the smart contract and application to publically viewable environments:

Up to now, your smart contract has been running locally. The next step is to deploy it to a live test network. We'll use Sepolia for this.

First you need some Sepolia test ETH. You can get some from a Sepolia Faucet.

In the packages/contracts directory, duplicate .env.example to .env. You'll need an Alchemy API key and the private key of the wallet you'd like to deploy your Sepolia contract from. I recommend using a burner account that doesn't hold any valuable assets on other chains.

Set the environment variables like so:

ALCHEMY_API_KEY=[your-api-key]
SEPOLIA_PRIVATE_KEY=[your-private-key]

Finally, run yarn deploy:sepolia. If you're successful, you'll get a message ike this in your terminal window:

Greeter with greeting "Hello, world!" deployed to 0xE47c47B1db8823BA54aae021cfce03b2d37B52a8

Here's a version of the contract I deployed earlier: 0xE47c47B1db8823BA54aae021cfce03b2d37B52a8

Let's verify your newly deployed contract with Etherscan. First, get an Etherscan API key here. Then add it to your .env file:

ETHERSCAN_API_KEY=[your-api-key]

Run yarn verify:sepolia [your-contract-address] 'Hello, world!' to verify your contract. Be sure to pass the address of the contract you just deployed and the constructor parameter, which in this case is the default greeting.

If you're successful, you'll get a message like this:

Successfully verified contract Greeter on the block explorer.

Let's look at deploying your application.

To interact with smart contracts on a testnet or mainnet from your app, you'll need an Alchemy API key. You can get one here if you didn't get one earlier.

Add this to .env in packages/app like so:

ALCHEMY_API_KEY=[your-api-key]

This will let you point your front end at a publically viewable contract on a network like Sepolia or mainnet.

You can deploy the application to Vercel by clicking this button:

Be sure to deploy from the packages/app directory and set these environment variables:

NEXT_PUBLIC_ALCHEMY_API_KEY=[your-api-key]
NEXT_PUBLIC_CONTRACT_ADDRESS=[your-contract-address]
NEXT_PUBLIC_CHAIN_ID=[your-chain-id]
NEXT_PUBLIC_RAINBOWKIT_PROJECT_ID=[your-project-id]

Here's an app I deployed earlier: https://solidity-nextjs-starter-app.vercel.app/

I built this to onboard myself to web3. Since 2021, Solidity Next.js Starter has amassed 100s of GitHub stars and helped devs land dream gigs in the space.

All suggestions for improvement are welcome. Please submit a pull request to contribute.

All code in this repository is unaudited. Use at your own risk.