Merge pull request #939 from onflow/brian-doyle/first-pass-minor-fixes

Clarify Hello World Guide

docs/build/getting-started/quickstarts/fcl-quickstart.md

@@ -1,24 +1,34 @@
 ---
 sidebar_position: 3
-sidebar_label: Pt. 3 - Interacting with the Blockchain
+sidebar_label: 3 - Simple Frontend
 ---
 
-# Hello World Pt. 3 - Interacting with the Blockchain
+# Hello World Part 3 - Simple Frontend
 
-Flow Client Library (FCL), is a JavaScript library developed to facilitate interactions with the Flow blockchain. It provides developers with tools to build, integrate, and interact with Flow directly from web applications. This web app quickstart will get you interacting with a contract already deployed to Flow.
+[Flow Client Library] (FCL), is a JavaScript library developed to facilitate interactions with the Flow blockchain. It provides developers with tools to build, integrate, and interact with Flow directly from web applications. This web app quickstart will get you interacting with a contract already deployed to Flow.
 
-For this tutorial, we're going to be making a [React](https://react.dev/learn) app with [Create React App](https://create-react-app.dev/). We'll try and keep the code as simple as possible in case you're coming from another framework.
+For this tutorial, we're going to be making a [React] app with [Create React App]. We'll try and keep the code as simple as possible in case you're coming from another framework.
 
-First, let's create our app and then navigate to it with the following terminal commands:
+## Objectives
 
-```
+After completing this guide, you'll be able to:
+
+* Display data from a [Cadence] smart contract on a React frontend using the [Flow Client Library]
+
+## Creating the App
+
+First, let's create our app and then navigate to it with the following terminal commands.  From the root of where you keep your source code:
+
+```zsh
 npx create-react-app fcl-app-quickstart
 cd fcl-app-quickstart
 ```
 
+Open the new project in a new window in your editor.
+
 It comes with a default layout, but let's remove it in `src/App.js` with something simple. Copy and paste this:
 
-```
+```tsx
 // src/App.js
 
 import './App.css';
@@ -36,39 +46,43 @@ export default App;
 
 Now let's run our app with the following `npm` command:
 
-```
+```zsh
 npm start
 ```
 
+You'll see a blank page with `FCL App Quickstart` at the top.
+
 ## Setting Up FCL
 
-In order to use FCL, we need to install it. Let's run the following to download the library and set it as a dependency in our project:
+In order to use FCL, we need to install it. Shut the server down then run the following to download the library and set it as a dependency in our project:
 
 ```
 npm install @onflow/fcl --save
 ```
 
 Next we'll want to add to our FCL configuration. There's a lot you can do here, but for this simple example, let's configure `accessNode.api` to talk to the Testnet Flow Access Node. An Access Node serves as the primary point of interaction for clients, such as wallets, dapps, and other services, to communicate with the Flow network. It provides a gateway for these clients to submit transactions, query data, and retrieve information without having to connect to the entire network or maintain a full copy of the blockchain.
 
-For our example, we are going to point at a free Access Node provided by Flow. Add the following config code to your `src/App.js`
+For our example, we are going to point at a free Access Node provided by Flow. Add the following config code to your `src/App.js`:
 
-```
+```tsx
 // src/App.js
 
