Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated Quickstarts #1575

Merged
merged 6 commits into from
Nov 13, 2023
Merged

Updated Quickstarts #1575

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0695a15
updated contract quickstart to match create-near-app update
jaojeda Nov 7, 2023
609447d
added Rust tab to deploy sample scode block
jaojeda Nov 10, 2023
b441189
added information on sandbox testing
jaojeda Nov 10, 2023
59701ee
updated subtitle for contract quickstart in landing pages
jaojeda Nov 10, 2023
9aa5a81
updated code block testing example
jaojeda Nov 10, 2023
6f40c89
updated quickstart-fronted to use the new gateway pattern
jaojeda Nov 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 89 additions & 35 deletions docs/2.develop/integrate/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
id: quickstart-frontend
title: Hello NEAR 👋
title: Hello NEAR Gateway 👋
sidebar_label: ⭐ Quickstart
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import {CodeTabs, Language, Github} from "@site/components/codetabs"

Hi! Let us guide you in starting and interacting with your first decentralized app (dApp) in NEAR: Hello NEAR.
Hi! Let us guide you in starting and interacting with your first decentralized app (dApp) in NEAR: Hello NEAR Gateway.

**Hello NEAR** is a friendly dApp composed by two main components:
1. A smart contract that stores and retrieves a greeting message
2. A simple web-based frontend that displays the greeting and enables to change it.
**Hello NEAR Gateway** is a friendly dApp composed by two main components:
1. A simple web-based frontend integration that interacts with a Near smart contract and enables you to change it.
2. A basic gateway that uses components that are stored in the BOS.

---

Expand All @@ -22,63 +22,117 @@ If you already have [Node.js](https://nodejs.org/en/download) installed, simply
npx create-near-app@latest
```

Use the interactive menu to set up your first project folder, we recommend you to use `javascript`.
Use the interactive menu to set up your first project folder. For this guide we'll be using the ` A Near Gateway (Web App)` option.

Once the folder is ready, check the README. It will show you how to **build** and **deploy** the smart contract, and **start** the frontend.
Once the folder is ready, check the README. It will show you how to **run** the development server. The README includes a list of package managers you can use though, for best results, we recommend using `pnpm`.

```bash
npm run build
npm start
pnpm dev
```

<details>
<summary>
Test it online with Gitpod
</summary>

A new browser window will open automatically with the code, give it a minute and the frontend will pop-up (make sure the pop-up window is not blocked).
Once the development server is running visit `http://localhost:3000` in your browser to view the dApp. Note that since the dApp uses NextJS the app might take longer to load the pages on first visit.

---

| 🌐 JavaScript | 🦀 Rust |
|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| <a href="https://gitpod.io/#https://github.com/near-examples/hello-near-js.git">Open in Gitpod</a> | <a href="https://gitpod.io/#https://github.com/near-examples/hello-near-rs.git">Open in Gitpod</a> |
## Interacting With Your dApp

</details>
Once the app starts you will see the screen below:

---
![img](/docs/assets/examples/hello-near-landing-page.png)
*Landing page of Hello NEAR Gateway*

## Interacting With Hello NEAR
The app is divided into two sections. One that shows an example of how Web3 Components can be used and another that shows how you can build a front end that can interact with smart contracts.

Once the app starts you will see the screen below. Now go ahead and sign in with your NEAR account. If you don't have one, you will be able to create one in the moment.
We'll start by looking at the Near frontend integration. When you click on the Near Integration card you'll be taken to the frontend below:

![img](/docs/assets/examples/hello-near.png)
![img](/docs/assets/examples/hello-near-gateway.png)
*Frontend of Hello NEAR*

Once logged in, change the greeting and see how our Hello NEAR app greets you!
Now go ahead and sign in with your NEAR account. If you don't have one, you will be able to create one in the moment.

Once logged in, change the greeting and see how our Hello NEAR app greets you!

---

## Structure of a dApp
## Structure of a NEAR Integration

Now that you understand what the dApp does, let us take a closer look to its structure:
Now that you understand what the frontend does, let us take a closer look at its structure:

1. The frontend code lives in the `/frontend` folder.
2. The smart contract code is in the `/contract` folder.
3. The compiled smart contract can be found in `/out/main.wasm`.
4. The account's name in which the contract was deployed is in `/neardev/dev-account`.
1. The frontend code lives in the `/hello-near/page.js` file.
2. The smart contract ID is in the `/contract` folder.

Note that the code for the login button is not found along with the frontend code. That is because it is shared by both the Gateway and the Hello Near frontend and can be found all throughout the app. You can find that code in the `components/navigation.js` file.

You can learn more about how the wallet selector are set up in our [tools documentation](../../4.tools/wallet-selector.md).

### Frontend
The frontend is composed by a single HTML file (`frontend/index.html`). This file defines the components displayed in the screen.
The frontend is composed by a single JS file (`hello-near/page.js`). This file calls the `useWallet` hook to import the methods we'll need to view and set the greeting.

Those are then used to set the state and set up a helper function that is passed down to the save button.

<CodeTabs>
<Language value="🌐 JavaScript" language="js">
<Github fname="index.js"
url="https://github.com/near/create-near-app/blob/master/templates/frontend/next/src/app/hello-near/page.js"
start="12" end="32" />
</Language>
</CodeTabs>

### Logic

The frontend's query logic lives in `wallets/wallet-selector.js`, which communicates with the contract through the Wallet API. You can find those queries in the `useInitWallet` hook in the following code:

<CodeTabs>
<Language value="🌐 JavaScript" language="js">
<Github fname="index.js"
url="https://github.com/near/create-near-app/blob/master/templates/frontend/next/src/wallets/wallet-selector.js"
start="82" end="112" />
</Language>
</CodeTabs>

The methods are then set in the `useWallet` hook's state so they can be accessed by the frontend.

## Interacting with Web3 Components

Now let's take a look at the gateway. Go ahead and click on the card titled Web3 Components at the bottom on the page. Once you do you'll be taken to the screen below:

![img](/docs/assets/examples/hello-near-components.png)
*Frontend of Hello Components*

If you're following along, you should already be logged into your NEAR account. If you aren't, go ahead and do so now.

You'll see that once you're logged in you are able to interact with the components that come included with the app.

## Structure of a Gateway

The website's logic lives in `frontend/index.js`, which communicates with the contract through `frontend/near-interface.js`. You will notice in `/frontend/index.js` the following code:
Now that you've interacted with some simple components in a gateway, let us take a closer look at it's structure:

1. The code for the container that holds the components can be found in the `hello-components/page.js` file.
2. The wrapper of each individual components lives in the `components/vm-components.js` file.
3. The component map with the link to each component in the BOS can found in the `config.js` file.

Note that, like in the Near Integration example above, the code for the login button is not found along with the frontend code. That is because it is shared by both the Gateway and the Hello Near frontend and can be found all throughout the app. You can find that code in the components/navigation.js file.

### Gateway

The gateway itself is pretty simple. As can be seen in the `hello-components/page.js`, all the gateway is doing is rendering components that themselves are using custom React components pulled form the Near Social VM API so they can display components from the BOS:

<CodeTabs>
<Language value="🌐 JavaScript" language="js">
<Github fname="index.js"
url="https://github.com/near-examples/hello-near-js/blob/master/frontend/index.js"
start="11" end="21" />
url="https://github.com/near/create-near-app/blob/master/templates/frontend/next/src/components/vm-component.js"
start="9" end="26" />
</Language>
</CodeTabs>

It indicates our app, when it starts, to check if the user is already logged in and execute either `signedInFlow()` or `signedOutFlow()`.
In the code above, the `Widget` component is being imported from the Near Social VM and is then handed the link to the component we're trying to render form the BOS.

## Moving Forward

That's it for our first quickstart dApp tutorial. You have now seen a fully functional frontend integration and a simple gateway that can render Web3 components.

In the following sections we dive deeper into what are [BOS components](../../bos/overview.md), how to [make your own gateway](../../bos/tutorial/gateway.md), and what are some of the [built-in components](../../bos/components.md).

If you have any questions, do not hesitate in joining us on [Discord](https://near.chat). We regularly host Office Hours, in which you can join our voice channel and ask questions.

Happy coding!
91 changes: 33 additions & 58 deletions docs/2.develop/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,16 @@
---
id: quickstart-guide
title: Hello NEAR 👋
title: Hello NEAR Contract 👋
sidebar_label: ⭐ Quickstart
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import {CodeTabs, Language, Github} from "@site/components/codetabs"

Hi! Let us guide you in starting and interacting with your first decentralized app (dApp) in NEAR: Hello NEAR.
Hi! Let us guide you in starting and interacting with your first smart contract in NEAR: Hello NEAR Contract.

**Hello NEAR** is a friendly dApp composed by two main components:
1. A smart contract that stores and retrieves a greeting message
2. A simple web-based frontend that displays the greeting and enables to change it.
**Hello NEAR Contract** is a simple smart contract that stores and retrieves a greeting message. It uses two methods, `get_greeting` and `set_greeting`, as well as a temporary
dev account to test out both methods.

---

Expand All @@ -22,51 +21,43 @@ If you already have [Node.js](https://nodejs.org/en/download) installed, simply
npx create-near-app@latest
```

Use the interactive menu to set up your first project folder, we recommend you to use `javascript`.
Use the interactive menu to set up your first project folder. For this guide we'll be using the `A Near Smart Contract` option.

Once the folder is ready, check the README. It will show you how to **build** and **deploy** the smart contract, and **start** the frontend.
Once the folder is ready, check the README. It will show you how to **build** and **deploy** the smart contract.


<CodeTabs>
<Language value="🌐 JavaScript" language="js">

```bash
npm run build
npm start
npm run deploy
```

<details>
<summary>
Test it online with Gitpod
</summary>

A new browser window will open automatically with the code, give it a minute and the frontend will pop-up (make sure the pop-up window is not blocked).


| 🌐 JavaScript | 🦀 Rust |
|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| <a href="https://gitpod.io/#https://github.com/near-examples/hello-near-js.git">Open in Gitpod</a> | <a href="https://gitpod.io/#https://github.com/near-examples/hello-near-rs.git">Open in Gitpod</a> |

</details>

---

## Interacting With Hello NEAR
</Language>
<Language value="🦀 Rust" language="rust">

Once the app starts you will see the screen below. Now go ahead and sign in with your NEAR account. If you don't have one, you will be able to create one in the moment.
```bash
./build.sh
./deploy.sh
```

![img](/docs/assets/examples/hello-near.png)
*Frontend of Hello NEAR*
</Language>
</CodeTabs>

Once logged in, change the greeting and see how our Hello NEAR app greets you!
Once the smart contract is deployed, you can set a new greeting using the provided temporary dev account found in `neardev/dev-account` or by using a testnet account. You can [sign up for a testnet account here](https://testnet.mynearwallet.com/create).

We go over how testnet accounts are used in more detail in [other guides](../3.tutorials/crosswords/03-intermediate/03-linkdrop.md), but for now all you need to know is that you can use your testnet account anywhere an account ID is needed without having to worry about any real-world costs.

---

## Structure of a dApp
## Structure of the project

Now that you understand what the dApp does, let us take a closer look to its structure:
Now that you've deployed your first contract, let us take a closer look to its structure:

1. The frontend code lives in the `/frontend` folder.
2. The smart contract code is in the `/contract` folder.
3. The compiled smart contract can be found in `/out/main.wasm`.
4. The account's name in which the contract was deployed is in `/neardev/dev-account`.
1. The smart contract code is in the `/contract` folder.
2. The compiled smart contract can be found in `/build/<your_project_name>.wasm`.
3. The account's name in which the contract was deployed is in `/neardev/dev-account`.

### Contract
The contract presents 2 methods: `set_greeting` and `get_greeting`. The first one stores a `String` in the contract's parameter `message`, while the second one retrieves it. By default, the contract returns the message `"Hello"`.
Expand All @@ -89,41 +80,25 @@ The contract presents 2 methods: `set_greeting` and `get_greeting`. The first on
## Testing

When writing smart contracts it is very important to test all methods exhaustively. This
project has both **unit** and **integration** tests. Before digging in their code,
go ahead and execute them using the command `npm run test`.
project has **integration** tests. It creates a sandbox environment that takes the `.wasm` file for your contract and simulates creating users and running both methods on the contract.

### Unit test
Unit tests check individual functions in the smart contract. They are written in the
same language than the smart contract. If your contract is in Rust you will find the tests at the bottom of
each `.rs` file.
Sandbox testing is important because it allows you test all methods on your contract in a secure and separate environment that imitates real world scenarios.

<CodeTabs>
<Language value="🦀 Rust" language="rust">
<Github fname="lib.rs"
url="https://github.com/near-examples/hello-near-rs/blob/main/contract/src/lib.rs"
start="46" end="58" />
</Language>
</CodeTabs>

### Integration test

Integration tests can be written in both Javascript and Rust. They work by deploying the contract in a **sandbox** and executing methods on it.
In this way, integration tests simulate interactions from users in a realistic scenario.
You will find the integration tests for `hello-near` in `integration-tests/`.
Before digging in their code, go ahead and execute them using the command `npm run test`.

<CodeTabs>
<Language value="🌐 JavaScript" language="js">
<Github fname="main.ava.ts"
url="https://github.com/near-examples/hello-near-js/blob/master/integration-tests/src/main.ava.ts"
start="32" end="43" />
<Github fname="lib.rs"
url="https://github.com/near/create-near-app/blob/master/templates/sandbox-tests/sandbox-ts/src/main.ava.ts"
start="33" end="44" />
</Language>
</CodeTabs>

---

## Moving Forward

That's it for our first quickstart tutorial. You have now seen a fully functional contract with a minimal user interface and testing.
That's it for our first quickstart tutorial. You have now seen a fully functional contract and testing.

Go ahead and check other [examples](/tutorials/examples/guest-book) or proceed straight to the [Develop section](./contracts/anatomy.md) to know how to write your own contract.

Expand Down
2 changes: 1 addition & 1 deletion docs/2.develop/welcome.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Do not worry if you are new to blockchain technologies, we will get you up to sp

<FeatureList>
<Column title="Build dApps">
<Feature url="/develop/quickstart-guide" title="Quickstart" subtitle="Spin-up your first dApp" image="quickstart.png" highlight="true" />
<Feature url="/develop/quickstart-guide" title="Quickstart" subtitle="Spin-up your first smart contract" image="quickstart.png" highlight="true" />
<Feature url="/tutorials/welcome" title="Tutorials & Examples" subtitle="Check-out a vast library of examples" image="tutorials.png" />
<Feature url="/develop/contracts/introduction" title="Build a Contract" subtitle="Learn how to write smart contracts" image="smartcontract.png" />
<Feature url="/develop/testing/introduction" title="Test the Contract" subtitle="Write unit & integration tests" image="test.png" />
Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ Welcome, this is the starting point for all NEAR documentation. Learn to build a
<Feature url="/concepts/basics/validators" title="Validators" subtitle="Learn how the network stays safe" image="validation.png" />
</Column>
<Column title="Developer Docs" size="3">
<Feature url="/develop/quickstart-guide" title="Quickstart" subtitle="Spin-up your first dApp" image="quickstart.png" />
<Feature url="/develop/quickstart-guide" title="Quickstart" subtitle="Spin-up your first smart contract" image="quickstart.png" />
<Feature url="/tutorials/welcome" title="Tutorials & Examples" subtitle="Check out a vast library of examples" image="tutorials.png" />
<Feature url="/develop/contracts/introduction" title="Build a Contract" subtitle="Learn how to write smart contracts" image="smartcontract.png" />
<Feature url="/develop/testing/introduction" title="Test the Contract" subtitle="Write unit & integration tests" image="test.png" />
Expand Down
Binary file added website/static/docs/assets/examples/hello-near-components.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/static/docs/assets/examples/hello-near-gateway.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/static/docs/assets/examples/hello-near-landing-page.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading