Skip to main content

Chain Hosted UI tutorial

Chain Hosted UI lets you to deploy dApp frontends directly on the NEAR blockchain. In this tutorial you'll learn how to build and deploy a simple React web app using Chain Hosted UI.

warning

This experiment reached the MVP stage of functionality but no longer has a maintainer due to Pagoda winding down. We encourage interested parties to fork the project and carry it forward. The smart contract has not yet been audited.

Requirementsโ€‹

To build and deploy your web3 dApp, you'll need to have installed:

If you already have NodeJS, installing TypeScript and pnpm is simple:

TypeScriptโ€‹

npm install -g typescript

pnpmโ€‹

npm install -g pnpm

Getting Startedโ€‹

Let's get started by cloning the chain hosted repository from GitHub. You'll take advantage of a demo React project in this monorepo to build your new React application.

git clone https://github.com/near/chain-hosted-ui

After cloning, you need to install the dependencies from the chain-hosted-ui folder:

Installโ€‹

cd chain-hosted-ui
pnpm install

Next, it's time to build all the packages included in the Chain Hosted solution:

Build allโ€‹

pnpm run build

React Appโ€‹

Now you can jump to the demo React project included in the chain-hosted-ui repository. This demo project provides the boilerplate code and preconfigured settings so you can start building your web app right away:

cd packages/react

In this folder you can build, edit, add components, content, or npm dependecies to your React web app. For example, you can edit src/App.tsx and add a "Hello World!" paragraph:

When ready, you can test your sample React dApp locally:

Run web appโ€‹

npm run dev

Blockchain Deploymentโ€‹

If you want to deploy your React frontend to the NEAR blockchain, you'll need to update the project's settings, and then run the deploy script.

Settingsโ€‹

To update the settings, configure the nearDeployConfig field in package.json:

Configuration parametersโ€‹

  • application is developer-defined and will be used as part of the URL (names should match [a-z_-]+)
  • deployerAccount is the account paying for bundle storage and calling smart contract methods (must match DEPLOYER_ACCOUNT.near referenced above)
  • filestoreContract is the hosted storage contract
    • v1.chain-hosted-ui.testnet on testnet v1.chain-hosted-ui.near
    • or deployed and configured separately

Account loginโ€‹

Before you can deploy your app, you need to set credentials to your NEAR account. You can do it by adding a new key into your account and saving it into the legacy keychain.

near account add-key <accountId> grant-full-access autogenerate-new-keypair save-to-legacy-keychain network-config testnet sign-with-keychain send

The JSON file will be saved at the path ~/.near-credentials/mainnet/YOUR_ACCOUNT.near.json (replace mainnet with testnet for testnet). Edit the created file to make sure it has following structure:

{
"account_id":"YOUR_ACCOUNT.near",
"public_key":"ed25519:44_CHARACTERS_BASE_58",
"private_key":"ed25519:88_CHARACTERS_BASE_58"
}

Deployโ€‹

After you've set up your account and contract settings, you can build the project bundle and deploy the application on chain by running:

npm run deploy

The deployment script will estimate the storage cost in NEAR tokens, and ask you to confirm the transaction:

react-example deployment calculated to cost 4.08204 N {
appKey: '<YOUR_ACCOUNT_ID>/react-example',
newAppChars: 96,
fileKeyChars: 327,
partitionKeyChars: 339,
fileBytes: 388004
}
? Estimated cost to deploy is 4.08204 N. Continue? (y/N)

Once you've deployed your frontend, you can load the web application at https://chain-hosted-ui.near.dev//<FILE_CONTRACT>/<DEPLOYER_ACCOUNT.near>/<APPLICATION-NAME>

  • <FILE_CONTRACT>: v1.chain-hosted-ui.testnet or v1.chainui.near
  • <DEPLOYER_ACCOUNT.near>: the NEAR account used to deploy, e.g. myaccount.testnet
  • <APPLICATION-NAME>: the application name you defined, e.g. react-example
  • Check this deployed example

Redeploymentโ€‹

Once deployed, new deployments can be made or the application can be removed (with any remaining storage being refunded):

  • To deploy a new version after making changes, run
    pnpm run deploy
    This will increment the application version, delete previous files, and refund any remaining available balance.
  • To delete application storage, refund storage-staked Near, and unregister the deployment account, run
    pnpm delete-and-unregister
  • To drop and recreate the application, run
    pnpm clean-deploy

Also note that in order to do a roll forward deployment, both sets of application files must exist simultaneously to avoid downtime. Consequently, storage must be paid ahead of each deployment to account for the new files, regardless of whether the application is already deployed. Once the deployment is live, the files from the previous deployment are deleted and storage is refunded as part of the deployment script.

Was this page helpful?