Build a frontend for the Hello World contract

In the previous examples, we invoked the contracts using the Stellar CLI, and in this last part of the guide we’ll create a web app that interacts with the Hello World contract through TypeScript bindings.

This example shows one way of creating a binding between a contract and a frontend. For a more comprehensive guide to Dapp frontends, see the Build a Dapp Frontend documentation. For tooling that helps you start with smart contracts integrated with a working frontend environment quickly, jump to learn more about Scaffold Stellar.

Initialize a frontend toolchain from scratch

You can build a Stellar dapp with any frontend toolchain or integrate it into any existing full-stack app. For this tutorial, we’re going to use Astro. Astro works with React, Vue, Svelte, any other UI library, or no UI library at all. In this tutorial, we’re not using a UI library. The smart contract-specific parts of this tutorial will be similar no matter what frontend toolchain you use. If you’re new to frontend, don’t worry. We won’t go too deep. But it will be useful for you to see and experience the frontend development process used by smart contract apps. We’ll cover the relevant bits of JavaScript and Astro, but teaching all of frontend development and Astro is beyond the scope of this tutorial. Let’s get started. You’re going to need Node.js v20 or greater. If you haven’t yet, install it now. We want to create an Astro project with the Hello World contract from the previous lessons integrated. To do this, we install the default Astro project:

npm create astro@latest

This project has the following directory structure.

extra-escape
├── astro.config.mjs
├── package-lock.json
├── package.json
├── packages
├── public
├── README.md
├── src
│   ├── assets
│   │   ├── astro.svg
│   │   └── background.svg
│   ├── components
│   │   └── Welcome.astro
│   ├── layouts
│   │   └── Layout.astro
│   └── pages
│       └── index.astro
└── tsconfig.json

Generate an NPM package for the Hello World contract

Before we open the new frontend files, let’s generate an NPM package for the Hello World contract. This is our suggested way to interact with contracts from frontends. These generated libraries work with any JavaScript project (not a specific UI like React), and make it easy to work with some of the trickiest bits of smart contracts on Stellar, like encoding XDR. This is going to use the CLI command stellar contract bindings typescript:

stellar contract bindings typescript \
  --network testnet \
  --contract-id hello_world \
  --output-dir packages/hello_world

Notice that we were able to use the contract alias, hello_world, in place of the contract id!

The binding will be created in as a NPM package in the directory packages/hello_world as specified in the CLI command. We’ll need to build the bindings package, since (in its initial state) the package is mostly TypeScript types and stubs for the various contract functions.

cd packages/hello_world
npm install
npm run build
cd ../..

We attempt to keep the code in these generated libraries readable, so go ahead and look around. Open up the new packages/hello_world directory in your editor. If you’ve built or contributed to Node projects, it will all look familiar. You’ll see a package.json file, a src directory, a tsconfig.json, and even a README.

Call the contract from the frontend

Now let’s open up src/pages/index.astro and use the binding to call the hello contract function with an argument. The default Astro project consists of a page (pages/index.astro) and a welcome component (component/Welcome.astro), and we don’t need any of that code. Replace the pages/index.astro code with this code (the welcome component will not be needed):

src/pages/index.astro

---
import * as Client from './packages/hello_world';

const contract = new Client.Client({
   ...Client.networks.testnet,
   rpcUrl: 'https://soroban-testnet.stellar.org:443'
});

const { result } = await contract.hello({to: "Devs!"});
const greeting = result.join(" ");
---

<h1>{greeting}</h1>

First we import the binding library, and then we need to define a contract client we can use for invoking the contract function we deployed to testnet in a previous step. The hello() contract function is invoked synchronously with the argument {to: "Devs!"} and the expected response is an array consisting of “Hello” and “Devs!”. We join the result array and the constant greeting should now hold the text Hello Devs! Jumping down to the HTML section we now want to display the greeting text in the browser. Let’s see it in action! Start the dev server:

npm run dev

And open localhost:4321 in your browser. You should see the greeting from the contract! You can try updating the argument to { to: 'Stellar' }. When you save the file, the page will automatically update.

When you start up the dev server with npm run dev, you will see similar output in your terminal as when you ran npm run init. This is because the dev script in package.json is set up to run npm run init and astro dev, so that you can ensure that your deployed contract and your generated NPM package are always in sync. If you want to just start the dev server without the initialize.js script, you can run npm run astro dev.

Using Scaffold Stellar to rapidly develop dapps

Scaffold Stellar is a developer toolkit for building decentralized applications and smart contracts on the Stellar blockchain, integrated with a frontend application. Getting a running set of smart contracts and a frontend can be done in just a few short steps with Scaffold Stellar. This tutorial will show you how to make a new Scaffold Stellar project. If you’d like to use existing smart contracts in a Scaffold Stellar project, all you need to do is copy them to the contracts/ folder in your project root!

Install the Scaffold Stellar CLI

Since you already have the Stellar CLI installed, you have everything you need to install Scaffold Stellar:

cargo binstall stellar-scaffold-cli

We recommend using binstall for faster installs, or use cargo install --locked stellar-scaffold-cli. Scaffold Stellar is a plugin on the Stellar CLI, meaning you’ll use stellar scaffold from the command line.

Initialize a fresh Scaffold Stellar project

stellar scaffold init <my-project>

Scaffold Stellar is a plugin on the Stellar CLI, so you’ll run commands as stellar scaffold <command>. init initializes a fresh Stellar Scaffold project at the provided path.

Install Node dependencies & set up environment variables

Make sure you already have Node.js, and run:

cd <my-project> # make sure you're in your new project's directory
npm install # install frontend dependencies
cp .env.example .env # copies the example frontend environment variable file to your own copy

Start your app in development mode!

npm start # or npm run dev

This command does two tasks concurrently: it runs stellar scaffold watch --build-clients which compiles your smart contracts, updating them as you change them, deploying them to your local Stellar chain (make sure Docker is running!), and configures all these settings via your environments.toml file in your root project folder. The second task it runs is vite, a popular JavaScript build tool to compile and watch your React frontend for changes. After a little compiling time, you’ll be able to see your running app at localhost:5173! Learn more about Scaffold Stellar.

​Initialize a frontend toolchain from scratch

​Generate an NPM package for the Hello World contract

​Call the contract from the frontend

​Using Scaffold Stellar to rapidly develop dapps

Initialize a frontend toolchain from scratch

Generate an NPM package for the Hello World contract

Call the contract from the frontend

Using Scaffold Stellar to rapidly develop dapps