@create-soroban-dapp
is both an npx
script and a boilerplate dApp for kickstarting any of your ideas for a Soroban-based DApp.
Largely inspired by the ink!athon project by Scio Labs and by @create-t3-app by T3 Open Source for the script mechanisms.
Check the LIVE VERSION
of the dApp utilizing already deployed testnet contracts!
Read the docs here 📚📚
@create-soroban-dapp
is composed of two key components:
- A boilerplate dApp utilizing the @soroban-react library.
- An
npx
script allowing any developer to quickly start their project via the command line usingnpx create-soroban-dapp
.
To create a new Soroban dApp project, simply use one of the following commands:
npx create-soroban-dapp@latest
or
npm create soroban-dapp@latest
After the script completes, navigate into your newly created project directory:
cd your-project-name
The script, in its early stage, might not function perfectly on every OS and configuration. If it fails to run properly, please report the issue to @benjaminsalon
on the Stellar developer Discord channel.
If the script fails or if you prefer manual setup, you can clone the repository directly:
git clone git@github.com:paltalabs/create-soroban-dapp.git
After cloning, the dApp will not be in the root folder. Instead, you'll find it in the soroban-react-dapp
subfolder:
cd soroban-react-dapp
From there, it functions like a standard Next.js app:
yarn install
# or npm install
# or pnpm install
When deploying contracts, you'll need the secret key of the deployer account. This secret key will be stored in an ignored file located at ./contracts/.env
.
To set up your secrets, run:
cp contracts/.env.example contracts/.env
If you're already inside the contracts folder (e.g., within the Docker Container), run:
cp .env.example .env
Then, edit the .env
file lcoated in soroban-react-dapp/contracts
to include your secret keys and RPC URLs. The .env
file should look like this:
# Stellar accounts Secret Keys
ADMIN_SECRET_KEY=
# RPC Setup
MAINNET_RPC_URL=
You can generate new accounts and private keys from Stellar Laboratory.
If you plan to deploy on the mainnet, you'll also need a Mainnet RPC Provider. You can find one at Validation Cloud or NowNodes.
We will use Docker Compose to set up and run the necessary containers. This includes a container for a local Stellar blockchain and another container with Soroban Preview, which contains all the dependencies needed to deploy and interact with the contracts.
First, navigate to the soroban-react-dapp/
directory where the docker-compose.yml
file is located:
cd soroban-react-dapp/
To give a custom name to the project, copy the .env.example
file to .env
using:
cp .env.example .env
then, edit the .env
file in your soroban-react-dapp
folder to include your project ID:
PROJECT_ID=your-project-id
Note
By default the containers name will be something like soroban-preview-${dirname-timestamp}
and soroban-contracts-${dirname-timestamp}
.
To bring up the necessary containers, run:
bash run.sh
This command will start the following services:
- soroban-preview: Provides the Soroban environment required to compile, deploy, and interact with your contracts. This container will have the terminal attached to it, allowing for direct interaction with the Soroban environment.
- stellar: Runs a local Stellar blockchain with Soroban support enabled. This service will run in the background, providing the necessary infrastructure for the Soroban environment.
Once inside the soroban-preview
container, navigate to the contracts/
directory to compile and deploy your contracts:
# Move to the contracts folder
cd contracts
# Build the contracts
make build
# Install dependencies and deploy the contract
yarn install
yarn deploy testnet greeting
After deploying the contracts, you can start the frontend of your dApp:
# Move to the parent folder
cd ..
# Install the dependencies
yarn
# Run the frontend in development mode
yarn dev
To stop the containers when you're done, run:
docker compose down
Here’s a breakdown of the docker-compose.yml
file:
-
soroban-preview:
- image: Uses the
esteblock/soroban-preview:21.0.1
image. - container_name: The container name is dynamically set based on the
${PROJECT_ID}
. - volumes: Maps the current directory to
/workspace
inside the container. - ipc: host: Shares the IPC namespace with the host.
- ports: Exposes port
3000
on the host, which will be used for the frontend. - networks: The container is connected to the
create-soroban-network
. - command: Keeps the container running by executing
tail -f /dev/null
.
- image: Uses the
-
stellar:
- image: Uses the
stellar/quickstart
image with Soroban support. - container_name: The container name is dynamically set based on the
${PROJECT_ID}
. - networks: Connected to the
create-soroban-network
. - ports: Exposes port
8000
on the host, used for interacting with the Stellar blockchain. - command: Runs Stellar with Soroban RPC and diagnostic events enabled.
- image: Uses the
-
networks:
- create-soroban-network: A custom bridge network for container communication.
This setup ensures a fully functional development environment for Soroban dApp development.