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.

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

docs: split up getting started guide into multiple pages #2202

Merged
merged 14 commits into from
May 13, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 4 additions & 0 deletions .changeset/ninety-pianos-crash.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
---

docs: split up getting started guide into multiple pages
25 changes: 24 additions & 1 deletion apps/docs/.vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,30 @@ export default defineConfig({
items: [
{
text: 'Getting Started',
link: '/getting-started.md',
link: '/guide/getting-started/',
collapsed: true,
items: [
{
text: 'Installation',
link: '/guide/getting-started/installation',
},
{
text: 'Usage',
link: '/guide/getting-started/usage',
},
{
text: 'Connecting to Testnet',
link: '/guide/getting-started/connecting-to-testnet',
},
{
text: 'Connecting to a Local Node',
link: '/guide/getting-started/connecting-to-a-local-node',
},
{
text: 'Further Resources',
link: '/guide/getting-started/further-resources',
},
],
},
{
text: 'Creating a Fuel dApp',
Expand Down
151 changes: 0 additions & 151 deletions apps/docs/src/getting-started.md

This file was deleted.

Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Connecting to a Local Node

Firstly, you will need a local node running on your machine. We recommend one of the following methods:

- [Testing utilities](/guide/testing/index.md#wallet-test-utilities) can assist in programmatically launching a short-lived node.
- Running [fuel-core](https://docs.fuel.network/guides/running-a-node/running-a-local-node/) directly, or via the CLI [fuels](/guide/fuels-cli/commands.md#fuels-core).

In the following example, we create a provider to connect to the local node and sign a message.

<<< @/../../docs-snippets/src/guide/introduction/getting-started.test.ts#connecting-to-the-local-node{ts:line-numbers}
22 changes: 22 additions & 0 deletions apps/docs/src/guide/getting-started/connecting-to-testnet.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Connecting to Testnet

The **Testnet** is a public network that allows you to interact with a Fuel Virtual Machine and is used for testing and development purposes.

> [!NOTE] Latest Testnet
> Beta 5
>
> `https://beta-5.fuel.network/graphql`

We have some useful resources for the Testnet:

- [**Faucet**](https://faucet-beta-5.fuel.network/) - for funding wallets that have been created.
- [**Explorer**](https://app.fuel.network/) - for viewing transactions and blocks.
- [**GraphQL Playground**](https://beta-5.fuel.network/playground) - for testing GraphQL queries and mutations.

---

In the example below, we connect a [Provider](/guide/provider/index.md) to the latest testnet and create a new wallet from a private key.

> **Note:** New wallets on the Testnet will not have any assets! You can use the [Faucet](https://faucet-beta-5.fuel.network/) to fund your wallet.

<<< @/../../docs-snippets/src/guide/introduction/getting-started.test.ts#connecting-to-the-testnet{ts:line-numbers}
11 changes: 11 additions & 0 deletions apps/docs/src/guide/getting-started/further-resources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Further Resources

For a more in-depth, step-by-step guide on working with the wider Fuel ecosystem, check out the [Developer Quickstart](https://docs.fuel.network/guides/quickstart/). This guide covers:

1. Installing all tools needed to develop with the Fuel ecosystem.

2. Writing your first Sway Project.

3. Deploying your contract.

4. Building a simple front-end dApp to interact with your deployed contract.
3 changes: 3 additions & 0 deletions apps/docs/src/guide/getting-started/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Getting Started

This guide will walk you through the process of setting up and using the Fuels-ts library in your front-end project.
39 changes: 39 additions & 0 deletions apps/docs/src/guide/getting-started/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<script setup>
import { data } from '../../versions.data'
const { fuels } = data
</script>

# Installation

We expect you to install the [Fuel Toolchain](https://docs.fuel.network/docs/sway/introduction/fuel_toolchain/#the-fuel-toolchain) before using this library. Follow [this guide](https://docs.fuel.network/guides/installation/) to get this installed.

The next step is to add the `fuels` dependency to your project. You can do this using the following command:

::: code-group

```sh-vue [npm]
npm install fuels@{{fuels}} --save
```

```sh-vue [pnpm]
pnpm add fuels@{{fuels}}
```

:::

**Note**: Use version `{{fuels}}` to ensure compatibility with `beta-5` network—check the [docs](https://docs.fuel.network/guides/installation/#using-the-latest-toolchain).

---

If you are using bun, you'll need to add a `trustedDependencies` field to your `package.json`:

```json
{
// ...
"trustedDependencies": ["@fuel-ts/fuel-core", "@fuel-ts/forc"]
}
```

This is to ensure that bun includes the `fuel-core` and `forc` binaries in your project.

> IMPORTANT: We don't officially support `bun` yet; use it at your own risk.
50 changes: 50 additions & 0 deletions apps/docs/src/guide/getting-started/usage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Usage

With the Fuels dependency set up, you can now create a React component that will connect to the Fuel provider and retrieve the base asset balance for a given wallet address. Here's an example of how to do this:

<!-- TODO: Create properly code snippet on new package: `app/react-app` after https://github.com/FuelLabs/fuels-ts/pull/827 got merged -->

```tsx
import { BN, Provider, Wallet } from "fuels";
import { useEffect, useState } from "react";

function App() {
const [balance, setBalance] = useState(0);

useEffect(() => {
async () => {
const provider = await Provider.create("https://beta-5.fuel.network/graphql");
const myWallet = Wallet.fromAddress("0x...", provider);
myWallet.getBalances().then((data) => {
setBalance(new BN(data[0].amount).toNumber());
});
}()
}, []);

return <div>My Balance: {balance}</div>;
}

export default App;
```

## CDN Usage (browser only)

For a quick test or just playing around, you can load it in your Web Apps straight from our CDN.

```html
<script type="module">
import {
Wallet,
Provider,
} from "https://cdnjs.cloudflare.com/ajax/libs/fuels/{{fuels}}/browser.mjs";

const exec = async () => {
const provider = await Provider.create(
"https://beta-5.fuel.network/graphql",
);
const { name } = provider.getChain();
console.log(name);
};
exec();
</script>
```
6 changes: 3 additions & 3 deletions apps/docs/src/guide/provider/index.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Provider

The [`Provider`](../../api/Account/Provider.md) lets you connect to a Fuel node ([_*local*_](../../getting-started.md#connecting-to-a-local-node) or [_*external*_](../../getting-started.md#connecting-to-the-testnet)) and interact with it, encapsulating common client operations in the SDK. Those operations include querying the blockchain for network, block, and transaction-related info (and [more](../../api/Account/Provider.md)), as well as sending [transactions](../transactions/index.md) to the blockchain.
The [`Provider`](/api/Account/Provider.md) lets you connect to a Fuel node ([_*local*_](/guide/getting-started/connecting-to-a-local-node.md) or [_*external*_](/guide/getting-started/connecting-to-testnet.md)) and interact with it, encapsulating common client operations in the SDK. Those operations include querying the blockchain for network, block, and transaction-related info (and [more](/api/Account/Provider.md)), as well as sending [transactions](/guide/transactions/index.md) to the blockchain.

All higher-level abstractions (e.g. [`Wallet`](../wallets/index.md), [`Contract`](../contracts/index.md)) that interact with the blockchain go through the `Provider`, so it's used for various actions like getting a wallet's balance, deploying contracts, querying their state, etc.
All higher-level abstractions (e.g. [`Wallet`](/guide/wallets/index.md), [`Contract`](/guide/contracts/index.md)) that interact with the blockchain go through the `Provider`, so it's used for various actions like getting a wallet's balance, deploying contracts, querying their state, etc.

<<< @/../../docs-snippets/src/guide/provider/provider.test.ts#provider-definition{ts:line-numbers}

You can find more examples of `Provider` usage [here](querying-the-chain.md).
You can find more examples of `Provider` usage [here](./querying-the-chain.md).
4 changes: 2 additions & 2 deletions apps/docs/src/guide/provider/querying-the-chain.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ Once you have set up a provider, you're ready to interact with the Fuel blockcha

We can connect to either a _*local*_ or an _*external*_ node:

> 1. _Running a [local node](../../getting-started.md#connecting-to-a-local-node)_
> 1. _Connecting to an [external node](../../getting-started.md#connecting-to-the-testnet)_
> 1. _Running a [local node](/guide/getting-started/connecting-to-a-local-node.md)_
> 1. _Connecting to an [external node](/guide/getting-started/connecting-to-testnet.md)_

Let's look at a few examples below.

Expand Down
Loading