-import * as fcl from '@onflow/fcl'
+import * as fcl from '@onflow/fcl';
 
 fcl.config({
   'accessNode.api': 'https://rest-testnet.onflow.org'
-})
+});
 ```
 
 ## Querying the Chain
 
-On Flow, you can interact with a contract by reading from the chain with a script or changing its state with a transaction. Reading is free and is done with FCL by passing a Cadence (the smart contract language of Flow) script to `fcl.query`. For our example we are going to read from a `HelloWorld` contract deployed to the account `0xa1296b1e2e90ca5b` on `testnet` (you can [view the contract here](https://f.dnz.dev/0xa1296b1e2e90ca5b/HelloWorld) to see what it looks like).
+On Flow, you can interact with a contract by reading from the chain with a script or changing its state with a transaction. Reading is free and is done with FCL by passing a [Cadence] script to `fcl.query`.
+
+For our example we are going to read from a `HelloWorld` contract deployed to the account `0xa1296b1e2e90ca5b` on `testnet` (you can [view the contract here] to see what it looks like).
 
 In the same `src/App.js` file, let's create app state to store our greeting and query the chain when the component renders in order to fetch the greeting state from the `HelloWorld` contract.
 
-```
+```tsx
 const [greeting, setGreeting] = useState("");
 
 useEffect(() => {
@@ -93,7 +107,7 @@ useEffect(() => {
 
 At this point our entire `src/App.js` file should look like this:
 
-```
+```tsx
 import { useEffect, useState } from 'react';
 import './App.css';
 import * as fcl from '@onflow/fcl';
@@ -137,6 +151,16 @@ export default App;
 
 You just built an app on Flow!
 
+Run `npm start` again.  After a moment, the greeting from `HelloWorld` will appear!
+
 ## 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.md) 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 [the app quickstart guide] or the [FCL documentation].
+
+[Flow Client Library]: ../../../tools/clients/fcl-js
+[Cadence]: https://cadence-lang.org/
+[React]: https://react.dev/learn
+[Create React App]: https://create-react-app.dev/
+[view the contract here]: https://f.dnz.dev/0xa1296b1e2e90ca5b/HelloWorld
+[the app quickstart guide]: ../../guides/flow-app-quickstart
+[FCL documentation]: ../../../tools/clients/fcl-js

docs/build/getting-started/quickstarts/flow-cli.md

@@ -1,60 +1,73 @@
 ---
 sidebar_position: 2
-sidebar_label: Pt. 2 - Local Development
+sidebar_label: 2 - Local Development
 ---
 
-# Hello World Pt. 2 - Local Development
+# Hello World Part 2 - Local Development
 
-The Flow Command Line Interface (CLI) is a set of tools that developers can use to interact with the Flow blockchain by managing accounts, sending transactions, deploying smart contracts, running the emulator, and more. This quickstart will get you familiar with its main concepts and functionality.
+The [Flow Command Line Interface] (CLI) is a set of tools that developers can use to interact with the Flow blockchain by managing accounts, sending transactions, deploying smart contracts, running the emulator, and more. This quickstart will get you familiar with its main concepts and functionality.
+
+## Objectives
+
+After completing this guide, you'll be able to:
+
+* Create a Flow project using the [Flow Command Line Interface]
+* Add an already-deployed contract to your project with the [Dependency Manager]
+* Deploy a smart contract locally to the Flow Emulator
+* Write and execute scripts to interact with a deployed smart contract
 
 ## Installation
 
-The first thing you'll need to do is install the Flow CLI. If you have [homebrew](https://brew.sh/) installed you can run:
+The first thing you'll need to do is install the Flow CLI. If you have [homebrew] installed you can run:
 
-```
+```zsh
 brew install flow-cli
 ```
 
-For other ways of installing, please [refer to the installation guide](../../../tools/flow-cli/install.md).
+For other ways of installing, please refer to the [installation guide].
 
 ## Configuration
 
 Lets first create a project directory and navigate to it:
 
-```
+```zsh
 mkdir cli-quickstart
 cd cli-quickstart
 ```
 
 Next, we'll initialize a new Flow project with the CLI:
 
-```
+```zsh
 flow init --config-only
 ```
 
 This will create a `flow.json` file in your project directory. This file is used to configure your project and describe the setup of your contracts, networks, and accounts.
 
 It will also have a default `emulator-account` created for you. We'll use this account to interact with the emulator later on.
 
-<Callout type="info">
-For additional details on how `flow.json` is configured, [read here.](../../../tools/flow-cli/flow.json/configuration.md)
-</Callout>
+:::info
+
+For additional details on how `flow.json` is configured, review the [configuration docs].
+
+:::
 
 ## Grabbing the HelloWorld Contract
 
-For this demo, we are going to be interacting with a simple `HelloWorld` contract that is already deployed on Flow's `testnet` network on account [0xa1296b1e2e90ca5b](https://contractbrowser.com/A.9dca641e9a4b691b.HelloWorld). In order to grab this project dependency, we'll use Flow's [Dependency Manager](../../../tools/flow-cli/dependency-manager.md) to install it into our project using a source string that defines the network, address, and contract name of the contract we want to import.
+For this demo, we are going to be interacting with a simple `HelloWorld` contract, written in [Cadence], that is already deployed on Flow's `testnet` network on account [0xa1296b1e2e90ca5b]. In order to grab this project dependency, we'll use Flow's [Dependency Manager] to install it into our project using a source string that defines the network, address, and contract name of the contract we want to import.
 
