This is an opinionated boilerplate/starterkit/scaffold to get up and running with smart contract & dApp development in the EVM-ecosystem.
It also comes in handy for hackathons. 👀
By Dennis Zoma 🧙♂️ & Scio Labs 💫.
Table of Contents:
- Package-Manager:
pnpm - Monorepo Tooling:
turborepo - Smart Contract Development:
hardhat- Deploy & Address-Export:
hardhat-deploy - Typescript-Types:
typechain
- Deploy & Address-Export:
- Frontend:
next- Contract Interactions:
wagmi,rainbowkit - Styling:
chakra,tailwindcss,twin.macro,emotion
- Contract Interactions:
- Misc:
- Linting & Formatting:
eslint,prettier,husky,lint-staged
- Linting & Formatting:
Below you find a few live projects that use ETHathon, a variation of it, or have a similar setup setup that inspired it:
- Yieldgate – Hackathon project that built a patreon-like platform to support projects with yield.
- Debate3 – Hackathon project that built discourse-like forums for DAOs.
- Stablecoins.wtf (frontend only) – Crypto Stablecoin Dashboard & Resources
# Install pnpm
npm i -g pnpm
# Install dependencies
pnpm install
# Copy & fill environments
# NOTE: Documentation of environment variables can be found in the according `.example` files
cp packages/frontend/.env.local.example packages/frontend/.env.local
cp packages/contracts/.env.example packages/contracts/.env# Generate contract-types, start local hardhat node, and start frontend with turborepo
pnpm dev
# Only start frontend (from root-dir)
# NOTE: Alternatively it can just be started via `pnpm dev` inside `packages/frontend`
pnpm frontend:devI strongly reommend developing in VSCode by opening the workspace file located at .vscode/ethathon.code-workspace instead of just the directory. This has multiple advantages and assures a more predictable monorepo configuration. The first plugin listed below will help with getting used to it.
I strongly recommend installing all plugins listed inside .vscode/extensions.json. They should be suggested automatically by VSCode.
Plugin Details
zoma.vscode-auto-open-workspace– Automatically suggests opening the according.code-workspacefile.dbaeumer.vscode-eslint– Adds ESLint editor support.esbenp.prettier-vscode– Adds Prettier editor support.NomicFoundation.hardhat-solidity– Adds Solidity language & Hardhat editor support.bradlc.vscode-tailwindcss&lightyen.tailwindcss-intellisense-twin– Adds tailwindcss & twin.macro editor support.- Optional:
gruntfuggly.todo-tree&wayou.vscode-todo-highlight– Lists allTODOcomments in your workspace. - Optional:
mikestead.dotenv– Adds syntax highlighting for.envfiles.
The file packages/frontend/.vscode/frontend.code-snippets contains useful snippets for quickly creating components & pages with Next.js, React, Typescript, and twin.macro. Example: Enter "Function Component with Props" in an empty .tsx file to get a FC component boilerplate with an empty TypeScript interface declaration and already imported 'twin.macro'. Check out the snippet-file itself to get a full overview.
There are multiple places where you need to insert your actual project name/identifier. I've highlighted most of these occurences with a /* TODO */ comment in the code. When installing the todo-tree plugin listed above you can easily replace them one by one.
Additionally, there are the following un-highlighted occurences:
- The name of the
.vscode/*.code-workspacefile - The package names within
package.json,packages/frontend/package.json, andpackages/contracts/package.json - The workspace dependency defined in
packages/frontend/package.json
Setting up a deployment via Vercel is pretty straightforward as build settings are preconfigured in vercel.json. To get started, press the Deploy button and enter the default environment variables listed below.
| Environment Variable | Value |
|---|---|
NEXT_PUBLIC_PRODUCTION_MODE |
true |
NEXT_PUBLIC_URL |
https://your-repo.vercel.app |
NEXT_PUBLIC_DEFAULT_CHAIN |
5 |
NEXT_PUBLIC_DEFAULT_CHAIN |
[5] |
NEXT_PUBLIC_RPC_1 |
https://rpc.ankr.com/eth |
NEXT_PUBLIC_RPC_5 |
https://rpc.ankr.com/eth_goerli |
You can find mode documentation on those environment variables in packages/frontend/.env.local.example. Always make sure to include respective RPCs for supported chains and define them within packages/frontend/src/shared/environment.ts. Valid hardhat deployments under packages/contracts/deployments are mandatory for each supported chain.
What is pnpm and do I really need it?
Pnpm works in my experience way faster and more reliable within monorepos than npm or yarn. When using it though, it's strongly recommended everyone in the team uses it. No installs should perform be performed nor any other lockfiles should be commited.
What is Turborepo and do I really need it?
Turborepo can drastically speed up your incremental builds in monorepos. But you don't have to use it. This is an example on how to rewrite the build task in the root package.json w/o Turborepo: turbo run build → pnpm --filter contracts build && pnpm --filter frontend build.
How to approach styling?
This boilerplate currently offers styling via the following options.
- Chakra UI – Component library for quick prototyping e.g. during hackathons)
- twin.macro – Tailwindcss within Styled Components via Emotion (see snippets)
- Standard (S)CSS styles via
classNameand*.module.(s)cssfiles.
Important, in production it's recommended to use at most one of 1. and 2. to reduce bundle size.
Can I just use plain TailwindCSS?
The packages above can be easily switched out with plain TailwindCSS, a detailed guide on that is coming very soon. In the meantime, open an issue to get guidance.