fuels-ts: The TypeScript SDK for Building on Fuel
GitHub describes it as Fuel Network Typescript SDK. The repository metadata lists TypeScript as its primary language. The metadata lists the Apache-2.0 license. This article stays within the project description and details documented in the GitHub repository README.
At a glance
- What is it?
- fuels-ts is the official TypeScript SDK for the Fuel network, bundling a provider, wallet, and CLI to build, deploy, and interact with Sway contracts. It is a pragmatic choice for TypeScript developers targeting Fuel, but its version churn and tight coupling to the Fuel toolchain demand careful planning.
- Who is it for?
- Adopt fuels-ts if you are a TypeScript developer building a dApp on the Fuel network and want a single SDK that covers provider, wallet, and contract interaction, plus a CLI to generate types and manage deployments. Avoid it if you need a stable, long-lived API or plan to target multiple chains, as the SDK's API changes frequently and is tightly coupled to Fuel's Sway and forc toolchain.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 16 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.
Star history
- FuelLabs/fuels-ts42,898 ★ · -140
| Repository | 2026-08-13 | 2026-11-13 |
|---|---|---|
| FuelLabs/fuels-ts | 43k | 42.9k |
-140 Stars in the last 92 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What fuels-ts Solves and Who It Is For
fuels-ts addresses the gap between writing Sway smart contracts and building a web frontend that talks to them. The Fuel network uses its own virtual machine and a GraphQL API, so generic Ethereum libraries like ethers.js do not work. This SDK provides a TypeScript-first interface to that API, plus a CLI that turns Sway ABI JSON into typed classes. It is aimed at developers who want to build a full-stack dApp without writing raw GraphQL queries or hand-rolling type definitions. The README's `npm create fuels` command scaffolds a complete project, which suggests the intended user is someone starting a new Fuel dApp, not someone integrating Fuel into an existing large codebase.
How It Works: Provider, Wallet, and CLI Architecture
The SDK is structured around a few core pieces. The `Provider` class connects to a Fuel node via a GraphQL endpoint, as shown in the README's example where `new Provider(NETWORK_URL)` is used to fetch chain ID, gas config, and base asset ID. This provider is the entry point for all network interactions. The `fuels` package also includes wallet functionality, though the README does not detail it. The CLI is a separate layer: it reads a `fuel.config.ts` file, builds Sway programs with `forc`, generates TypeScript types from the ABI, deploys contracts, and saves their IDs to a JSON file. The `fuels dev` command starts a local node with hot-reload, which ties the development loop together. The data flow is: write Sway, run `fuels build` to compile and generate types, then use those types in your application code with the provider to call contracts. This is a code-generation approach, not a runtime reflection approach, which means type safety is baked in at compile time.
Getting Started: Install and First Commands
Installation is straightforward: `npm install fuels --save`. The README shows connecting to a network by creating a `Provider` with a URL like `https://mainnet.fuel.network/v1/graphql` or the testnet equivalent. For a local node, it points to a guide for running a local Fuel node. To scaffold a new dApp, you run `npm create fuels` and answer a prompt for the project name, which produces a fullstack project. The CLI offers seven commands: `init`, `build`, `deploy`, `dev`, `node`, `typegen`, and `versions`. The `init` command creates a sample `fuel.config.ts`; `build` compiles Sway and generates TypeScript; `deploy` pushes contracts and records their IDs; `dev` starts a node with hot-reload; `node` starts a node using project configs; `typegen` generates types from ABI JSON files; and `versions` checks for version incompatibilities. The `versions` command is notable because it acknowledges the risk of mismatched toolchain versions, which is a real concern given the SDK's rapid release cycle.
Limitations and Failure Modes
The most obvious limitation is the SDK's version velocity. The recent releases show v0.103.0 in January 2026, v0.102.0 in October 2025, and v0.101.3 in July 2025. That is two minor-version bumps in about six months, and anything before 1.0 can change its API without a major version warning. Anyone who builds on this SDK must budget for frequent migration work. The README's `versions` command exists precisely because mismatched versions of the SDK, forc, and the node can cause subtle failures. Another limitation is that the SDK is Fuel-specific. It does not abstract over other chains, so if your project needs to support Ethereum or another network, you will need a separate SDK and a different data model. The CLI also assumes you are using Sway and forc; if your contracts are written in another language, or you prefer a different build system, the `fuels build` and `typegen` commands will not help you.
Alternative: fuels-rs and Direct GraphQL
The main alternative is the Rust SDK, `fuels-rs`, which the README links to. The difference is not just language but approach: `fuels-rs` is for backend or off-chain services written in Rust, where you might want lower-level control and better performance for heavy contract interaction. It uses the same underlying GraphQL API, but it does not offer the same `npm create fuels` scaffolding or the TypeScript type generation that makes the TS SDK convenient for frontend work. If you are building a web app, `fuels-rs` is not a drop-in replacement; you would have to write your own backend and expose an API to the frontend. Another alternative is to skip the SDK entirely and talk to the Fuel GraphQL endpoint directly with a generic GraphQL client. That gives you full control but forces you to hand-write queries for every contract call and manage serialization and error handling yourself. For a simple read-only use case, that might be viable, but for any real dApp, the SDK's type generation and wallet integration save significant effort.
Maintenance and Upgrade Cost
The maintenance cost is tied to the SDK's pre-1.0 status. Each minor release can introduce breaking changes, as the version numbers suggest. The repository has a CHANGELOG.md, and the `versions` command implies that the team expects users to check compatibility between the SDK, forc, and the node. Upgrading likely involves running `fuels versions`, updating the SDK and possibly the Sway toolchain, and then regenerating types. The CLI's `build` and `typegen` commands are idempotent in principle, but you will need to re-run them after upgrading to pick up new type definitions. The license is Apache-2.0, which is permissive and allows commercial use, modification, and distribution, with no copyleft obligations. That is a low legal barrier for adoption, but it does not reduce the technical upgrade burden. There is no indication of a long-term support (LTS) policy, so you should treat every release as a potential breaking change until the project reaches 1.0.
Who Should Adopt It and What to Verify First
This SDK is the right fit for a team that is committed to the Fuel ecosystem and wants to move fast with a scaffolded fullstack setup. The `npm create fuels` command is a strong onboarding tool, and the CLI's hot-reload `dev` mode suggests a productive local development loop. But it is a poor fit for a team that needs API stability, because the pre-1.0 versioning means you cannot pin to a minor release and expect it to remain compatible with the network. Before adopting, verify that your target Fuel network version matches the SDK version you plan to use. Run `fuels versions` after installation to see if the toolchain is compatible. Also, test the `typegen` command against your own Sway ABI files, because the generated types are only as good as the ABI parser. If you are building a production system, plan to lock the SDK version and budget for regular upgrades, or consider the Rust SDK if your workload is backend-heavy and you can tolerate a different development flow.
Editorial conclusion
Adopt fuels-ts if you are a TypeScript developer building a dApp on the Fuel network and want a single SDK that covers provider, wallet, and contract interaction, plus a CLI to generate types and manage deployments. Avoid it if you need a stable, long-lived API or plan to target multiple chains, as the SDK's API changes frequently and is tightly coupled to Fuel's Sway and forc toolchain. Before committing, verify the current version's breaking changes against your existing code, check the changelog for migration guides, and test the CLI's typegen and build commands with a sample contract to ensure your workflow matches the expected config.
Frequently asked questions
Which npm package do I install for fuels-ts?
Install `fuels`. The repository's root package.json is named `fuels-ts`, carries version `0.0.0` and sets `"private": true`, so it is a monorepo root rather than the published artifact.
What Node version does fuels-ts need?
The repository root package.json sets engines to node `^20.18.0 || ^22.0.0 || ^24.0.0` and pnpm `^9.4.0`, with `packageManager` set to `[email protected]`. That manifest is private, so it describes the monorepo rather than the published package.
Does the fuels CLI need the Fuel toolchain to run?
Some of its commands do. `fuels build` is described as building a `forc` workspace, and `fuels dev` and `fuels node` start a Fuel node, while `fuels init`, `fuels typegen`, `fuels versions` and `fuels help` work on files inside Node. The Fuel toolchain has its own installation guide linked separately from the SDK docs.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/fuellabs-fuels-ts)Star history chart for your README
[](https://hysenlabs.com/projects/fuellabs-fuels-ts)Was this useful?