-```
+```zsh
 flow dependencies add testnet://0xa1296b1e2e90ca5b.HelloWorld
 ```
 
-This will add the `HelloWorld` contract and any of its dependencies to an `imports` directory in your project (we recommend adding this directory to your .gitignore file). It will also add any dependencies to your `flow.json` file.
+This will add the `HelloWorld` contract and any of its dependencies to an `imports` directory in your project. We recommend adding this directory to your `.gitignore` file, which is done by the script by default. It will also add any dependencies to your `flow.json` file.
 
-During the install you'll be prompted to specify which account to deploy the contracts to. For this tutorial, you can select the default `emulator-account`.
+During the install you'll be prompted to specify which account to deploy the contracts to. For this tutorial, you can select the default `emulator-account`. Leave the alias address for HelloWorld on mainnet blank.
 
-Opening the contract file in your editor you should see the following:
+Review the `📝 Dependency Manager Actions Summary` for a list of actions completed by the script.
 
-```
+Open `imports/a1296b1e2e90ca5b/HelloWorld.cdc` in your editor. You will see the following:
+
+```cadence
 access(all) contract HelloWorld {
 
   access(all)
@@ -75,35 +88,50 @@ This contract has a `greeting` variable that can be read and changed. It also ha
 
 ## Deploying the Contract to Emulator
 
-Emulator is a local version of the Flow blockchain that you can use to test your contracts and scripts. It's a great way to develop and test your contracts without having to interact with the `testnet` or `mainnet`.
+The emulator is a local version of the Flow blockchain that you can use to test your contracts and scripts. It's a great way to develop and test your contracts locally - before you try them on the `testnet` or `mainnet`.
 
-Before we deploy, let's open a new terminal window and run the emulator:
+Before we deploy, let's open a new terminal window and run the emulator.  From the root of your project directory, where your `emulator-account.pkey` and `flow.json` files are located, run:
 
-```
+```zsh
 flow emulator start
 ```
 
-To deploy the `HelloWorld` contract to the emulator, you can run the following command:
+:::warning
 
-```
+If you see a message that configuration is missing, you are in the wrong directory.  Do **not** run `flow init`!.
+
+
+> 🙏 Configuration is missing, initialize it with: 'flow init' and then rerun this command.
+
+:::
+
+To deploy the `HelloWorld` contract to the emulator, return to your first terminal and run the following command:
+
+```zsh
 flow project deploy
 ```
 
-The contract will now have been deployed to the account you selected earlier. You can now interact with it using a script.
+You should see:
+
+```zsh
+🎉 All contracts deployed successfully
+```
+
+The contract will now have been deployed to the default `emulator-account`. You can now interact with it using a script.
 
 ## Running Scripts
 
 Scripts are used to read data from the Flow blockchain. There is no state modification. In our case, we are going to read a greeting from the `HelloWorld` contract.
 
 Let's create a script file. We can generate a boilerplate script file with the following command:
 
-```
+```zsh
 flow generate script ReadGreeting
 ```
 
-This will create a file called `ReadGreeting.cdc` in the `cadence/scripts` directory.  Let's update the script to read the greeting from the `HelloWorld` contract:
+This will create a file called `ReadGreeting.cdc` in the `cadence/scripts` directory.  Let's update the script to read the greeting from the `HelloWorld` contract.  Replace the existing coded with:
 
