Introduction: Why Build in Web3?
The transition from Web2 to Web3 represents one of the most significant shifts in the history of software engineering. In the traditional Web2 model, developers build applications where data is stored in centralized databases owned by corporations. In Web3, the paradigm shifts to decentralized ledgers—blockchains—where data is immutable, permissionless, and owned by the users.
The problem many developers face when entering the Web3 space is the “fragmentation of knowledge.” You might understand how to write a Smart Contract in Solidity, but how do you connect it to a modern React frontend? How do you handle wallet connections or manage state when the “database” is a global network of nodes? This gap often leads to security vulnerabilities and poor user experiences.
In this guide, we will bridge that gap. We are going to build a Decentralized Crowdfunding Platform. This project is perfect because it covers state management, financial transactions (Ether), and complex data structures. By the end of this tutorial, you will have a deep understanding of the full-stack dApp lifecycle, from writing smart contracts to deploying a responsive frontend.
The Modern Web3 Tech Stack
To build a high-performance dApp, we need a robust set of tools. Our stack will consist of:
- Solidity: The primary programming language for writing smart contracts on the Ethereum Virtual Machine (EVM).
- Hardhat: A development environment to compile, deploy, test, and debug Ethereum software.
- Ethers.js: A library that allows our frontend to interact with the Ethereum blockchain.
- Next.js: A React framework for building the user interface.
- Tailwind CSS: For styling our application efficiently.
Step 1: Setting Up Your Development Environment
Before writing a single line of code, we must ensure our environment is prepared. You will need Node.js installed on your machine.
Initialize the Project
Open your terminal and create a new directory for your project:
mkdir decentralized-crowdfund
cd decentralized-crowdfund
mkdir backend frontend
Setting Up the Backend with Hardhat
Navigate to the backend folder and initialize Hardhat:
cd backend
npm init -y
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox
npx hardhat
When prompted, select “Create a JavaScript project” and accept all defaults. This will generate a project structure including folders for contracts, tests, and scripts.
Step 2: Writing the Crowdfunding Smart Contract
Smart contracts are the backbone of any dApp. They are self-executing pieces of code that live on the blockchain. Our contract will allow users to create “campaigns,” contribute Ether, and allow creators to withdraw funds if their goal is met.
Create a file named Crowdfund.sol in the contracts/ directory:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;
/**
* @title Crowdfund
* @dev A simple crowdfunding contract that allows users to fund projects.
*/
contract Crowdfund {
struct Campaign {
address creator;
string title;
string description;
uint256 target;
uint256 deadline;
uint256 amountCollected;
bool claimed;
}
// Mapping to store campaigns by an ID
mapping(uint256 => Campaign) public campaigns;
uint256 public campaignCount = 0;
// Event emitted when a new campaign is created
event CampaignCreated(uint256 id, address creator, string title, uint256 target);
// Event emitted when a donation is made
event DonationReceived(uint256 id, address donor, uint256 amount);
/**
* @dev Creates a new campaign.
* @param _title Title of the project.
* @param _description Description of the project.
* @param _target Goal amount in Wei.
* @param _duration Duration in seconds from now.
*/
function createCampaign(
string memory _title,
string memory _description,
uint256 _target,
uint256 _duration
) public {
require(_target > 0, "Target must be greater than zero");
campaigns[campaignCount] = Campaign({
creator: msg.sender,
title: _title,
description: _description,
target: _target,
deadline: block.timestamp + _duration,
amountCollected: 0,
claimed: false
});
emit CampaignCreated(campaignCount, msg.sender, _title, _target);
campaignCount++;
}
/**
* @dev Allows users to donate to a specific campaign.
* @param _id The ID of the campaign.
*/
function donateToCampaign(uint256 _id) public payable {
Campaign storage campaign = campaigns[_id];
require(block.timestamp < campaign.deadline, "Campaign has ended");
require(msg.value > 0, "Must send some Ether");
campaign.amountCollected += msg.value;
emit DonationReceived(_id, msg.sender, msg.value);
}
/**
* @dev Allows creator to withdraw funds if target is met.
*/
function withdraw(uint256 _id) public {
Campaign storage campaign = campaigns[_id];
require(msg.sender == campaign.creator, "Only creator can withdraw");
require(campaign.amountCollected >= campaign.target, "Target not met");
require(!campaign.claimed, "Funds already claimed");
campaign.claimed = true;
(bool sent, ) = payable(campaign.creator).call{value: campaign.amountCollected}("");
require(sent, "Failed to send Ether");
}
}
Understanding the Code
In the code above, we use a struct to define what a Campaign looks like. A mapping acts like a key-value store to save these campaigns on the blockchain. Notice the use of msg.sender (the address of the person calling the function) and msg.value (the amount of Ether sent with the transaction).
Real-world analogy: Think of the Smart Contract as a vending machine. It has predefined rules (how much an item costs, what happens when you press a button). Once deployed, no one—not even the developer—can change those rules.
Step 3: Testing the Smart Contract
Testing is non-negotiable in Web3. Since smart contracts are immutable and handle real money, a bug can be catastrophic. We will use Hardhat’s built-in testing suite (Mocha and Chai).
Create a file test/Crowdfund.js:
const { expect } = require("chai");
const { ethers } = require("hardhat");
describe("Crowdfund Contract", function () {
let Crowdfund, crowdfund, owner, addr1;
beforeEach(async function () {
// Get signers (mock accounts)
[owner, addr1] = await ethers.getSigners();
// Deploy the contract
Crowdfund = await ethers.getContractFactory("Crowdfund");
crowdfund = await Crowdfund.deploy();
});
it("Should create a campaign correctly", async function () {
const target = ethers.parseEther("10"); // 10 ETH
const duration = 3600; // 1 hour
await crowdfund.createCampaign("Test Project", "Description", target, duration);
const campaign = await crowdfund.campaigns(0);
expect(campaign.title).to.equal("Test Project");
expect(campaign.target).to.equal(target);
expect(campaign.creator).to.equal(owner.address);
});
it("Should allow donations", async function () {
await crowdfund.createCampaign("Donation Test", "Desc", ethers.parseEther("1"), 3600);
// addr1 sends 0.5 ETH
await crowdfund.connect(addr1).donateToCampaign(0, { value: ethers.parseEther("0.5") });
const campaign = await crowdfund.campaigns(0);
expect(campaign.amountCollected).to.equal(ethers.parseEther("0.5"));
});
});
Run the tests using npx hardhat test. You should see all tests passing. This gives us confidence that our logic is sound.
Step 4: Building the Frontend with Next.js
Now that our backend is ready, let’s build the interface that users will interact with. We will use Next.js for its speed and excellent developer experience.
Navigate to the frontend directory and create a new Next.js app:
cd ../frontend
npx create-next-app@latest . --tailwind --eslint
During installation, select “Yes” for the App Router and TypeScript if you prefer (though we will use JavaScript for simplicity in this guide).
Installing Ethers.js
We need Ethers.js to talk to the blockchain. This library acts as the translator between JavaScript and the Ethereum JSON-RPC API.
npm install ethers
Step 5: Connecting the Wallet
In Web3, the “Login” button is replaced by “Connect Wallet.” The user’s wallet (like MetaMask) holds their private keys and signs transactions. Our app needs to request access to this wallet.
Create a utility file utils/web3Provider.js:
import { ethers } from "ethers";
export const getProviderOrSigner = async (needSigner = false) => {
// Connect to MetaMask
const provider = new ethers.BrowserProvider(window.ethereum);
if (needSigner) {
const signer = await provider.getSigner();
return signer;
}
return provider;
};
In your app/page.js, let’s add the connection logic:
"use client";
import { useState, useEffect } from "react";
import { getProviderOrSigner } from "../utils/web3Provider";
export default function Home() {
const [walletConnected, setWalletConnected] = useState(false);
const [userAddress, setUserAddress] = useState("");
const connectWallet = async () => {
try {
const signer = await getProviderOrSigner(true);
const address = await signer.getAddress();
setUserAddress(address);
setWalletConnected(true);
} catch (err) {
console.error(err);
}
};
return (
<main className="flex flex-col items-center justify-center min-h-screen p-24">
{!walletConnected ? (
<button
onClick={connectWallet}
className="bg-blue-600 text-white px-6 py-2 rounded-lg"
>
Connect Wallet
</button>
) : (
<p className="text-green-600">Connected: {userAddress}</p>
)}
</main>
);
}
Step 6: Interacting with the Smart Contract
To call functions on our smart contract, we need two things: the Contract Address and the ABI (Application Binary Interface). The ABI is a JSON file generated by Hardhat during compilation that tells our frontend how to interact with the contract’s functions.
Deploying the Contract Locally
In the backend folder, run a local blockchain node:
npx hardhat node
In a new terminal, deploy the contract to this local node:
npx hardhat run scripts/deploy.js --network localhost
Note the deployed address. Copy the Crowdfund.json from backend/artifacts/contracts/Crowdfund.sol/ into your frontend folder.
Creating a Campaign via Frontend
import { ethers } from "ethers";
import CrowdfundABI from "./Crowdfund.json";
const contractAddress = "YOUR_DEPLOYED_ADDRESS_HERE";
async function handleCreateCampaign() {
const signer = await getProviderOrSigner(true);
const contract = new ethers.Contract(contractAddress, CrowdfundABI.abi, signer);
// Create a campaign: Title, Description, Target (1 ETH), Duration (1 day)
const tx = await contract.createCampaign(
"Save the Oceans",
"Cleaning up plastic from the Pacific",
ethers.parseEther("1.0"),
86400
);
await tx.wait(); // Wait for the transaction to be mined
alert("Campaign Created!");
}
Common Mistakes and How to Fix Them
1. Incorrect Provider Usage
Mistake: Trying to send a transaction using a Provider instead of a Signer.
Fix: In Ethers.js, a Provider is read-only. To change state on the blockchain (send Ether, call a writing function), you must use signer = await provider.getSigner().
2. Handling BigInts
Mistake: Treating Ether values as standard JavaScript numbers.
Fix: Ethereum uses 18 decimal places. JavaScript’s Number type loses precision. Always use BigInt or ethers.parseEther() and ethers.formatEther() to handle values.
3. Forgetting to Await Transactions
Mistake: Assuming a transaction is finished as soon as the function returns.
Fix: contract.function() returns a transaction response. You must call await tx.wait() to wait for the block to be mined and the state to update.
4. Hardcoding Gas Limits
Mistake: Manually setting gas limits that are too low.
Fix: Let Ethers.js and the wallet (MetaMask) estimate the gas for you. Only override gas settings if you are building complex DeFi protocols.
Best Practices for Web3 Developers
- Fail Loudly: Use
requirestatements in Solidity with clear error messages. - Optimize for Gas: Storage is expensive. Use
uint8instead ofuint256where appropriate, but be careful of overflow (though Solidity 0.8.x handles this automatically). - Events are Your Best Friend: Frontend indexing is slow. Emit events in Solidity and use listeners in your frontend to update the UI in real-time.
- Environment Variables: Never, ever hardcode your private keys in your code. Use
.envfiles and add them to.gitignore.
The Lifecycle of a Web3 Transaction
To truly understand how your dApp works, let’s trace the path of a transaction:
- User Action: User clicks “Donate” on your Next.js site.
- Frontend Preparation: Ethers.js encodes the function call and the Ether value into data that the blockchain understands.
- Wallet Request: MetaMask pops up, showing the user the gas cost and the details of what they are about to sign.
- Signing: The user approves. MetaMask signs the transaction with the user’s private key (without revealing the key to the app).
- Broadcasting: The signed transaction is sent to an Ethereum node (like Alchemy, Infura, or your local Hardhat node).
- Mempool: The transaction sits in the “Mempool” (memory pool) waiting for a miner/validator to pick it up.
- Mining/Validation: A validator includes the transaction in a block.
- Confirmation: Your frontend, which is “waiting” via
tx.wait(), receives the receipt and updates the UI to show success.
Scaling and Deployment
Once your dApp works locally, it’s time to move to a Testnet (like Sepolia or Holesky) before going to Ethereum Mainnet. Testnets use “fake” Ether that you can get for free from a “Faucet,” allowing you to test in a production-like environment without spending real money.
For the frontend, platforms like Vercel or Netlify are excellent for hosting Next.js apps. Since the backend is decentralized, you only need to host the static assets of your frontend!
Summary and Key Takeaways
- Web3 is about ownership: Data lives on the blockchain, not a central server.
- Smart Contracts are immutable: Once deployed, the code cannot be changed, making testing essential.
- The “Glue”: Ethers.js is the critical link between your React frontend and the Ethereum blockchain.
- UX Matters: Always handle loading states and wallet disconnection to ensure a smooth user experience.
- Security First: Always validate inputs and use established libraries like OpenZeppelin for more complex needs.
Frequently Asked Questions (FAQ)
1. What is the difference between a Provider and a Signer?
A Provider is a read-only connection to the blockchain. It allows you to query data like account balances or read contract state. A Signer is a connection that has access to a private key (usually via a wallet), allowing you to sign and send transactions to change the blockchain’s state.
2. Why do I need to pay “Gas”?
Gas is the fee paid to validators to process your transaction and include it in the blockchain. It prevents spam and compensates the people running the network hardware. Complex transactions (like creating a campaign) cost more gas than simple ones (like sending Ether).
3. Can I use a traditional database with my dApp?
Yes. Many modern dApps use a “Hybrid” approach. They store critical data (ownership, financial records) on-chain and non-critical data (user profiles, comments) in a traditional database (like MongoDB) or decentralized storage (like IPFS).
4. How do I update my smart contract after it’s deployed?
Standard smart contracts cannot be updated. However, you can use “Proxy Patterns” or “Upgradable Contracts.” This involves a proxy contract that points to an implementation contract. To “update,” you simply point the proxy to a new implementation address.
5. Is Solidity the only language for Web3?
No, but it is the most popular for the EVM. Others include Vyper (Pythonic), Rust (used for Solana and Polkadot), and Move (used for Aptos and Sui).