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.
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:
- App.tsx
Loading...
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
:
- package.json
Loading...
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 matchDEPLOYER_ACCOUNT.near
referenced above)filestoreContract
is the hosted storage contractv1.chain-hosted-ui.testnet
on testnetv1.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
orv1.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
This will increment the application version, delete previous files, and refund any remaining available balance.
pnpm run deploy
- 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.