-```
+```cadence
 import "HelloWorld"
 
 access(all) fun main(): String {
@@ -113,11 +141,15 @@ access(all) fun main(): String {
 
 The import syntax will automatically resolve the address of the contract on the network you are running the script on. This is determined by your `flow.json` configuration.
 
-> Note: if you'll like to learn more about writing scripts, please [read here](../../basics/scripts.md).
+:::tip
+
+If you'll like to learn more about writing scripts, please check out the docs for [basic scripts].
+
+:::
 
 To run the script, we'll run this from the CLI:
 
-```
+```zsh
 flow scripts execute cadence/scripts/ReadGreeting.cdc
 ```
 
@@ -129,13 +161,13 @@ To change state on the Flow Blockchain, you need to run a transaction. Let's cre
 
 First, create a file called `cadence/transactions/ChangeGreeting.cdc` with the following command:
 
-```
+```zsh
 flow generate transaction ChangeGreeting
 ```
 
-Update the boilerplate transaction to look like this:
+Open the new file - `cadence/transactions/ChangeGreeting.cdc`.  Update the boilerplate transaction to look like this:
 
-```
+```cadence
 import "HelloWorld"
 
 transaction(greeting: String) {
@@ -150,28 +182,73 @@ transaction(greeting: String) {
 }
 ```
 
-This will log the account signing the transaction, call the `changeGreeting` method of the `HelloWorld` contract, and pass in the new greeting. (If you want to learn more about writing transactions, please [read here](../../basics/transactions.md)).
+This will log the account signing the transaction, call the `changeGreeting` method of the `HelloWorld` contract, and pass in the new greeting. 
 
-In order to run a transaction, the signing account needs to pay for it. We could run a transaction on emulator using the default `emulator-account` account. Let's learn one more command for creating accounts.
+:::tip
 
-The easiest way to create an account using CLI is by running (remember, your emulator should still be running at this point in another terminal):
+If you want to learn more about writing transactions, please read the docs for [basic transactions].
 
-```
+:::
+
+In order to run a transaction, the signing account needs to pay for it. You could run the transaction on emulator using the default `emulator-account` account, but a better test is to run it with a new test account.
+
+Let's learn the command for creating accounts.
+
+The easiest way to create an account using CLI is with:
+
+```zsh
 flow accounts create
 ```
 
-Once that runs, select `Emulator` as the network and give your account the name `emulator-tester`. You'll now see this account in your `flow.json`.
+Remember, your emulator should still be running at this point in another terminal.
+
+Give your account the name `emulator-tester`, then select `Emulator` as the network.  You'll now see this account in your `flow.json`.
 
 To run a transaction with this new account, you can run the following:
 
-```
+```zsh
 flow transactions send cadence/transactions/ChangeGreeting.cdc "Hello, me" --signer emulator-tester --network emulator
 ```
 
-You've just modified the state of the Flow Blockchain!
+You've just modified the state of the Flow Blockchain! At least on the emulator.  You'll know it worked if you see the receipt.  Yours will be similar to:
 
-## More
+```zsh
+Transaction ID: 2ff6cbb8125103595fca0abaead94cd00510d29902ceae9f5dc480e927ab7334
+
+Block ID	36bbf6fc573129fa9a3c78a43e257d3b627a3af78fd9e64eeb133d981819cc69
+Block Height	3
+Status		✅ SEALED
+ID		2ff6cbb8125103595fca0abaead94cd00510d29902ceae9f5dc480e927ab7334
+Payer		179b6b1cb6755e31
+Authorizers	[179b6b1cb6755e31]
+```
 
-If you want to continue on generating your own contracts, you can also use the the `generate` subcommand to create a new contract file. See more on the `generate` documentation.
+You can also re-run the `ReadGreeting` script with:
+
+```zsh
+flow scripts execute cadence/scripts/ReadGreeting.cdc
+```
+
+You'll now see:
+
+```zsh
+Result: "Hello, me"
+```
+
+## More
 
-After that, it's easy to add your contract to your project configuration using the Flow CLI `config` commands.
+If you want to continue on generating your own contracts, you can also use the the `generate` subcommand to create a new contract file. See more in the [`generate` documentation].
+
+After that, it's easy to add your contract to your project configuration using the Flow CLI [`config` commands].
+
+[Flow Command Line Interface]: ../../../tools/flow-cli
+[Cadence]: https://cadence-lang.org/
+[configuration docs]: ../../../tools/flow-cli/flow.json/configuration
+[homebrew]: https://brew.sh/
+[installation guide]: ../../../tools/flow-cli/install
+[0xa1296b1e2e90ca5b]: https://contractbrowser.com/A.9dca641e9a4b691b.HelloWorld
+[Dependency Manager]: ../../../tools/flow-cli/dependency-manager
+[basic scripts]: ../../basics/scripts
+[basic transactions]: ../../basics/transactions
+[`generate` documentation]: ../../../tools/flow-cli/boilerplate
+[`config` commands]: https://developers.flow.com/tools/flow-cli/flow.json/manage-configuration