Version: Current

Flow App Quickstart

Last Updated: January 11th 2022

Note: This page will walk you through a very bare bones project to get started building a web3 dapp using the Flow Client Library (FCL). If you are looking for a clonable repo, check out the scaffolds availabe in the Flow CLI.

Video Walkthrough

Below is a video walkthrough covering the contents of this tutorial. You are welcome to watch or skip the video walkthrough depending on your style of learning.

Before You Start

Make sure you have Flow CLI installed. If you don't, follow the installation instructions.

Introduction

FCL-JS is the easiest way to start building decentralized applications. FCL (aka Flow Client Library) wraps much of the logic you'd have to write yourself on other blockchains. Follow this quick start and you'll have a solid overview of how to build a shippable dapp on Flow.

We're going to make an assumption that you know or understand React; however, the concepts should be easy to understand and transfer to another framework. While this tutorial will make use of Cadence (Flow's smart contract language), you do not need to know it. Instead, we recommend later diving into learning the Cadence language once you've gotten the core FCL concepts down.

In this tutorial, we are going to interact with an existing smart contract on Flow's testnet known as the Profile Contract. Using this contract, we will create a new profile and edit the profile information, both via a wallet. In order to do this, the FCL concepts we'll cover are:

Installation
Configuration
Authentication
Querying the Blockchain
Initializing an Account
Mutating the Blockchain

And if you ever have any questions we're always happy to help on Discord. There are also links at the end of this article for diving deeper into building on Flow.

Installation

The first step is to generate a React app using Next.js and create-next-app. From your terminal, run the following:

npx create-next-app@latest flow-app
cd flow-app

Configuration

Setting up Flow

Then, using the Flow CLI, create a new flow.json file in the root of your app. This file will contain the Flow configuration for your project.

flow init

We don't recommend keeping private keys in your flow.json, so for good practice let's move our private key to a emulator.key file in the root of our project and point to it using the key/location pattern used by Flow CLI. This file will be ignored by git, so it won't be committed to your repository.

We won't be using emulator and running contracts locally in this quickstart, but FCL will complain if it finds private keys in your flow.json file.

Your flow.json file should look like this:

{
	"networks": {
		"emulator": "127.0.0.1:3569",
		"mainnet": "access.mainnet.nodes.onflow.org:9000",
		"sandboxnet": "access.sandboxnet.nodes.onflow.org:9000",
		"testnet": "access.devnet.nodes.onflow.org:9000"
	},
	"accounts": {
		"emulator-account": {
			"address": "f8d6e0586b0a20c7",
			"key": {
				"type": "file",
				"location": "./emulator.key"
			}
		}
	}
}

Configuring FCL

Next, install FCL so we can use it in our app.

npm install @onflow/fcl --save

Now run the app using the following command in your terminal.

npm run dev

Now that your app is running, you can configure FCL. Within the main project directory, create a folder called flow and create a file called config.js. This file will contain configuration information for FCL, such as what Access Node and wallet discovery endpoint to use (e.g. testnet or a local emulator). Add the following contents to the file:

Note: These values are required to use FCL with your app.

Create file: ./flow/config.js

import { config } from "@onflow/fcl";
config({
  "accessNode.api": "https://rest-testnet.onflow.org", // Mainnet: "https://rest-mainnet.onflow.org"
  "discovery.wallet": "https://fcl-discovery.onflow.org/testnet/authn" // Mainnet: "https://fcl-discovery.onflow.org/authn"
})

📣 Tip: It's recommend to replace these values with environment variables for easy deployments across different environments like development/production or Testnet/Mainnet.

The accessNode.api key specifies the address of a Flow access node. Flow provides these, but in the future access to Flow may be provided by other 3rd parties, through their own access nodes. discovery.wallet is an address that points to a service that lists FCL compatible wallets. Flow's FCL Discovery service is a service that FCL wallet providers can be added to, and be made 'discoverable' to any application that uses the discovery.wallet endpoint.

Learn more about configuring Discovery or setting configuration values.

The main page for Next.js apps is located in pages/index.js. So let's finish configuring our dapp by going in the pages/ directory and importing the config file into the top of our index.js file. We'll then swap out the default component in index.js to look like this:

Replace file: ./pages/index.js

import "../flow/config";
import Head from 'next/head'
export default function Home() {
  return (
    <div>
      <Head>
        <title>FCL Quickstart with NextJS</title>
        <meta name="description" content="My first web3 app on Flow!" />
        <link rel="icon" href="/favicon.png" />
      </Head>
      <main>
        Hello World
      </main>
    </div>
  )
}

