This template allows you to create a front-end application that connects to a Substrate node back-end with minimal configuration. To learn about Substrate itself, visit the Substrate Documentation.
The template is built with Create React App and Polkadot js API. Familiarity with these tools will be helpful, but the template strives to be self-explanatory.
The codebase is installed using git and yarn. This tutorial assumes you have installed yarn globally prior to installing it within the subdirectories. For the most recent version and how to install yarn, please refer to Yarn documentation and installation guides.
# Clone the repository
git clone https://github.com/substrate-developer-hub/substrate-front-end-template.git
cd substrate-front-end-template
yarn install
You can start the template in development mode to connect to a locally running node
yarn start
You can also build the app in production mode,
yarn build
and open build/index.html
in your favorite browser.
Connecting to Polkadot:
https://substrate-developer-hub.github.io/substrate-front-end-template?rpc=wss://rpc.polkadot.io
Connecting to your local Substrate node (Chrome and Firefox only):
https://substrate-developer-hub.github.io/substrate-front-end-template?rpc=ws://localhost:9944
Connecting to the development Substrate node wss://dev-node.substrate.dev
:
https://substrate-developer-hub.github.io/substrate-front-end-template
The template's configuration is stored in the src/config
directory, with
common.json
being loaded first, then the environment-specific json file,
and finally environment variables, with precedence.
development.json
affects the development environmenttest.json
affects the test environment, triggered inyarn test
command.production.json
affects the production environment, triggered inyarn build
command.
Some environment variables are read and integrated in the template config
object,
including:
REACT_APP_PROVIDER_SOCKET
overridingconfig[PROVIDER_SOCKET]
More on React environment variables.
When writing and deploying your own front end, you should configure:
PROVIDER_SOCKET
insrc/config/production.json
pointing to your own deployed node.
There are two ways to specify it:
- With
PROVIDER_SOCKET
in{common, development, production}.json
. - With
rpc=<ws or wss connection>
query parameter after the URL. This overrides the above setting.
The custom hook useSubstrate()
provides access to the Polkadot js API and thus the
keyring and the blockchain itself. Specifically it exposes this API.
{
setCurrentAccount: func(acct) {...}
state: {
socket,
keyring,
keyringState,
api,
apiState,
currentAccount
}
}
socket
- The remote provider socket it is connecting to.keyring
- A keyring of accounts available to the user.keyringState
- One of"READY"
or"ERROR"
states.keyring
is valid only whenkeyringState === "READY"
.api
- The remote api to the connected node.apiState
- One of"CONNECTING"
,"READY"
, or"ERROR"
states.api
is valid only whenapiState === "READY"
.currentAccount
- The current selected account pair in the application context.setCurrentAccount
- Function to update thecurrentAccount
value in the application context.
If you are only interested in reading the state
, there is a shorthand useSubstrateState()
just to retrieve the state.
The TxButton handles basic query and transaction requests to the connected node. You can reuse this component for a wide variety of queries and transactions. See src/Transfer.js for a transaction example and src/Balances.js for a query example.
The Account Selector provides the user with a unified way to select their account from a keyring. If the Balances module is installed in the runtime, it also displays the user's token balance. It is included in the template already.
-
Polkadot-js API and related crypto libraries depend on
BigInt
that is only supported by modern browsers. To ensure that react-scripts properly transpile your webapp code, update thepackage.json
file:{ "browserslist": { "production": [ ">0.2%", "not ie <= 99", "not android <= 4.4.4", "not dead", "not op_mini all" ] } }
Refer to this doc page.