@create-soroban-dapp

@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 📚📚

Introduction

@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 using npx create-soroban-dapp.

Usage

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

Troubleshooting

If the npm create Script Malfunctions

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.

Manual Cloning

If the script fails or if you prefer manual setup, you can clone the repository directly:

git clone [email protected]: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

Set Up Your Secrets!

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.

Get Those Containers Up!

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.

1. Move to the Right Directory

First, navigate to the soroban-react-dapp/ directory where the docker-compose.yml file is located:

cd soroban-react-dapp/

2. Setting up the containers

2.1 Copy the .env File

To give a custom name to the project, copy the .env.example file to .env using:

cp .env.example .env

2.2 Naming the containers

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}.

3 Run the Containers

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.

4. Compile and Deploy Contracts

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

5. Run the Frontend

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

6. Stopping the Containers

To stop the containers when you're done, run:

docker compose down

7. Explanation of the docker-compose.yml Configuration

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.

• 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.

• networks:

  • create-soroban-network: A custom bridge network for container communication.

This setup ensures a fully functional development environment for Soroban dApp development.