fuels-ts: the fuels CLI, the Provider, and what the npm package is called

The npm package is fuels, the repository is fuels-ts

The install line names a package that does not match the repository:

npm install fuels --save

That difference is not cosmetic. The root package.json is named `fuels-ts`, carries version `0.0.0`, and sets `"private": true`, which marks it as a monorepo root rather than something you install. Working inside this checkout is a different job from consuming the SDK: the tree carries pnpm-workspace.yaml, turbo.json, a packages/ directory, and templates/, so a git clone gives you the build system for the SDK, not a copy of the code your app will run.

Know which of the two you have before you debug anything. If you cloned the repo and your app cannot resolve `fuels`, the problem is the monorepo layout, not a missing dependency.

The network is a string you pass to Provider, and localhost has no URL

Connection is one constructor argument. The example constructs a Provider against a URL, then asks the chain three questions about itself:

import { Provider } from 'fuels';

const NETWORK_URL = 'https://mainnet.fuel.network/v1/graphql';

const provider = new Provider(NETWORK_URL);

const chainId = await provider.getChainId();
const gasConfig = await provider.getGasConfig();
const baseAssetId = await provider.getBaseAssetId();

console.log({ chainId, gasConfig, baseAssetId });

The endpoints are a table of two URLs and a link. Mainnet is `https://mainnet.fuel.network/v1/graphql`, testnet is `https://testnet.fuel.network/v1/graphql`, and the localhost row points at a documentation page about running a local Fuel node rather than at a URL string. So a local development endpoint is not a value the project hands you; you have to take it from the node documentation, and nothing in the example shows a default or a fallback if the string is wrong.

Every call in that snippet is read-only. Chain id, gas config and base asset id are chain metadata, so this part of the SDK answers questions without touching a key.

npm create fuels produces a fullstack dapp directory

Scaffolding is a separate command from installing, and it asks one question:

$ npm create fuels

◇ What is the name of your project? #
│ my-fuel-project
└

⚡️ Success! Created a fullstack Fuel dapp at: my-fuel-project.

The name you type becomes the directory. What lands inside that directory is not shown, and that is the part to check before you commit to it: the word fullstack in the success line tells you the scaffold covers both the contract side and the app side, so a plain TypeScript library consumer gets more structure than they asked for. The command also creates a project rather than adding a dependency to an existing one, which means integrating into a codebase you already have is a manual job.

For an existing repository the lower-level entry point is `fuels init`, which creates a `fuel.config.ts` file and nothing else.

Eight fuels commands, and only half of them stay inside Node

The CLI surface is small enough to read in one screen:

$ npm install fuels --save
$ npm fuels --help

Commands:
  init [options]      Create a sample `fuel.config.ts` file
  build [options]     Build Sway programs and generate Typescript for them
  deploy [options]    Deploy contracts to the Fuel network
  dev [options]       Start a Fuel node with hot-reload capabilities
  node [options]      Start a Fuel node using project configs
  typegen [options]   Generate Typescript from Sway ABI JSON files
  versions [options]  Check for version incompatibilities
  help [command]      Display help for command

Split that list by what it needs. `init`, `typegen`, `versions` and `help` operate on files in your project. `build` is described as building a `forc` workspace, and `dev` and `node` start a Fuel node, so those three reach outside the TypeScript package and into the Fuel toolchain, which is installed from a separate guide. A Node-only environment is enough to read the chain and generate types from ABI JSON; it is not enough to compile Sway or run a local node.

The repository root adds its own floor, node `^20.0.0 || ^22.0.0 || ^24.0.0` with pnpm `^9.4.0` and `packageManager` set to `[email protected]`, in a private manifest that describes the monorepo rather than the published package.

Typegen couples your TypeScript to a Sway compiler version

TypeScript types for a contract are generated, not written. `fuels typegen` produces them from Sway ABI JSON files, and `fuels build` does the same as a side effect of compiling. That is the SDK's central convenience and its central upgrade hazard in one fact: your app's type layer is a build artifact.

The consequences show up in the repository layout. A `snapshots/` directory at the root holds recorded outputs, `templates/` holds the shapes the scaffolder copies, and a `.changeset/` directory holds the pending version bumps, which is how a monorepo like this records what changed before a release. When the SDK version moves, generated types move with it, and any contract you did not touch can produce a different TypeScript signature. A green test run on the old lockfile is not evidence about the new one.

`fuels versions` exists to check for version incompatibilities, which tells you the mismatch is a known state rather than an accident.

The test suite runs twice, in Node and in a browser

One test command would be simpler, and the repository does not have one. The `test` script runs vitest against `vitest.node.config.mts` with the `node` project, `test:browser` runs the same runner against `vitest.browser.config.mts` with the `browser` project, and `test:all` runs both concurrently through `run-p`. Alongside that sit `playwright-tests/` with `playwright.config.ts`, a `vitest.workspace.ts`, and a `.fuel-core/` directory.

For a contributor that means a change can pass in the node project and still fail in the browser project, because the two configs select different environments. A patch validated with only `test` is half a validation. The same split applies to coverage: `test:coverage-merge` and `test:coverage-diff` exist as separate scripts under `scripts/`, which implies the two projects are measured and then combined rather than measured once.

None of this reaches an app that consumes the npm package, but it tells you what the maintainers treat as supported.

Raw private keys sit in named environment slots

The repository's .env.example is short and blunt about what its own tests expect:

DEVNET_WALLET_PVT_KEY=
TESTNET_WALLET_PVT_KEY=
NETWORK_TEST_URL=
NETWORK_TEST_PVT_KEY=
PERFORMANCE_ANALYSIS_TEST_URL=
PERFORMANCE_ANALYSIS_PVT_KEY=

Each network gets its own URL variable and its own key variable, with a `PUBLISHED_NPM_TAG` slot for the release channel. The pattern shows one per environment rather than a single shared key, which is the right shape to copy.

What the listing does not settle is where a key should live in a deployed app. No signer, keystore or hardware-wallet module appears among the root files, and the Fuel Wallet SDK is linked as a separate project from the SDK docs, so the boundary between holding a key and talking to a chain is drawn somewhere this repository does not show. Anyone about to write a deploy script has to make that decision first, because the environment variable pattern above is convenient in development and wrong in production.

Last push 2026-03-27, newest release v0.103.0 from 2026-01-30

The two dates are not the same, and the gap matters. The last push was on 2026-03-27. The newest release is v0.103.0, published on 2026-01-30, after v0.102.0 on 2025-10-31 and v0.101.3 on 2025-07-22. Master is therefore ahead of what npm serves under `fuels`, and a bug fixed on master since January is not in your node_modules.

Every published version sits in the 0.x range, so nothing in the numbering promises a stable interface across a minor bump. The v0.101.3 to v0.102.0 to v0.103.0 sequence also shows roughly three months between releases, which is the cadence to plan around when you schedule SDK bumps in a project.

Licensing is the easy part. The project states `Apache 2.0` as the primary license and points at a LICENSE file in the repository root, which is the permissive grant most integrators expect. Nothing in the visible text restricts commercial use.

Editorial conclusion

Adopt fuels-ts if you are building a dApp on Fuel and want Sway contracts compiled and typed into TypeScript, and prefer it over hand-rolled GraphQL calls because deploy, typegen and a local node are one CLI. Do not adopt it for a read-only chain query, where the GraphQL endpoint alone is enough, or if you need a version that has not moved since 2026-03-27. Verify three things in order: that `npm view fuels version` matches the release your code targets, that the `forc` and Sway versions behind `fuels build` agree with the Sway compiler your contracts are written for, and that the private key your deployment script loads never comes from the environment variables in the repository's own .env.example.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes