From 2ae1f8b3dbc5e91b055070f508c578da120eb1e5 Mon Sep 17 00:00:00 2001 From: Dhaiwat Date: Fri, 12 Apr 2024 17:37:16 +0530 Subject: [PATCH] docs: add `create-fuels` CLI docs under tooling (#2030) --- .changeset/two-crabs-switch.md | 4 + apps/docs/.vitepress/config.ts | 11 +- apps/docs/src/guide/cli/npm-create-fuels.md | 81 ------------- apps/docs/src/guide/npm-create-fuels/index.md | 113 ++++++++++++++++++ .../src/guide/npm-create-fuels/options.md | 51 ++++++++ 5 files changed, 177 insertions(+), 83 deletions(-) create mode 100644 .changeset/two-crabs-switch.md delete mode 100644 apps/docs/src/guide/cli/npm-create-fuels.md create mode 100644 apps/docs/src/guide/npm-create-fuels/index.md create mode 100644 apps/docs/src/guide/npm-create-fuels/options.md diff --git a/.changeset/two-crabs-switch.md b/.changeset/two-crabs-switch.md new file mode 100644 index 0000000000..82d950f83f --- /dev/null +++ b/.changeset/two-crabs-switch.md @@ -0,0 +1,4 @@ +--- +--- + +docs: add `create-fuels` CLI docs under tooling diff --git a/apps/docs/.vitepress/config.ts b/apps/docs/.vitepress/config.ts index 9613c6181e..61d3b160e7 100644 --- a/apps/docs/.vitepress/config.ts +++ b/apps/docs/.vitepress/config.ts @@ -384,7 +384,7 @@ export default defineConfig({ { text: 'Unit conversion', link: '/guide/utilities/unit-conversion', - } + }, ], }, { @@ -455,7 +455,14 @@ export default defineConfig({ items: [ { text: 'npm create fuels', - link: '/guide/cli/npm-create-fuels', + link: '/guide/npm-create-fuels/', + collapsed: true, + items: [ + { + text: 'Options', + link: '/guide/npm-create-fuels/options', + }, + ], }, { text: 'fuels', diff --git a/apps/docs/src/guide/cli/npm-create-fuels.md b/apps/docs/src/guide/cli/npm-create-fuels.md deleted file mode 100644 index cb682c1386..0000000000 --- a/apps/docs/src/guide/cli/npm-create-fuels.md +++ /dev/null @@ -1,81 +0,0 @@ -# npm create fuels - -You can quickly bootstrap a full-stack Fuel project locally with the following command: - -::: code-group - -```sh [pnpm] -pnpm create fuels - -# or, if you want to pass in your preferences directly from the command line: -pnpm create fuels [project-name] [options] - -# eg. pnpm create fuels my-fuel-project --pnpm --contract --predicate -# Note: project-name and all other options are optional -Options: - -V, --version output the version number - -c, --contract Include contract program - -p, --predicate Include predicate program - -s, --script Include script program - --pnpm Use pnpm as the package manager - --npm Use npm as the package manager - -cs, -cp, -sp, -cps Shorthand to include combination of contract, script and predicate programs - --verbose Enable verbose logging - -h, --help Display help for command -``` - -```sh [npm] -npm create fuels - -# or, if you want to pass in your preferences directly from the command line: -npm create fuels [project-name] [options] - -# eg. npm create fuels my-fuel-project --pnpm --contract --predicate -# Note: project-name and all other options are optional -Options: - -V, --version output the version number - -c, --contract Include contract program - -p, --predicate Include predicate program - -s, --script Include script program - --pnpm Use pnpm as the package manager - --npm Use npm as the package manager - -cs, -cp, -sp, -cps Shorthand to include combination of contract, script and predicate programs - --verbose Enable verbose logging - -h, --help Display help for command -``` - -::: - -This will setup a new full-stack Fuel project. To get things running, you'll need to install the dependencies and start the development servers: - -::: code-group - -```sh [pnpm] -# Start a local Fuel node and hot-reload for your Sway smart contracts -pnpm fuels:dev -``` - -```sh [npm] -# Start a local Fuel node and hot-reload for your Sway smart contracts -npm run fuels:dev -``` - -::: - -In another terminal window, start the frontend dev server: - -::: code-group - -```sh [pnpm] -pnpm dev -``` - -```sh [npm] -npm dev -``` - -::: - -Your app should now be running on `localhost:3000`. - -Any changes you make to your Sway smart contracts will be hot-reloaded and reflected in the frontend. All of this is enabled thanks to the new [fuels CLI](../fuels/index.md). The fuels CLI has several more powerful customization options that will let you tweak your local dev experience to your liking. diff --git a/apps/docs/src/guide/npm-create-fuels/index.md b/apps/docs/src/guide/npm-create-fuels/index.md new file mode 100644 index 0000000000..1e2e63918a --- /dev/null +++ b/apps/docs/src/guide/npm-create-fuels/index.md @@ -0,0 +1,113 @@ +# npm create fuels + +`npm create fuels` is a command line tool that helps you scaffold a new full-stack Fuel dApp. + +## Getting Started + +Run the following command in your terminal to get started: + +::: code-group + +```sh [npm] +npm create fuels +``` + +```sh [pnpm] +pnpm create fuels +``` + +::: + +You will be greeted with a few simple questions about your project. Answer them as you see fit. + +```md +◇ What is the name of your project? +│ my-fuel-project +│ +◇ Select a package manager: +│ pnpm +│ +◆ Which Sway programs do you want? (space to toggle) +│ ● Contract +│ ○ Predicate +│ ○ Script +└ +``` + +The tool will then scaffold the project and install the necessary dependencies for you. The project's directory structure will look something like this: + +```md +my-fuel-project +├── src +│ ├── pages +│ │ ├── index.tsx +│ │ └── ... +│ ├── components +│ │ └── ... +│ ├── styles +│ │ └── ... +│ └── lib.ts +├── public +│ └── ... +├── sway-programs +│ ├── contract +│ │ └── src +│ │ └── main.sw +│ ├── Forc.lock +│ └── Forc.toml +├── fuels.config.ts +├── package.json +└── ... +``` + +The most important file in this setup is the `./fuels.config.ts` file, which contains information about your Sway contracts, your local Fuel node, and where your TypeScript types are generated. You can read more about this file in the [Fuels CLI documentation](../fuels/config-file.md). + +The `sway-programs` directory contains your Sway programs. + +The `src` directory contains your frontend code. + +## Running the Project + +To run your new full-stack Fuel dApp, you will need to start two processes: + +### 1. The `fuels:dev` process + +This process will start a local Fuel node on your machine, and keep watch for any changes you make to your Sway smart contracts. Whenever you make a change, the node will automatically rebuild and deploy your contracts to the local Fuel node. It will also automatically keep generating TypeScript types for your contracts, so that you can use them in your frontend code. + +To start the `fuels:dev` process, run the following command in your terminal: + +::: code-group + +```sh [npm] +npm run fuels:dev +``` + +```sh [pnpm] +pnpm fuels:dev +``` + +::: + +### 2. The Frontend Dev Server + +To run your frontend dev server, run the following command in your terminal: + +::: code-group + +```sh [npm] +npm run dev +``` + +```sh [pnpm] +pnpm dev +``` + +::: + +Your frontend should now be running at `http://localhost:3000`. + +--- + +You should now have a local full-stack Fuel development environment that looks like this: + +![Fullstack Fuel Dev Workflow](../../public/creating-a-fuel-dapp-create-fuels-split-view.png) diff --git a/apps/docs/src/guide/npm-create-fuels/options.md b/apps/docs/src/guide/npm-create-fuels/options.md new file mode 100644 index 0000000000..4f508d432b --- /dev/null +++ b/apps/docs/src/guide/npm-create-fuels/options.md @@ -0,0 +1,51 @@ +# Options + +The `npm create fuels` command has several command-line options that you can use to customize your project. + +::: code-group + +```sh [pnpm] +pnpm create fuels [project-name] [options] +``` + +```sh [npm] +npm create fuels [project-name] [options] +``` + +::: + +## `-c, --contract` + +Notifies the tool to include a Sway contract program in your project. + +## `-p, --predicate` + +Notifies the tool to include a Sway predicate program in your project. + +## `-s, --script` + +Notifies the tool to include a Sway script program in your project. + +## `--pnpm` + +Notifies the tool to use pnpm as the package manager to install the necessary dependencies. + +## `--npm` + +Notifies the tool to use npm as the package manager to install the necessary dependencies. + +## `-cs, -cp, -sp, -cps` + +Shorthand to include a combination of contract, script and predicate programs. + +## `--verbose` + +Enables verbose logging. Useful when debugging issues with the tool. + +## `-h, --help` + +Displays a help message with all available options. + +## `-V, --version` + +Displays the version number of the `npm create fuels` command.