Skip to content

Commit

Permalink
Merge pull request #406 from onflow/nialexsan/quickstart-fixes
Browse files Browse the repository at this point in the history 
quickstart fixes
  • Loading branch information
@nialexsan
nialexsan authored Oct 5, 2023
2 parents 73d7e08 + 7dfeb44 commit d8685fa
Show file tree
Hide file tree
Showing 9 changed files with 72 additions and 62 deletions.
10 changes: 5 additions & 5 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Updating existing content is a seamless process:

<Callout type="note" title="Here is what it looks like.">
![edit page](./static/images/contributing/edit-light.png#gh-light-mode-only)
![edit page](./static/images/contributing//edit-dark.png#gh-dark-mode-only)
![edit page](./static/images/contributing/edit-dark.png#gh-dark-mode-only)
</Callout>

1. Clicking the link will take you directly to the source code of the page you're viewing.
Expand Down Expand Up @@ -142,8 +142,8 @@ The `index` page should only include information that is available elsewhere wit
Using `DocCardList` improves the layout of the index page:

<Callout type="note" title="Example">
![edit page](./static/images/contributing//doc-card-list-light.png#gh-light-mode-only)
![edit page](./static/images/contributing//doc-card-list-dark.png#gh-dark-mode-only)
![edit page](./static/images/contributing/doc-card-list-light.png#gh-light-mode-only)
![edit page](./static/images/contributing/doc-card-list-dark.png#gh-dark-mode-only)
</Callout>

On the most pages you can use just `<DocCardList />` component imported from `'@theme/DocCardList'`
Expand Down Expand Up @@ -259,7 +259,7 @@ Currently, the Flow Docs validates content using the following conditions:

Here is an example of check run output with successful validation.

![successful-checks](./static/images/contributing//successful-checks.png)
![successful-checks](./static/images/contributing/successful-checks.png)

### Dead Links Checks

Expand All @@ -273,6 +273,6 @@ Previews are generated against the **PR branch of the Flow Docs**, to ensure you

Here is an example of preview output for changed documents in a PR

![preview-link](./static/images/contributing//preview-link.png)
![preview-link](./static/images/contributing/preview-link.png)

When you merge updates to documents in your PR, previews will deployed with a few minutes delay.
2 changes: 1 addition & 1 deletion docs/build/getting-started/quickstarts/explore-more.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,5 @@ sidebar_position: 999

Below are some additional resources to help you get started with Flow:

- [Guides](../../../guides/flow-app-quickstart.mdx) - Longer form guides to help you get started with Flow
- [Guides](../../../guides/flow-app-quickstart.md) - Longer form guides to help you get started with Flow
- [Emerald Academy](https://academy.ecdao.org/en/quickstarts) - Quickstart Tutorials for Flow created by the [Emerald City DAO](https://ecdao.org/)
2 changes: 1 addition & 1 deletion docs/build/getting-started/quickstarts/fcl-quickstart.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -138,4 +138,4 @@ You just built an app on Flow!

## Mutating Chain State and More

For a deeper dive into writing an FCL app, such as how to change the chain state with FCL, check out [this guide](../../../guides/flow-app-quickstart.mdx) or the [FCL documentation](../../../tools/clients/fcl-js/index.md).
For a deeper dive into writing an FCL app, such as how to change the chain state with FCL, check out [this guide](../../../guides/flow-app-quickstart.md) or the [FCL documentation](../../../tools/clients/fcl-js/index.md).
101 changes: 56 additions & 45 deletions docs/guides/flow-app-quickstart.mdx → docs/guides/flow-app-quickstart.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@ sidebar_custom_props:
icon: 🏗️
---


# Flow App Quickstart

---
Expand All @@ -34,39 +33,32 @@ This guide assumes a good understanding of React. The concepts are easy to under

- [Installation](#installation)
- [Configuration](#configuration)
- [Authentication](#authentication)
- [Querying the Blockchain](#querying-the-blockchain)
- [Initializing an Account](#initializing-an-account)
- [Mutating the Blockchain](#mutating-the-blockchain)
- [Authenticate a user](#authenticate-a-user)
- [Deploy contracts](#deploy-contracts)
- [Query the Blockchain](#query-the-blockchain)
- [Mutate the Blockchain](#mutate-the-blockchain)

For more help, [Discord](https://discord.gg/flow). See links at the end of this article for diving deeper into building on Flow.

## Installation

Make sure you have Flow CLI installed. [installation instructions](../tools/flow-cli/install.md).

The first step is to generate a React app using Next.js and [create-next-app](https://nextjs.org/docs/api-reference/create-next-app). From your terminal, run the following:

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

## Configuration

### Setting up Flow

Using the Flow CLI scaffold, create a basic hello world web project. This will create a new `flow.json` file in the hello-world folder. This file will contain the Flow configuration for your project.
Using the Flow CLI scaffold, create a basic hello world web project with `Web Scaffolds` -> `[5] FCL Web Dapp`. This will create a new `flow.json` file in the `hello-world` folder. This file will contain the Flow configuration for your project.

```sh
flow setup hello-world --scaffold
# select scaffold 5
cd hello-world
npm install
# run the app in a later step
flow setup hello-world --scaffold
# select scaffold 5
cd hello-world
npm install
# run the app in a later step
```

We don't recommend keeping private keys in your `flow.json`, notice that Flow CLI already moved the emulator private key to a `emulator.key` file and point to it using the [key/location pattern](../tools/flow-cli/flow.json/security.md#private-account-configuration-file). This file should be added to your .gitignore file, so it won't be committed to your repository.
We don't recommend keeping private keys in your `flow.json`, notice that Flow CLI already moved the emulator private key to a `emulator.key` file and point to it using the [key/location pattern](../tools/flow-cli/flow.json/security.md#private-account-configuration-file). This file should be added to your `.gitignore` file, 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.

Expand All @@ -93,44 +85,64 @@ Your `flow.json` file should look like this:
```

<Callout type="info">
The flow.json file is used to keep track of deployed contracts and accounts. [More Information](../tools/clients/fcl-js/api#using-flowjson)
The `flow.json` file is used to keep track of deployed contracts and accounts. [More Information](../tools/clients/fcl-js/api#using-flowjson)
</Callout>


### Configuring FCL

Next, notice @onflow/fcl has been added to the package.json and the web application is read to be run.
Next, notice `@onflow/fcl` has been added to the `package.json` and the web application is ready to be run.

<Callout type="info">
There are a lot of benefits to getting familiar with existing Flow CLI scaffolds. For example the hello-world scaffold already has fcl configuration settings to run on local emulator.
There are a lot of benefits to getting familiar with existing Flow CLI scaffolds. For example the `hello-world` scaffold already has fcl configuration settings to run on local emulator.
</Callout>


The `hello-world` web application comes with convenience npm commands to facilitate a quick start. The following command will preform:
1. Start emulator
2. Start dev wallet
3. Start web app
1. Start emulator
2. Start dev wallet
3. Start web app

<Callout type="info">
Emulator is a local blockchain [More Information](../tools/emulator). Emulator has all the features as testnet and mainnet blockchains
Emulator is a local blockchain [More Information](../tools/emulator/index.md). Emulator has all the features as testnet and mainnet blockchains
</Callout>

```sh
npm run dev:local
```

Now that your app is running. FYI, fcl loads the configuration in `config/fcl.ts` This file contains configuration information for FCL, such as what Access Node and wallet discovery endpoint and which network to use (e.g. testnet or a local emulator).
Now that your app is running. FCL loads the configuration in `config/fcl.ts` This file contains configuration information for FCL, such as what Access Node and wallet discovery endpoint and which network to use (e.g. testnet or a local emulator).

The `accessNode.api` key specifies the address of a Flow access node. There are publically available access nodes, but have to rate limit. Alternatively, applications might want to run an Observer node [Run a Node](../references/run-and-secure/node-operation/observer-node.mdx).
`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.
- `accessNode.api` key specifies the address of a Flow access node. There are publically available access nodes, but have to rate limit. Alternatively, applications might want to run an Observer node [Run a Node](../references/run-and-secure/node-operation/observer-node.mdx).
- `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.

Also, notice that package.json uses `NEXT_PUBLIC_FLOW_NETWORK=local` for `dev` command, this is used to set the network in `config/fcl.ts`.
Also, notice that `package.json` uses `NEXT_PUBLIC_FLOW_NETWORK=local` for `dev` command, this is used to set the network in `config/fcl.ts`.
<Callout type="info">
Learn more about [configuring Discovery](../tools/clients/fcl-js/discovery.mdx) or [setting configuration values](../tools/clients/fcl-js/api.md#setting-configuration-values).
</Callout>

The main Next.js app component is located in `pages/_app.tsx`. It should import the config file `config/fcl.ts` already and should look like this:

```jsx
import '../styles/globals.css'
import DefaultLayout from '../layouts/DefaultLayout'

// Import FCL config
import '../config/fcl'

function MyApp({ Component, pageProps }) {
return (
<DefaultLayout>
<Component {...pageProps} />
</DefaultLayout>
)
}

The main page for Next.js apps is located in `pages/index.js`. So let's finish configuring our app 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:
export default MyApp

```

The main page for the Next.js app is located in `pages/index.tsx`. It should contain some basic UI and should look like this:

```jsx
import Head from 'next/head'
Expand Down Expand Up @@ -169,25 +181,24 @@ export default function Home() {
)
}


```

Now we're ready to start talking to Flow!
<Callout type="warning">
The web app will run but there are no contracts deployed to local emulator. This is a step in `Querying the Blockchain` section.
The web app will run, but there are no contracts deployed to local emulator. This is a step in [Query the Blockchain](#query-the-blockchain) section.
</Callout>

## Authenticating a User
## Authenticate a User

![User Login](./user-login-hello-world.gif)

Note: in above code `useCurrentUser` is used to determine if there is a user logged in.
Note: in the code above `useCurrentUser` is used to determine if there is a logged in user.

There are two methods to allow the user to login. `fcl.logIn()` or `fcl.authenticate()` [More Information on, authenticate](../tools/clients/fcl-js/api#authenticate)

In `components/Navbar.tsx` a button wires up the authentication method `fcl.authenticate()`. It is used to bring up the list of supported wallets. See below

Once authenticated, FCL has a hook `const user = useCurrentUser()` to get the user data, when user is signed in `loggedIn` is true. For more information on the `currentUser`, read more [here](../tools/clients/fcl-js/api.md#current-user).
Once authenticated, FCL uses a hook `const user = useCurrentUser()` to get the user data, when user is signed in `user.loggedIn` flag is `true`. For more information on the `currentUser`, read more [here](../tools/clients/fcl-js/api.md#current-user).

```jsx
import Head from 'next/head'
Expand Down Expand Up @@ -226,21 +237,21 @@ export default function Navbar() {

```
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. Choose the `dev wallet` to use the same account that deployed the `HelloWorld` contract, this is needed for mutation. 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.
You should now be able to log in or sign up users and unauthenticate them. Upon logging in or signing up your users will see a popup where they can choose between wallet providers. Choose the `dev wallet` to use the same account that deployed the `HelloWorld` contract, this is needed for mutation. 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.
<Callout type="info">
More on wallets, [Lilico wallet](https://lilico.app/) is a Flow wallet.
More on wallets, [Flow Core wallet](https://core.flow.com/) is a Reference Flow wallet.
</Callout>
## Deploying contracts
## Deploy contracts
Hello World scaffold does come with a Cadence contract. You will notice `HelloWorld.cdc` has been deployed when running `npm run dev:local`. Look at hello-world package.json to see the commands that get run, `flow dev` deploys contracts.
Hello World scaffold does come with a Cadence contract. You will notice `HelloWorld.cdc` has been deployed when running `npm run dev:local`. Look at hello-world `package.json` to see the commands that get run, `flow dev` deploys contracts to the emulator.
In the `flow.json` make sure the emulator endpoint is correct. Look at the terminal the emulator is running,
![Emulator Output](./emulator-output.png)
1. Make sure the emulator is using the same port as `gRPC` and
2. Configure `deployment` to add mapping of contract to account.
2. The `deployment` section of `flow.json` should look something like this:
```json
...
"networks": {
Expand Down Expand Up @@ -293,6 +304,8 @@ Verify that `flow.json` updates with HelloWorld contract information, `contracts
}
```
For more information on deployments check [Flow CLI](../tools/flow-cli/flow.json/manage-configuration.md) documentation
## Query the Blockchain
Now that all pieces are in place. UI can query `HelloWorld` contract.
Expand Down Expand Up @@ -326,14 +339,14 @@ In `components/Container.tsx` file, `fcl.query` is used to set the Cadence scrip
It is that simple!
## Mutating the Blockchain
## Mutate the Blockchain
Update the `HelloWorld` contract greeting. Notice that Greeting gets changed when the transaction gets processed.
![Update contract](./hello-world-update-contract.gif)
In `components/Container.tsx` file, the `mutateGreeting` method `fcl.mutate` sends UpdateHelloWorld cadence which triggers a transaction that the user signs.
In `components/Container.tsx` file, the `mutateGreeting` method `fcl.mutate` sends `UpdateHelloWorld` cadence which triggers a transaction that the user signs.
```javascript
const mutateGreeting = async (event) => {
Expand All @@ -353,8 +366,6 @@ In `components/Container.tsx` file, the `mutateGreeting` method `fcl.mutate` sen

```
This guide covers flow-cli commands that make deploying contracts simple and using `fcl` to querying and mutating a contract.
## More information
That's it! You now have Flow app that uses auth, query and mutate the chain. This is just the beginning. There is so much more to know. Next steps:
Expand Down
11 changes: 5 additions & 6 deletions docs/guides/nft-marketplace.mdx → docs/guides/nft-marketplace.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,8 +71,7 @@ Following are the core components for any NFT marketplace solution on the Flow b
- [NFT Metadata Standard](https://github.com/onflow/flow-nft/#nft-metadata): A generalized framework for NFTs on Flow to expose their metadata. The framework described already has [a mechanism specified to render the basic representation](https://github.com/onflow/flow-nft/#list-of-common-views) of an NFT.
- [Flow NFT Catalog](https://github.com/dapperlabs/nft-catalog): NFT marketplaces can use this on-chain registry of NFTs to obtain the list of NFTs owned by an account and obtain display metadata for those NFTs and their collections. Developers should use the [example scripts](https://github.com/dapperlabs/nft-catalog#using-the-catalog-for-marketplaces-and-other-nft-applications) in conjunction with the [NFT Metadata Standard](https://github.com/onflow/flow-nft/#nft-metadata).
- [NFT Storefront Contract](https://github.com/onflow/nft-storefront): ​​Contract used by almost all Flow NFT marketplaces for creating NFT sale listings. Note that you can directly use the version of this contract already deployed on the Mainnet.
- [FCL (Flow Client Library)](../tools/clients/fcl-js/): This library is like web3.js in Ethereum. Application frontend will use FCL to interact with user wallets and the blockchain. JS-based backends of applications can also use it to interact with the blockchain.
>>>>>>> 99bd9fab3 (resolve merge conflict)
- [FCL (Flow Client Library)](../tools/clients/fcl-js): This library is like web3.js in Ethereum. Application frontend will use FCL to interact with user wallets and the blockchain. JS-based backends of applications can also use it to interact with the blockchain.
- Flow SDKs: Multiple SDKs are available in different programming languages ([Go](../tools/clients/flow-go-sdk/index.mdx), [Java](https://github.com/the-nft-company/flow-jvm-sdk)) for Flow application backends to interact with the blockchain.

## Coming from Ethereum
Expand All @@ -86,9 +85,9 @@ If you are coming from Ethereum, the following list shows corresponding modules
| NFT Standard | ERC-721/ERC-1155 | [Flow NFT Token Standard](https://github.com/onflow/flow-nft) |
| NFT Metadata Standard | ERC-721 | [Flow NFT Metadata Standard](https://github.com/onflow/flow-nft/#nft-metadata) |
| Native Crypto Currency | ETH | [FLOW](../build/basics/flow-token.md) |
| Wallet Interaction Library | web3.js | [Flow Client Library (FCL)](../tools/clients/) |
| Blockchain Interaction SDK | web3.js | [Language Clients](../tools/clients/) |
| Block Explorer | Etherscan | [Block Explorers](../tools/) |
| Wallet Interaction Library | web3.js | [Flow Client Library (FCL)](../tools/clients) |
| Blockchain Interaction SDK | web3.js | [Language Clients](../tools/clients) |
| Block Explorer | Etherscan | [Block Explorers](../tools) |
| Node Service Providers | Infura | [Official Flow Access Nodes](https://flowscan.org/staking/nodes) |
| Wallets | Metamask, WalletConnect | [Blocto](https://portto.com/), [Dapper Wallet](https://www.meetdapper.com/) |

Expand Down Expand Up @@ -236,7 +235,7 @@ On many blockchains, decentralized apps offer the Connect Wallet button to let u

Sign-in/up functionality is implemented using [FCL](../tools/clients/fcl-js/index.md). The following documentation provides details on how to implement this functionality on the application frontend:

- [FCL Authentication Functionality](../tools/clients/fcl-js/authentication.mdx)
- [FCL Authentication Functionality](../tools/clients/fcl-js/authentication.md)
- [Sign-in/up using FCL with Blocto Wallet](https://docs.blocto.app/blocto-sdk/flow/login-register)

Using FCL, you can get the authenticated account information for your users.
Expand Down
Loading

1 comment on commit d8685fa

@vercel
Copy link

@vercel vercel bot commented on d8685fa Oct 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

docs – ./

docs-smoky-iota.vercel.app
developers.flow.com
docs-git-main-onflow.vercel.app
docs-onflow.vercel.app

Please sign in to comment.