-
Notifications
You must be signed in to change notification settings - Fork 362
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Chain deployed UI project documentation (#2145)
* Update chain-ui.md * Update chain-ui-tutorial.md * Update sidebars.js --------- Co-authored-by: andy-haynes <36863574+andy-haynes@users.noreply.github.com>
- Loading branch information
1 parent
62eb63b
commit 7692aa8
Showing
3 changed files
with
270 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,186 @@ | ||
| --- | ||
| id: chain-hosted-ui-tutorial | ||
| title: Chain Hosted UI tutorial | ||
| sidebar_label: Chain Hosted UI Tutorial | ||
| --- | ||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
| import {CodeTabs, Language, Github} from "@site/src/components/codetabs"; | ||
|
|
||
| [Chain Hosted UI](chain-ui.md) 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](https://react.dev/) web app using Chain Hosted UI. | ||
|
|
||
| :::info Learn more | ||
| If you want to learn more about the Chain Hosted UI solution for hosting frontends directly on chain, check [this article](chain-ui.md). | ||
| ::: | ||
|
|
||
| ## Requirements | ||
|
|
||
| To build and deploy your web3 dApp, you'll need to have installed: | ||
|
|
||
| - [NodeJS](https://nodejs.org) | ||
| - [TypeScript](https://typescriptlang.org) | ||
| - [pnpm](https://pnpm.io/) | ||
|
|
||
| If you already have NodeJS, installing TypeScript and `pnpm` is simple: | ||
|
|
||
| #### TypeScript | ||
|
|
||
| ```sh | ||
| npm install -g typescript | ||
| ``` | ||
|
|
||
| #### pnpm | ||
|
|
||
| ```sh | ||
| npm install -g pnpm | ||
| ``` | ||
|
|
||
| ## Getting Started | ||
|
|
||
| Let's get started by cloning the [chain hosted repository](https://github.com/near/chain-hosted-ui/) from GitHub. | ||
| You'll take advantage of a demo React project in this monorepo to build your new React application. | ||
|
|
||
| ```sh | ||
| git clone https://github.com/near/chain-hosted-ui | ||
| ``` | ||
|
|
||
| After cloning, you need to install the dependencies from the `chain-hosted-ui` folder: | ||
|
|
||
| #### Install | ||
|
|
||
| ```sh | ||
| cd chain-hosted-ui | ||
| pnpm install | ||
| ``` | ||
|
|
||
| Next, it's time to build all the packages included in the Chain Hosted solution: | ||
|
|
||
| #### Build all | ||
|
|
||
| ```sh | ||
| 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: | ||
|
|
||
| ```sh | ||
| 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: | ||
|
|
||
| <CodeTabs> | ||
| <TabItem value="App.tsx"> | ||
| <Github url="https://github.com/near/chain-hosted-ui/blob/35e3b518e2a1348eb94d85749a12a591616cc64e/packages/react/src/App.tsx" start="16" end="21" language="jsx" /> | ||
| </TabItem> | ||
| </CodeTabs> | ||
|
|
||
|
|
||
| When ready, you can test your sample React dApp locally: | ||
|
|
||
| #### Run web app | ||
|
|
||
| ```sh | ||
| 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`: | ||
|
|
||
| <CodeTabs> | ||
| <TabItem value="package.json"> | ||
| <Github url="https://github.com/near/chain-hosted-ui/blob/35e3b518e2a1348eb94d85749a12a591616cc64e/packages/react/package.json" start="42" end="46" language="jsx" /> | ||
| </TabItem> | ||
| </CodeTabs> | ||
|
|
||
| #### 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 login to your NEAR account. | ||
|
|
||
| Currently the Chain Hosted deployment scripts only support the [Near CLI JS](https://github.com/near/near-cli) keystore. This CLI can be used to [initialize keystore credentials](../../4.tools/cli.md#near-login) for the deployment account: | ||
|
|
||
| ```sh | ||
| near login | ||
| ``` | ||
|
|
||
| :::note | ||
|
|
||
| Alternatively, this may be configured manually by creating a JSON file at the path | ||
| `~/.near-credentials/mainnet/DEPLOYER_ACCOUNT.near.json` (replace `mainnet` with `testnet` for testnet) with the | ||
| following content: | ||
| ```js | ||
| { | ||
| "account_id":"DEPLOYER_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: | ||
|
|
||
| ```sh | ||
| 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](https://chain-hosted-ui.near.dev/v1.chain-hosted-ui.testnet/solops2.testnet/react-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 | ||
| ```sh | ||
| 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 | ||
| ```sh | ||
| pnpm delete-and-unregister | ||
| ``` | ||
| - To drop and recreate the application, run | ||
| ```sh | ||
| 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| --- | ||
| id: chain-hosted-ui | ||
| title: Chain Hosted UI | ||
| sidebar_label: Chain Hosted UI | ||
| --- | ||
|
|
||
| [Chain Hosted UI](https://github.com/near/chain-deployed-ui) is a [decentralized frontend solution](frontend.md#decentralized-frontend-solutions) that lets you to deploy dApp frontends directly on the NEAR blockchain. A frontend can be built with typical Web2 tooling (e.g. React + Vite + node.js dependencies), and the resulting compressed bundle can be stored in the state of a smart contract. | ||
|
|
||
| :::info Keep in mind | ||
|
|
||
| This is an early stage project, and the solution hasn’t been battle tested to the point it can be recommended for production use. | ||
|
|
||
| ::: | ||
|
|
||
| ## Overview | ||
|
|
||
| Thanks to the fact that storage on NEAR is cheap, it's feasible to host lightweight applications with optimized bundles on chain. This offers a straightforward path to decentralized hosting as an alternative to static deployment platforms such as Vercel, GitHub Pages, Render, and others. | ||
|
|
||
| The Chain Deployed UI tooling provides the boilerplate app code (React, Vue, TypeScript), along with the `FileStore` smart contract and basic CDN tools so you can build a dApp, pack it, and store it on chain. | ||
|
|
||
| This `FileStore` smart contract deployed by NEAR is designed to store and serve dApp bundles for any user, so you don't need to have an understanding of smart contract development. You only need to understand how to sign a transaction (with help from our tooling) and to have enough NEAR tokens to pay for storage. | ||
|
|
||
| :::tip | ||
|
|
||
| You can still deploy your own file storage smart contract if you want to have additional customization or if you want total control over your data. | ||
|
|
||
| ::: | ||
|
|
||
| ### Pros | ||
|
|
||
| - By decentralizing the hosting of your front-end, you minimize the risk of censoring or blocking content by centralized authorities. | ||
| - Users might trust a decentralized application more, knowing that it operates on a transparent and immutable blockchain. | ||
| - Data displayed on the front-end is more likely to be accurate and tamper-proof since it's typically fetched directly from the blockchain. | ||
|
|
||
| ### Cons | ||
|
|
||
| - Implementing a decentralized front-end can be more complex than traditional web development, requiring knowledge of additional technologies like [IPFS](https://ipfs.tech), [Arweave](https://arweave.org), or blockchain interactions. | ||
| - Decentralized networks can face issues such as latency or lower speeds compared to traditional centralized servers, potentially affecting user experience. | ||
| The ecosystem for developing decentralized frontends is still maturing, which means there might be fewer tools and libraries available than for traditional web development. | ||
| - While decentralized storage costs have been decreasing, they can still be higher than traditional hosting, especially if the dApp generates a lot of data transactions. | ||
|
|
||
| ## How it works | ||
|
|
||
| A standard workflow of the chain deployed solution would be: | ||
| - Building, packing, and compressing the web app frontend | ||
| - Uploading the web app bundle files using the `FileStore` smart contract | ||
| - Serving the web app using a CDN gateway | ||
|
|
||
| Once the web app has been uploaded to the blockchain, a web [Gateway](#gateway) converts browser requests to blockchain [RPC](#rpc) calls, so users can access your decentralized application. | ||
|
|
||
| ### Gateway | ||
|
|
||
| A gateway server is required to convert browser resource requests to RPC calls. For convenience, gateways may be deployed to cloud hosts, but this causes some centralization. It can be mitigated by having multiple gateways run by different parties. It is important that a user trust the gateway provider however, since the gateway is ultimately what is in control of the experience being served to the user's browser. | ||
|
|
||
| ### RPC | ||
|
|
||
| An [RPC provider](../../5.api/rpc/providers.md) services requests for chain data. For resilience, gateways should ideally be capable of falling back to a different provider in the event the primary provider is experiencing degraded service. | ||
|
|
||
| ## Considerations | ||
|
|
||
| Compared to classic Web2 hosting solutions, the cost structure of a chain-deployed dApp is very different. | ||
|
|
||
| When deploying on chain, you pay a one-time fee for the storage space of your compressed bundles. This means that it's critical to pay attention to the size of dependencies you include in your application, as packages that are bloated or do not support proper tree-shaking will directly affect your cost. | ||
|
|
||
| :::info | ||
|
|
||
| NEAR uses [storage staking](../../1.concepts/storage/storage-staking.md), where NEAR tokens are locked while storage is being used and refundable in the event of deleting that data from smart contract state. The cost of storage is `1 NEAR` per `100 Kb`. | ||
|
|
||
| ::: | ||
|
|
||
| ### Storage Optimization | ||
|
|
||
| Additional storage optimization can be achieved by building your dApp from a provided template with preconfigured code splitting. This allows you to yield separate bundles for the template boilerplate and the custom dApp code: | ||
| - The template boilerplate can be uploaded once, and then served for every dApp built using that template. | ||
| - This decreases the deployment cost, since you only need to deploy the custom dApp code and specific dependencies. | ||
|
|
||
| ### Asset Hosting | ||
|
|
||
| For hosting large assets (such as images and videos) that your web app may require, you could leverage a [decentralized storage service](../../1.concepts/storage/decentralized-storage.md) to maintain a fully decentralized deployment. Some of these solutions are: | ||
| - [Arweave](https://arweave.org) | ||
| - [Crust](https://crust.network) | ||
| - [IPFS](https://ipfs.tech) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters