From 44b6c75591874e9f48e9c8035980f60b34bb64eb Mon Sep 17 00:00:00 2001 From: Anderson Arboleya Date: Tue, 24 Dec 2024 08:31:43 -0300 Subject: [PATCH] Revamping getting started docs --- apps/docs/.vitepress/config.ts | 16 +++--- .../src/guide/getting-started/cdn-usage.md | 20 ++++++++ .../connecting-to-a-local-node.md | 10 ---- .../getting-started/connecting-to-network.md | 30 +++++++++++ .../getting-started/connecting-to-testnet.md | 22 -------- .../getting-started/further-resources.md | 13 ++--- apps/docs/src/guide/getting-started/index.md | 11 +++- .../src/guide/getting-started/installation.md | 16 +++--- .../guide/getting-started/react-example.md | 31 ++++++++++++ .../getting-started/running-local-node.md | 46 +++++++++++++++++ ...-localnode.ts => connecting-to-network.ts} | 6 ++- .../snippets/connecting-to-testnet.ts | 15 ------ apps/docs/src/guide/getting-started/usage.md | 50 ------------------- 13 files changed, 165 insertions(+), 121 deletions(-) create mode 100644 apps/docs/src/guide/getting-started/cdn-usage.md delete mode 100644 apps/docs/src/guide/getting-started/connecting-to-a-local-node.md create mode 100644 apps/docs/src/guide/getting-started/connecting-to-network.md delete mode 100644 apps/docs/src/guide/getting-started/connecting-to-testnet.md create mode 100644 apps/docs/src/guide/getting-started/react-example.md create mode 100644 apps/docs/src/guide/getting-started/running-local-node.md rename apps/docs/src/guide/getting-started/snippets/{connecting-to-localnode.ts => connecting-to-network.ts} (55%) delete mode 100644 apps/docs/src/guide/getting-started/snippets/connecting-to-testnet.ts delete mode 100644 apps/docs/src/guide/getting-started/usage.md diff --git a/apps/docs/.vitepress/config.ts b/apps/docs/.vitepress/config.ts index f1a007accd1..a93e908e0d7 100644 --- a/apps/docs/.vitepress/config.ts +++ b/apps/docs/.vitepress/config.ts @@ -51,16 +51,20 @@ export default defineConfig({ link: '/guide/getting-started/installation', }, { - text: 'Usage', - link: '/guide/getting-started/usage', + text: 'Connecting to the Network', + link: '/guide/getting-started/connecting-to-network', }, { - text: 'Connecting to Testnet', - link: '/guide/getting-started/connecting-to-testnet', + text: 'Running a local Fuel node', + link: '/guide/getting-started/running-local-node', }, { - text: 'Connecting to a Local Node', - link: '/guide/getting-started/connecting-to-a-local-node', + text: 'React Example', + link: '/guide/getting-started/react-example', + }, + { + text: 'CDN Usage', + link: '/guide/getting-started/cdn-usage', }, { text: 'Further Resources', diff --git a/apps/docs/src/guide/getting-started/cdn-usage.md b/apps/docs/src/guide/getting-started/cdn-usage.md new file mode 100644 index 00000000000..e8b465ff45f --- /dev/null +++ b/apps/docs/src/guide/getting-started/cdn-usage.md @@ -0,0 +1,20 @@ +# CDN Usage (browser only) + +```html + +``` diff --git a/apps/docs/src/guide/getting-started/connecting-to-a-local-node.md b/apps/docs/src/guide/getting-started/connecting-to-a-local-node.md deleted file mode 100644 index 7a464d19088..00000000000 --- a/apps/docs/src/guide/getting-started/connecting-to-a-local-node.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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](../testing/launching-a-test-node.md) 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. - -In the following example, we create a provider to connect to the local node and sign a message. - -<<< @./snippets/connecting-to-localnode.ts#main{ts:line-numbers} diff --git a/apps/docs/src/guide/getting-started/connecting-to-network.md b/apps/docs/src/guide/getting-started/connecting-to-network.md new file mode 100644 index 00000000000..70c38564229 --- /dev/null +++ b/apps/docs/src/guide/getting-started/connecting-to-network.md @@ -0,0 +1,30 @@ +# Connecting to the Network + +After [installing](./installation.md) the `fuels` package, it's easy to connect to the Network: + +<<< @./snippets/connecting-to-network.ts#main{ts:line-numbers} + +# RPC URLs + +These are our official RPC URLs: + +| Mainnet | Testnet | +| ----------------------------------------- | ----------------------------------------- | +| `https://mainnet.fuel.network/v1/graphql` | `https://testnet.fuel.network/v1/graphql` | + +# Resources + +You can also access all our apps directly: + +| | Mainnet | Testnet | +| -------- | ------------------------------------------ | ------------------------------------------ | +| Faucet | — | https://faucet-testnet.fuel.network/ | +| Explorer | https://app.fuel.network | https://app-testnet.fuel.network | +| Bridge | https://app.fuel.network/bridge | https://app-testnet.fuel.network/bridge | +| GraphQL | https://mainnet.fuel.network/v1/playground | https://testnet.fuel.network/v1/playground | + +# More + +If you want to connect to `localhost`, check this: + +- [Running a local Fuel node](./running-local-node.md) diff --git a/apps/docs/src/guide/getting-started/connecting-to-testnet.md b/apps/docs/src/guide/getting-started/connecting-to-testnet.md deleted file mode 100644 index 188a30b1397..00000000000 --- a/apps/docs/src/guide/getting-started/connecting-to-testnet.md +++ /dev/null @@ -1,22 +0,0 @@ -# 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 -> Dev Testnet -> -> `https://testnet.fuel.network/v1/graphql` - -We have some useful resources for the Testnet: - -- [**Faucet**](https://faucet-testnet.fuel.network/) - for funding wallets that have been created. -- [**Explorer**](https://app.fuel.network/) - for viewing transactions and blocks. -- [**GraphQL Playground**](https://testnet.fuel.network/v1/playground) - for testing GraphQL queries and mutations. - ---- - -In the example below, we connect a [Provider](../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-testnet.fuel.network/) to fund your wallet. - -<<< @./snippets/connecting-to-testnet.ts#main{ts:line-numbers} diff --git a/apps/docs/src/guide/getting-started/further-resources.md b/apps/docs/src/guide/getting-started/further-resources.md index 015e4115d1b..9dd190bb679 100644 --- a/apps/docs/src/guide/getting-started/further-resources.md +++ b/apps/docs/src/guide/getting-started/further-resources.md @@ -1,11 +1,8 @@ # 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: +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/), which 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. +1. Installing all tools needed to develop with the Fuel ecosystem +1. Writing your first Sway Project +1. Deploying your contract +1. Building a simple front-end dApp to interact with your deployed contract diff --git a/apps/docs/src/guide/getting-started/index.md b/apps/docs/src/guide/getting-started/index.md index cbb43088ec9..e98236114e6 100644 --- a/apps/docs/src/guide/getting-started/index.md +++ b/apps/docs/src/guide/getting-started/index.md @@ -1,3 +1,12 @@ # Getting Started -This guide will walk you through the process of setting up and using the Fuels-ts library in your front-end project. +Welcome to `fuels` Typescript SDK! + +We prepared a couple guides to walk you through your first steps: + +1. [Installation](/guide/getting-started/installation) +1. [Connecting to the Network](/guide/getting-started/connecting-to-network) +1. [Running a local Fuel node](/guide/getting-started/running-local-node) +1. [React Example](/guide/getting-started/react-example) +1. [CDN Usage](/guide/getting-started/cdn-usage) +1. [Further Resources](/guide/getting-started/further-resources) diff --git a/apps/docs/src/guide/getting-started/installation.md b/apps/docs/src/guide/getting-started/installation.md index 51520e763aa..bcd754346e5 100644 --- a/apps/docs/src/guide/getting-started/installation.md +++ b/apps/docs/src/guide/getting-started/installation.md @@ -5,24 +5,26 @@ # 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. +You must install the [Fuel Toolchain](https://docs.fuel.network/guides/installation/) before using this library. -The next step is to add the `fuels` dependency to your project. You can do this using the following command: +Then add the `fuels` dependency to your project: ::: code-group -```sh-vue [npm] -npm install fuels@{{fuels}} --save +```sh-vue [bun] +bun add fuels@{{fuels}} ``` ```sh-vue [pnpm] pnpm add fuels@{{fuels}} ``` -```sh-vue [bun] -bun add fuels@{{fuels}} +```sh-vue [npm] +npm install fuels@{{fuels}} --save ``` ::: -**Note**: Use version `{{fuels}}` to ensure compatibility with `testnet` network—check the [docs](https://docs.fuel.network/guides/installation/#using-the-latest-toolchain). +Now you are ready to: + +- [Connect to the Network](./connecting-to-network.md) diff --git a/apps/docs/src/guide/getting-started/react-example.md b/apps/docs/src/guide/getting-started/react-example.md new file mode 100644 index 00000000000..d915da5013a --- /dev/null +++ b/apps/docs/src/guide/getting-started/react-example.md @@ -0,0 +1,31 @@ +# React Example + + + +```tsx +import { BN, Provider, Wallet } from "fuels"; +import { useEffect, useState } from "react"; + +function App() { + const [balance, setBalance] = useState(0); + + useEffect(() => { + const main = async () => { + const provider = await Provider.create( + "https://mainnet.fuel.network/v1/graphql", + ); + + const wallet = Wallet.fromAddress("0x...", provider); + const { balances } = await wallet.getBalances(); + + setBalance(new BN(balances[0].amount).toNumber()); + }; + + main(); + }, []); + + return
My Balance: {balance}
; +} + +export default App; +``` diff --git a/apps/docs/src/guide/getting-started/running-local-node.md b/apps/docs/src/guide/getting-started/running-local-node.md new file mode 100644 index 00000000000..caebca0ee53 --- /dev/null +++ b/apps/docs/src/guide/getting-started/running-local-node.md @@ -0,0 +1,46 @@ +# Running a local Fuel node + +Remember to first install the [Fuel Toolchain](https://docs.fuel.network/guides/installation/). + +Then check the command self documentation: + +::: code-group + +```sh-vue [Fuel Binary] +fuel-core +``` + + + +```sh-vue [TS SDK] +fuels node +``` + +::: + +Check also the online docs: + +| | Command | Documentation | +| ----------- | ------------ | ------------------------------------------------------------------------------------------------------ | +| Fuel Binary | `fuel-core` | [docs](https://docs.fuel.network/guides/running-a-node/running-a-local-node/) — Running a local node | +| TS SDK | `fuels node` | [docs](https://docs.fuel.network/docs/fuels-ts/fuels-cli/commands/#fuels-node) — Using the `fuels` CLI | + + + +# Testing Utilities + +You can run a Fuel node from within your `.ts` unit tests: + +- [Launching a test node](../testing/launching-a-test-node.md) + +# Developer Utilities + +Configure your project for the `fuels` CLI using a `fuels.config.ts` file: + +- [Using the `fuels init` command](../fuels-cli/commands.md#fuels-init) + +It makes development easier with a hot-reload experience: + +- [Using the `fuels dev` command](../fuels-cli/commands.md#fuels-dev) diff --git a/apps/docs/src/guide/getting-started/snippets/connecting-to-localnode.ts b/apps/docs/src/guide/getting-started/snippets/connecting-to-network.ts similarity index 55% rename from apps/docs/src/guide/getting-started/snippets/connecting-to-localnode.ts rename to apps/docs/src/guide/getting-started/snippets/connecting-to-network.ts index 32d26a15e26..0d46d510d25 100644 --- a/apps/docs/src/guide/getting-started/snippets/connecting-to-localnode.ts +++ b/apps/docs/src/guide/getting-started/snippets/connecting-to-network.ts @@ -1,12 +1,14 @@ // #region main import { Provider, Wallet } from 'fuels'; -import { LOCAL_NETWORK_URL } from '../../../env'; +const NETWORK_URL = 'https://mainnet.fuel.network/v1/graphql'; +// const NETWORK_URL = 'https://testnet.fuel.network/v1/graphql'; +// const NETWORK_URL = 'https://localhost:/v1/graphql'; const ADDRESS = '0x767caf5b08eba21c561078a4d5be09bbd7f16b9eca22699a61f1edd9e456126f'; -const provider = await Provider.create(LOCAL_NETWORK_URL); +const provider = await Provider.create(NETWORK_URL); const wallet = Wallet.fromAddress(ADDRESS, provider); const { balances } = await wallet.getBalances(); diff --git a/apps/docs/src/guide/getting-started/snippets/connecting-to-testnet.ts b/apps/docs/src/guide/getting-started/snippets/connecting-to-testnet.ts deleted file mode 100644 index c47478ff548..00000000000 --- a/apps/docs/src/guide/getting-started/snippets/connecting-to-testnet.ts +++ /dev/null @@ -1,15 +0,0 @@ -// #region main -import { Provider, Wallet } from 'fuels'; - -const ADDRESS = - '0x767caf5b08eba21c561078a4d5be09bbd7f16b9eca22699a61f1edd9e456126f'; - -const provider = await Provider.create( - 'https://testnet.fuel.network/v1/graphql' -); -const wallet = Wallet.fromAddress(ADDRESS, provider); - -const { balances } = await wallet.getBalances(); - -console.log('Balances', balances); -// #endregion main diff --git a/apps/docs/src/guide/getting-started/usage.md b/apps/docs/src/guide/getting-started/usage.md deleted file mode 100644 index 5e6d24d5962..00000000000 --- a/apps/docs/src/guide/getting-started/usage.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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: - - - -```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://testnet.fuel.network/v1/graphql"); - const myWallet = Wallet.fromAddress("0x...", provider); - myWallet.getBalances().then((data) => { - setBalance(new BN(data[0].amount).toNumber()); - }); - }() - }, []); - - return
My Balance: {balance}
; -} - -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 - -```