feat: fuels CLI

[arboleya]

TL;DR

1. Fast development cycles for Fullstack Fuel dApps via predictable routine automation
2. A watch—>rebuild—>reload approach that's well-known and appreciated for overall Web Development
3. Next Steps:
   • Scaffold CLI tool for creating new projects #1330
     • npm create fuels@latest my-fuel-dapp

Try it out

You can install this PR's release using the tag from this comment:

pnpm add [email protected]
# pnpm add [email protected]...

Essential commands

• fuels init — Creates a new fuels.config.ts file
• fuels build — Build Forc workspace and generate Typescript for everything
• fuels deploy — Deploy Forc workspace locally and save deployed contract IDs in JSON file
• fuels dev — Start a local Fuel node and run build + deploy on every file change

Config File: fuels.config.ts

The fuels CLI uses a fuels.config.ts file for pre-configuring project defaults:

Configure the path to your forc workspace and output dir, and voilà.

import { createConfig } from "fuels";

export default createConfig({
  workspace: "./sway-programs", // Forc workspace
  output: "./src/sway-programs-api", // Where to generate type-safe API
});

/** 
  * Check the docs: 
  * https://fuellabs.github.io/fuels-ts/guide/cli/config-file 
  */ 

Developing

Start developing with a single command:

pnpm fuels dev

Under the hood, the fuels CLI automates all manual tasks during development:

1. Spin up short-lived local Fuel node (fuel-core)
2. Build and deploy all contracts to the local Fuel node (forc)
3. Grab and save their deployed IDs in a <output>/contract-ids.json file
4. Generate Typescript for these contracts in <output>/
5. Watch your Forc workspace for changes, and once they happen:
   1. Re/build and re/deploy all contracts to the local Fuel node
   2. Update [newly] deployed Contract IDs in <output>/contract-ids.json
   3. Re/Generate Typescript for everything
   4. Rinse, repeat

Quick Demo

One-liner showing the basics:

pnpm create next-app --ts --tailwind --eslint --src-dir --app --import-alias=false my-fuel-dapp \
  && cd my-fuel-dapp \
  && pnpm add [email protected] \
  && mkdir ./sway-programs \
  && pnpm fuels forc new sway-programs/contract \
  && pnpm fuels init -c ./sway-programs/contract -o ./src/sway-programs-api \
  && pnpm fuels dev

Documentation

One-liner to check the rendered docs:

git clone [email protected]:FuelLabs/fuels-ts.git --branch aa/feat/fuels-cli fuels-cli-docs \
  && cd fuels-cli-docs \
  && pnpm install \
  && pnpm build \
  && cd apps/docs \
  && pnpm preview

CLI Help screen

pnpm fuels help

Usage: fuels [options] [command]

Options:
  -D, --debug        Enables verbose logging (default: false)
  -S, --silent       Omit output messages (default: false)
  -v, --version      Output the version number
  -h, --help         Display help

Commands:
  init [options]     Create a sample `fuel.config.ts` file
  dev [options]      Start a Fuel node and run build + deploy on every file change
  build [options]    Build Sway programs and generate Typescript for them
  deploy [options]   Deploy contracts to the Fuel network
  typegen [options]  Generate Typescript from Sway ABI JSON files
  versions           Check for version incompatibilities
  core               Wrapper around Fuel Core binary
  forc               Wrapper around Forc binary
  help [command]     Display help for command

Test Coverage

FWIW, all new files should be 100% fully test-covered.

Special Thanks

Goes to @luizstacio ❤️ for the original idea and making this possible via #635.

[github-actions]

This PR is published in NPM with version 0.0.0-pr-1291-20231101155347

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	85.96% (+0.92% 🔼)	5726/6661
🟡	Branches	69.21% (+1.94% 🔼)	845/1221
🟡	Functions	75.79% (+1.26% 🔼)	933/1231
🟢	Lines	85.98% (+0.88% 🔼)	5470/6362

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / logger.ts	100%	100%	100%	100%
🟢	... / index.ts	100%	100%	100%	100%
🟢	... / createConfig.ts	100%	100%	100%	100%
🟢	... / types.ts	100%	100%	100%	100%
🟢	... / index.ts	100%	100%	100%	100%
🟢	... / buildSwayPrograms.ts	100%	100%	100%	100%
🟢	... / findPackageRoot.ts	100%	100%	100%	100%
🟢	... / getBinarySource.ts	100%	100%	100%	100%
🟢	... / generateTypes.ts	100%	100%	100%	100%
🟢	... / forcUtils.ts	100%	100%	100%	100%
🟢	... / index.ts	100%	100%	100%	100%
🟢	... / index.hbs	100%	100%	100%	100%
🟢	... / index.ts	100%	100%	100%	100%
🟢	... / createWallet.ts	100%	100%	100%	100%
🟢	... / deployContract.ts	100%	100%	100%	100%
🟢	... / getDeployConfig.ts	100%	100%	100%	100%
🟢	... / saveContractIds.ts	100%	100%	100%	100%
🟢	... / index.ts	100%	100%	100%	100%
🟢	... / loadConfig.ts	100%	100%	100%	100%
🟢	... / defaultChainConfig.ts	100%	100%	100%	100%
🟢	... / shouldUseBuiltinForc.ts	100%	100%	100%	100%
🟢	... / shouldUseBuiltinFuelCore.ts	100%	100%	100%	100%
🟢	... / validateConfig.ts	100%	100%	100%	100%
🟢	... / withConfig.ts	100%	100%	100%	100%
🟢	... / startFuelCore.ts	100%	100%	100%	100%
🟢	... / index.ts	100%	100%	100%	100%
🟢	... / fuels.config.ts	100%	100%	100%	100%
🟢	... / fuels.config.hbs	100%	100%	100%	100%
🟢	... / withProgram.ts	100%	100%	100%	100%
🟢	... / compareSystemVersions.ts	100%	100%	100%	100%
🟢	... / getBuiltinVersions.ts	100%	100%	100%	100%
🟢	... / fuelUpLink.ts	100%	100%	100%	100%
🟢	... / getSystemVersions.ts	100%	100%	100%	100%
🟢	... / capitalizeString.ts	100%	100%	100%	100%

Test suite run success

1367 tests passing in 248 suites.

Report generated by 🧪jest coverage report action from e356e5b

[danielbate]

🚀