Now we're ready to start talking to Flow!

Authentication

To authenticate a user, all an app has to do is call fcl.logIn(). Sign up and unauthenticate are all also as simple as fcl.signUp() and fcl.unauthenticate(). Once authenticated, FCL sets an object called fcl.currentUser which exposes methods for watching changes in user data, signing transactions, and more. For more information on the currentUser, read more here.

Let's add in a few buttons for sign up/login and also subscribe to changes on the currentUser. When the user is updated (which it will be after authentication), we'll set the user state in our component to reflect this. To demonstrate user authenticated sessions, we'll conditionally render a component based on if the user is or is not logged in.

This is what your file should look like now:

Replace file: ./pages/index.js

import Head from 'next/head'
import "../flow/config";
import { useState, useEffect } from "react";
import * as fcl from "@onflow/fcl";
export default function Home() {
  const [user, setUser] = useState({loggedIn: null})
  useEffect(() => fcl.currentUser.subscribe(setUser), [])
  const AuthedState = () => {
    return (
      <div>
        <div>Address: {user?.addr ?? "No Address"}</div>
        <button onClick={fcl.unauthenticate}>Log Out</button>
      </div>
    )
  }
  const UnauthenticatedState = () => {
    return (
      <div>
        <button onClick={fcl.logIn}>Log In</button>
        <button onClick={fcl.signUp}>Sign Up</button>
      </div>
    )
  }
  return (
    <div>
      <Head>
        <title>FCL Quickstart with NextJS</title>
        <meta name="description" content="My first web3 app on Flow!" />
        <link rel="icon" href="/favicon.png" />
      </Head>
      <h1>Flow App</h1>
      {user.loggedIn
        ? <AuthedState />
        : <UnauthenticatedState />
      }
    </div>
  );
}

You should now be able to log in or sign up a user and unauthenticate them. Upon logging in or signing up your users will see a popup where they can choose between wallet providers. Let's select the Blocto wallet for this example to create an account. Upon completing authentication, you'll see the component change and the user's wallet address appear on the screen if you've completed this properly.

Querying the Blockchain

One of the main things you'll often need to do when building a dapp is query the Flow blockchain and the smart contracts deployed on it for data. Since smart contracts will live on both Testnet and Mainnet, let's put the account address where the smart contract lives into the flow.json so FCL can pick it up. We are going to also use an alias for testnet.

If you want to see how to use local files for emulator and learn more about aliases, check out the flow.json documentation. For now, know that an alias lets us specify a contract address based on a specific network (e.g. testnet/mainnet).

Replace file: flow.json

{
	"contracts": {
		"Profile": {
			"aliases": {
				"testnet": "0xba1132bc08f82fe2"
			}
		}
	},
	"networks": {
		"emulator": "127.0.0.1:3569",
		"mainnet": "access.mainnet.nodes.onflow.org:9000",
		"sandboxnet": "access.sandboxnet.nodes.onflow.org:9000",
		"testnet": "access.devnet.nodes.onflow.org:9000"
	},
	"accounts": {
		"emulator-account": {
			"address": "f8d6e0586b0a20c7",
			"key": {
				"type": "file",
				"location": "./emulator.key"
			}
		}
	}
}

If you want to see the on chain smart contract we'll be speaking with next, you can view the Profile Contract source code but again for this tutorial it's not necessary you understand it.

First, lets query the contract to see what the user's profile name is.

A few things need to happen in order to do that:

We need to import the contract and pass it the user's account address as an argument.
Execute the script using fcl.query.
Set the result of the script to the app state in React so we can display the profile name in our browser.
Display "No Profile" if one was not found.

Take a look at the new code. We'll explain each new piece as we go. Remember, the cadence code is a separate language from JavaScript used to write smart contracts, so you don't need to spend too much time trying to understand it. (Of course, you're more than welcome to, if you want to!)

Replace file: ./pages/index.js

import Head from 'next/head'
import "../flow/config";
import { useState, useEffect } from "react";
import * as fcl from "@onflow/fcl";
export default function Home() {
  const [user, setUser] = useState({loggedIn: null})
  const [name, setName] = useState('') // NEW
  useEffect(() => fcl.currentUser.subscribe(setUser), [])
	// NEW
  const sendQuery = async () => {
    const profile = await fcl.query({
      cadence: `
        import Profile from 0xProfile
        pub fun main(address: Address): Profile.ReadOnly? {
          return Profile.read(address)
        }
      `,
      args: (arg, t) => [arg(user.addr, t.Address)]
    })
    setName(profile?.name ?? 'No Profile')
  }
  const AuthedState = () => {
    return (
      <div>
        <div>Address: {user?.addr ?? "No Address"}</div>
        <div>Profile Name: {name ?? "--"}</div> {/* NEW */}
        <button onClick={sendQuery}>Send Query</button> {/* NEW */}
        <button onClick={fcl.unauthenticate}>Log Out</button>
      </div>
    )
  }
  const UnauthenticatedState = () => {
    return (
      <div>
        <button onClick={fcl.logIn}>Log In</button>
        <button onClick={fcl.signUp}>Sign Up</button>
      </div>
    )
  }
  return (
    <div>
      <Head>
        <title>FCL Quickstart with NextJS</title>
        <meta name="description" content="My first web3 app on Flow!" />
        <link rel="icon" href="/favicon.png" />
      </Head>
      <h1>Flow App</h1>
      {user.loggedIn
        ? <AuthedState />
        : <UnauthenticatedState />
      }
    </div>
  );
}

A few things happened. In our AuthedState component, we added a button to send a query for the user's profile name and a div to display the result above it. The corresponding useState initialization can be seen at the top of the component.

The other thing we did is build out the actual query inside of sendQuery method. Let's take a look at it more closely:

await fcl.query({
  cadence: `
    import Profile from 0xProfile
    pub fun main(address: Address): Profile.ReadOnly? {
      return Profile.read(address)
    }
  `,
  args: (arg, t) => [arg(user.addr, t.Address)]
});

Inside the query you'll see we set two things: cadence and args. Cadence is Flow's smart contract language we mentioned. For this tutorial, when you look at it you just need to notice that it's importing the Profile contract from the account we named 0xProfile earlier in our config file, then also taking an account address, and reading it. That's it until you're ready to learn more Cadence.

In the args section, we are simply passing it our user's account address from the user we set in state after authentication and giving it a type of Address. For more possible types, see this reference.

Go ahead and click the "Send Query" button. You should see "No Profile." That's because we haven't initialized the account yet.

Initializing the Account

For the Profile contract to store a Profile in a user's account, it does so by initializing what is called a "resource." A resource is an ownable piece of data and functionality that can live in the user's account storage. This paradigm is known is as "resource-oriented-programming", a principle that is core to Cadence and differentiates its ownership model from other smart contract languages, read more here. Cadence makes it so that resources can only exist in one place at any time, they must be deliberately created, cannot be copied, and if desired, must be deliberately destroyed.

There's a lot more to resources in Cadence than we'll cover in this guide, so if you'd like to know more, check out this Cadence intro.

To do this resource initialization on an account, we're going to add another function called initAccount. Inside of that function, we're going to add some Cadence code which says, "Hey, does this account have a profile? If it doesn't, let's add one." We do that using something called a "transaction." Transactions occur when you want to change the state of the blockchain, in this case, some data in a resource, in a specific account. And there is a cost (transaction fee) in order to do that; unlike a query.

That's where we jump back into FCL code. Instead of query, we use mutate for transactions. And because there is a cost, we need to add a few fields that tell Flow who is proposing the transaction, who is authorizing it, who is paying for it, and how much they're willing to pay for it. Those fields — not surprisingly — are called: proposer, authorizer, payer, and limit. For more information on these signatory roles, check out this doc.

Let's take a look at what our account initialization function looks like:

const initAccount = async () => {
  const transactionId = await fcl.mutate({
    cadence: `
      import Profile from 0xProfile
      transaction {
        prepare(account: AuthAccount) {
          // Only initialize the account if it hasn't already been initialized
          if (!Profile.check(account.address)) {
            // This creates and stores the profile in the user's account
            account.save(<- Profile.new(), to: Profile.privatePath)
            // This creates the public capability that lets applications read the profile's info
            account.link<&Profile.Base{Profile.Public}>(Profile.publicPath, target: Profile.privatePath)
          }
        }
      }
    `,
    payer: fcl.authz,
    proposer: fcl.authz,
    authorizations: [fcl.authz],
    limit: 50
  })
  const transaction = await fcl.tx(transactionId).onceSealed()
  console.log(transaction)
}

You can see the new fields we talked about. You'll also notice fcl.authz. That's shorthand for "use the current user to authorize this transaction", (you could also write it as fcl.currentUser.authorization). If you want to learn more about transactions and signing transactions, you can view the docs here. For this example, we'll keep it simple with the user being each of these roles.

You'll also notice we are awaiting a response with our transaction data by using the syntax fcl.tx(transactionId).onceSealed(). This will return when the blockchain has sealed the transaction and it's complete in processing it and verifying it.

Now your index.js file should look like this (we also added a button for calling the initAccount function in the AuthedState):

Replace file: ./pages/index.js

import Head from 'next/head'
import "../flow/config";
import { useState, useEffect } from "react";
import * as fcl from "@onflow/fcl";
export default function Home() {
  const [user, setUser] = useState({loggedIn: null})
  const [name, setName] = useState('')
  useEffect(() => fcl.currentUser.subscribe(setUser), [])
  const sendQuery = async () => {
    const profile = await fcl.query({
      cadence: `
        import Profile from 0xProfile
        pub fun main(address: Address): Profile.ReadOnly? {
          return Profile.read(address)
        }
      `,
      args: (arg, t) => [arg(user.addr, t.Address)]
    })
    setName(profile?.name ?? 'No Profile')
  }
  // NEW
  const initAccount = async () => {
    const transactionId = await fcl.mutate({
      cadence: `
        import Profile from 0xProfile
        transaction {
          prepare(account: AuthAccount) {
            // Only initialize the account if it hasn't already been initialized
            if (!Profile.check(account.address)) {
              // This creates and stores the profile in the user's account
              account.save(<- Profile.new(), to: Profile.privatePath)
              // This creates the public capability that lets applications read the profile's info
              account.link<&Profile.Base{Profile.Public}>(Profile.publicPath, target: Profile.privatePath)
            }
          }
        }
      `,
      payer: fcl.authz,
      proposer: fcl.authz,
      authorizations: [fcl.authz],
      limit: 50
    })
    const transaction = await fcl.tx(transactionId).onceSealed()
    console.log(transaction)
  }
  const AuthedState = () => {
    return (
      <div>
        <div>Address: {user?.addr ?? "No Address"}</div>
        <div>Profile Name: {name ?? "--"}</div>
        <button onClick={sendQuery}>Send Query</button>
        <button onClick={initAccount}>Init Account</button> {/* NEW */}
        <button onClick={fcl.unauthenticate}>Log Out</button>
      </div>
    )
  }
  const UnauthenticatedState = () => {
    return (
      <div>
        <button onClick={fcl.logIn}>Log In</button>
        <button onClick={fcl.signUp}>Sign Up</button>
      </div>
    )
  }
  return (
    <div>
      <Head>
        <title>FCL Quickstart with NextJS</title>
        <meta name="description" content="My first web3 app on Flow!" />
        <link rel="icon" href="/favicon.png" />
      </Head>
      <h1>Flow App</h1>
      {user.loggedIn
        ? <AuthedState />
        : <UnauthenticatedState />
      }
    </div>
  )
}

Press the "Init Account" button you should see the wallet ask you to approve a transaction. After approving, you will see a transaction response appear in your console (make sure to have that open). It may take a few moments. With the transaction result printed, you can use the transactionId to look up the details of the transaction using a block explorer.

Mutating the Blockchain

Now that we have the profile initialized, we are going to want to mutate it some more. In this example, we'll use the same smart contract provided to change the profile name.

To do that, we are going to write another transaction that adds some Cadence code which lets us set the name. Everything else looks the same in the following code except for one thing: we'll subscribe to the status changes instead of waiting for it to be sealed after the mutate function returns.

It looks like this:

const executeTransaction = async () => {
  const transactionId = await fcl.mutate({
    cadence: `
      import Profile from 0xProfile
      transaction(name: String) {
        prepare(account: AuthAccount) {
          account
            .borrow<&Profile.Base{Profile.Owner}>(from: Profile.privatePath)!
            .setName(name)
        }
      }
    `,
    args: (arg, t) => [arg("Flow Developer", t.String)],
    payer: fcl.authz,
    proposer: fcl.authz,
    authorizations: [fcl.authz],
    limit: 50
  })
  fcl.tx(transactionId).subscribe(res => setTransactionStatus(res.status))
}

Here you can see our argument is "Flow Developer" and at the bottom we've called the subscribe method instead of onceSealed.

Let's see how that works inside our whole index.js file. But, let's also set the statuses to our React component's state so we can see on screen what state we're in.

Replace file: ./pages/index.js

import Head from 'next/head'
import "../flow/config";
import { useState, useEffect } from "react";
import * as fcl from "@onflow/fcl";
export default function Home() {
  const [user, setUser] = useState({loggedIn: null})
  const [name, setName] = useState('')
  const [transactionStatus, setTransactionStatus] = useState(null) // NEW
  useEffect(() => fcl.currentUser.subscribe(setUser), [])
  const sendQuery = async () => {
    const profile = await fcl.query({
      cadence: `
        import Profile from 0xProfile
        pub fun main(address: Address): Profile.ReadOnly? {
          return Profile.read(address)
        }
      `,
      args: (arg, t) => [arg(user.addr, t.Address)]
    })
    setName(profile?.name ?? 'No Profile')
  }
  const initAccount = async () => {
    const transactionId = await fcl.mutate({
      cadence: `
        import Profile from 0xProfile
        transaction {
          prepare(account: AuthAccount) {
            // Only initialize the account if it hasn't already been initialized
            if (!Profile.check(account.address)) {
              // This creates and stores the profile in the user's account
              account.save(<- Profile.new(), to: Profile.privatePath)
              // This creates the public capability that lets applications read the profile's info
              account.link<&Profile.Base{Profile.Public}>(Profile.publicPath, target: Profile.privatePath)
            }
          }
        }
      `,
      payer: fcl.authz,
      proposer: fcl.authz,
      authorizations: [fcl.authz],
      limit: 50
    })
    const transaction = await fcl.tx(transactionId).onceSealed()
    console.log(transaction)
  }
  // NEW
  const executeTransaction = async () => {
    const transactionId = await fcl.mutate({
      cadence: `
        import Profile from 0xProfile
        transaction(name: String) {
          prepare(account: AuthAccount) {
            account
              .borrow<&Profile.Base{Profile.Owner}>(from: Profile.privatePath)!
              .setName(name)
          }
        }
      `,
      args: (arg, t) => [arg("Flow Developer!", t.String)],
      payer: fcl.authz,
      proposer: fcl.authz,
      authorizations: [fcl.authz],
      limit: 50
    })
    fcl.tx(transactionId).subscribe(res => setTransactionStatus(res.status))
  }
  const AuthedState = () => {
    return (
      <div>
        <div>Address: {user?.addr ?? "No Address"}</div>
        <div>Profile Name: {name ?? "--"}</div>
        <div>Transaction Status: {transactionStatus ?? "--"}</div> {/* NEW */}
        <button onClick={sendQuery}>Send Query</button>
        <button onClick={initAccount}>Init Account</button>
        <button onClick={executeTransaction}>Execute Transaction</button> {/* NEW */}
        <button onClick={fcl.unauthenticate}>Log Out</button>
      </div>
    )
  }
  const UnauthenticatedState = () => {
    return (
      <div>
        <button onClick={fcl.logIn}>Log In</button>
        <button onClick={fcl.signUp}>Sign Up</button>
      </div>
    )
  }
  return (
    <div>
      <Head>
        <title>FCL Quickstart with NextJS</title>
        <meta name="description" content="My first web3 app on Flow!" />
        <link rel="icon" href="/favicon.png" />
      </Head>
      <h1>Flow App</h1>
      {user.loggedIn
        ? <AuthedState />
        : <UnauthenticatedState />
      }
    </div>
  )
}

Now if you click the "Execute Transaction" button you'll see the statuses update next to "Transaction Status." When you see "4" that means it's sealed! Status code meanings can be found here. If you query the account profile again, "Profile Name:" should now display "Flow Developer".

That's it! You now have a shippable Flow dapp that can auth, query, init accounts, and mutate the chain. This is just the beginning. There is so much more to know. We have a lot more resources to help you build. To dive deeper, here are a few good places for taking the next steps:

Cadence

FCL Scaffolds

Full Stack NFT Marketplace Example

More FCL

Other

Flow Developer Onboarding Guide

Flow App Quickstart

Video Walkthrough​

Before You Start​

Introduction​

Installation​

Configuration​

Setting up Flow​

Configuring FCL​

Authentication​

Querying the Blockchain​

Initializing the Account​

Mutating the Blockchain​

Video Walkthrough

Before You Start

Introduction

Installation

Configuration

Setting up Flow

Configuring FCL

Authentication

Querying the Blockchain

Initializing the Account

Mutating the Blockchain