# Learn to Integrate Keplr
Build applications that interact with the Keplr browser extension.
In this section, you will learn more about:
- Detecting Keplr.
- Getting chain information.
- Working with the user interaction flow.
CosmJS allows you to connect with Keplr (opens new window), the widely used browser extension, to manage your private keys. In a previous section you used the command-line and CosmJS to issue commands to the Cosmos Hub Testnet. In this tutorial, you are working on a browser application that interacts with the Keplr extension.
You will again connect to the Cosmos Hub Testnet. Optionally, connect to your locally running Cosmos blockchain using
simapp as explained before.
To keep the focus on CosmJS and Keplr, you are going to use ready-made pages created by the Next.js framework. Do not worry if you routinely use another framework, the CosmJS-specific code in this tutorial can be applied similarly in Angular, Vue, and other frameworks.
# Creating your simple Next.js project
In your project folder create the ready-made Next.js app, which automatically places it in a subfolder for you. This follows the docs (opens new window):
Which guides you with:
This created a new
cosmjs-keplr folder, so open it. There you can find a
/pages folder, which contains an
index.tsx. That's your first page.
Run it, in the
You should see the result, a welcome page with links, in your browser by visiting http://localhost:3000 (opens new window). Next.js uses React (opens new window) under the hood.
# HTML elements
The goal of the exercise is to find token balances, yours and the faucet's, and then send some tokens back to the faucet. Before introducing any CosmJS, you can already create a React component that includes the basic user interface that you need. By convention, create a
/components folder and then copy the following code inside a new file called
The properties of
FaucetSender.tsx only contain the things it knows at build time. It keeps a state, and this state is either updated by the user or after a fetch. It reuses a default style you can find in
The component is still unused. You do not need the default page that comes with create-next-app, so you can replace the contents of
index.tsx with the following code that imports the new component:
The faucet address was found in the previous section, as well as the RPC endpoint that connects to the Cosmos Hub Testnet.
npm run dev picks up the changes, you should see that your page has changed to what you created. In particular, it alerts you with "TODO" when you click on the button.
Your page is not very useful yet, make it more so.
# Installing CosmJS
Now that you have a working Next.js project and ready page, it is time to add the necessary CosmJS elements to the project:
# Displaying information without user input
When building a user interface, it is good practice to not ask your user's address until it becomes necessary (e.g. if they click a relevant button). You should start by showing information that is knowable without user input. In this case, this is the token
denom (denomination) and the faucet's balance. Add the following function that gets the balance from the faucet and place it above the
onToSendChanged function inside
Note that it only cares about the first coin type stored in
balances: this is to keep the exercise simple, but there could be multiple coins in that array of balances. It extracts the
denom, which is then displayed to the user as the unit to transfer. Add the denom that in the constructor as well so that it runs on load via another specific function:
The call to
setTimeout is so that
init is not launched on the same pass as the constructor.
run dev picks the changes, you should see that your page starts showing the relevant information.
Now, add elements that handle your user's information.
# Getting testnet tokens
Refer to the previous section on how to get Cosmos Hub Testnet tokens. This time you should use your Keplr address. If you have not set up one yet, do so now. Your Cosmos Hub Testnet address is the same one that Keplr shows you for the Cosmos Hub mainnet.
# Detecting Keplr
Following Keplr's documentation (opens new window), it is time to add a function to see if Keplr is installed on the browser. For convenience and type hinting, install the Typescript Keplr types from within the folder of your project:
After this package is installed, inform Typescript that
window may have a
.keplr field with the help of this helper (opens new window), by adding it below your imports to
Detecting Keplr can be done at any time, but to keep the number of functions low for this exercise do it in
onSendClicked. You want to avoid detecting Keplr on page load if not absolutely necessary. This is generally considered bad user experience for users who might just want to browse your page and not interact with it. Replace the
onSendClicked with the following:
Hopefully, when you click on the button it does not show an alert. It does not do anything else either. As an optional confirmation, if you disable Keplr from Chrome's extension manager, when you click the button the page tells you to install it.
# Prepare Keplr
Keplr is now detected. By default, Keplr lets its users only connect to the blockchains it knows about. Unfortunately, the Cosmos Hub Testnet is not one of them, but there is a feature where you can instruct it to handle any Cosmos blockchain, provided you give its parameters. Here is an example (opens new window). In the case of Cosmos Hub Testnet, these parameters are available, as mentioned on the testnet page (opens new window). Add a new function for them as shown in the expandable box:
You need to add another import from the
@keplr-wallet package so that your script understands what
Note that it mentions the
chainId: "theta-testnet-001". In effect, this adds the Cosmos Hub Testnet to Keplr's registry of blockchains, under the label
theta-testnet-001. Whenever you want to prompt the user to add the Cosmos Hub Testnet to Keplr, add the line:
This needs to be done once, which in this case is in the
onSendClicked function after having detected Keplr, but repeating the line elsewhere is generally not a problem.
Keplr is now detected and prepared. Now try to do something useful with the user's information.
# Your address and balance
onSendClicked, similar to the previous section, you can:
- Prepare Keplr, with
- Get the signer for your user's accounts, with
- Create your signing client.
- Get the address and balance of your user's first account.
- Send the requested coins to the faucet.
- Inform and update.
In practice, the code for
onSendClicked looks like this:
Keplr is only tasked with signing transactions. The transactions are broadcast with the RPC endpoint of your choice.
Now run the full script. In the refreshed page, enter an amount of
uatom (for example
1000000) and click Send to faucet. A number of events happen:
- Keplr asks for confirmation that you agree to add the testnet network. It does not install any network without your approval, as that would be a security risk. It asks this only the first time you add a given network, which is why doing it in
- Keplr asks whether you agree to share your account information, because this involves a potential security risk. Again, it asks this only once per web page + network combination.
- Your address and balance fields are updated and visible.
- Keplr asks whether you agree to sign the transaction, a very important action that requires approval every time.
After this is done, your balance updates again, and in the browser console you see the transaction result.
If you want to double check if you got everything right, you can find the full component's code in the expandable box below:
# With a locally running chain
What if you wanted to experiment with your own chain while in development?
Keplr does not know about locally running chains by default. As you did with Cosmos Hub Testnet, you must inform Keplr about your chain: change
ChainInfo to match the information about your chain, and change
rpcUrl so that it points to your local port.
If you would like to get started on integrating Keplr into your own checkers game, you can go straight to the related exercise in CosmJS for Your Chain to start from scratch.
More specifically, you can jump to:
- Integrate CosmJS and Keplr, for a more elaborate integration between Keplr, CosmJS, custom messages, and a pre-existing Checkers GUI.
To summarize, this section has explored:
- How to use CosmJS to connect with Keplr, a browser extension widely used to manage private keys, to find your token balance and that of the faucet and then send some tokens back to the faucet.
- How to create a simple app in the Next.js framework for the purposes of performing the exercise, though the CosmJS-specific code is also applicable to Angular, Vue, and other frameworks.
- Best practices regarding when and when not to ask for your user's address, such as limiting your user interface to only showing information that is knowable without user input until making a request is absolutely necessary.
- How to add a function to detect whether or not Keplr is installed on the browser, also minimizing the occasions when information requests are made in line with best practices.
- How to prepare Keplr to handle any Cosmos blockchain (or for use with locally running chains, such as during development) by providing it with the necessary parameters for a specific chain, before experimenting with accessing useful information from the chain.