This is an opinionated boilerplate to get up and running with dApp development in the Substrate ecosystem, especially with ink! smart contracts. It uses custom-built useInkathon
React Hooks that abstract & improve the polkadot.js experience.
By Dennis Zoma π« & Scio Labs πͺ
Table of Contents:
- Disclaimer π¨
- The Stack
- Projects using it
- Getting Started
- Development
- Customization
- Deployment
- FAQs & Troubleshooting
This repository is still work-in-progress and there are probably bugs. See the open issues.
- Package-Manager:
pnpm
- Smart Contract Development:
ink!
,cargo
- Frontend:
next
- Contract Interactions:
polkadot-js
,useInkathon
React Hooks - Styling:
chakra
,tailwindcss
,twin.macro
,emotion
- Contract Interactions:
- Misc:
- Linting & Formatting:
eslint
,prettier
,husky
,lint-staged
- Linting & Formatting:
Below you find a few projects that use this boilerplate, a variation of it, or have a similar setup that inspired it:
- AZERO Domains β Domain Name Service for Aleph Zero
# 1. Install pnpm (https://pnpm.io/installation)
npm i -g pnpm
# 2. Install dependencies
pnpm install
# 3. Copy & fill environments
# NOTE: Documentation of environment variables can be found in the according `.example` file
# NOTE: Start with only the alephzero-testnet
cp packages/frontend/.env.local.example packages/frontend/.env.local
# 1. Install Rust: https://docs.substrate.io/install/
# NOTE: Leave out the "Compile a Substrate node" part for now
rustup component add rust-src
rustup target add wasm32-unknown-unknown
# 2. Install ink! tooling (https://use.ink/getting-started/setup#ink-cli)
cargo install cargo-contract --force --locked --git https://github.com/paritytech/cargo-contract.git
cargo install cargo-dylint dylint-link --force --locked
# 3. Install local substrate-contracts-node (https://github.com/paritytech/substrate-contracts-node)
cargo install contracts-node --force --git https://github.com/paritytech/substrate-contracts-node.git
# NOTE: Can be executed in both, the root-dir or in `packages/frontend/`
# Start Frontend (Next.js)
pnpm dev
I created shorthand npm-scripts for most interactions (e.g. build, or starting a local node). Therefore, to execute those the active terminal directory needs to be packages/contracts
. The full commands can be found in packages/contracts/package.json
.
# Start local node with persistence & open contracts-ui
# NOTE: When using Brave, shields have to be taken down for the UIs
# NOTE: Just use `pnpm node` to not automatically open contracts-ui
pnpm dev
# Build Contracts
pnpm build
# Deploy Contracts with the generated `*.contract` file
# via drag'n'drop in contracts-ui in the browser
# Copy the deployed contracts address and save it via the following command
ADDRESS=β¦ pnpm write-address
# NOTE: This command can also be adapted for different contracts and chains
ADDRESS=123 CHAIN=alephzero-testnet CONTRACT=new_greeter pnpm write-address
# Test Contracts
pnpm test
I strongly recommend developing in VSCode by opening the workspace file located at .vscode/inkathon.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-workspace
file.dbaeumer.vscode-eslint
β Adds ESLint editor support.esbenp.prettier-vscode
β Adds Prettier editor support.bradlc.vscode-tailwindcss
&lightyen.tailwindcss-intellisense-twin
β Adds tailwindcss & twin.macro editor support.bungcip.better-toml
β Adds.toml
file support.rust-lang.rust-analyzer
β Adds Rust language support.- Optional:
gruntfuggly.todo-tree
&wayou.vscode-todo-highlight
β Lists allTODO
comments in your workspace. - Optional:
mikestead.dotenv
β Adds syntax highlighting for.env
files.
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 highlighted most of these occurrences 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 occurrences:
- The name of the
.vscode/*.code-workspace
file - 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 |
alephzero-testnet |
NEXT_PUBLIC_DEFAULT_CHAIN |
["alephzero-testnet"] |
You can find more documentation on those environment variables in packages/frontend/.env.local.example
and all available blockchain network identifiers in the useInkathon
repository.
What is pnpm and do I need it?
Pnpm works in my experience way faster and more reliably within monorepos than npm or yarn. When using it though, it's strongly recommended everyone on the team uses it. No installs should perform be performed nor any other lock files should be committed.
Also, esp. the contracts
package has multiple shorthand npm scripts defined in its package.json
that are recommended to use.
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
className
and*.module.(s)css
files.
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 that is coming soon. In the meantime, open an issue to get guidance.