Guide · Open source
How to use fp-ts: install, core types and tips
Updated · written with AI from the project's own documentation and checked against our catalogue data
fp-ts is an MIT-licensed TypeScript library that provides functional programming building blocks such as Option, Either, IO, Task, and the Functor, Applicative and Monad abstractions. This guide shows how to install it, check your setup, and where the core types fit. It is written for developers who already know functional programming, because the project's own docs assume that knowledge.
fp-tsgcanti/fp-ts · ★ 11.5k · MIT Install options & downloads Quick start
- 1Check your TypeScript version. Confirm you have TypeScript 3.5 or newer and that strict mode is enabled.
- 2Install fp-ts. Run npm install fp-ts in your project directory.
- 3Check for a single version. Run npm ls fp-ts and confirm there is one version, with others marked deduped.
- 4Read the module docs. Open the module page for the type you need, such as Option or Either, on the official docs site.
- 5Decide on Effect-TS for new work. If you are starting a new project, review the README announcement and the Effect-TS documentation before committing.
Check the prerequisites before you install
You need Node.js and npm, plus TypeScript 3.5 or newer. The library is designed to be consumed with the strict flag turned on in TypeScript.
The README's compatibility table lists the required TypeScript version for each fp-ts line. Version 2.0.x requires TypeScript 3.5 or newer, and version 1.15.x requires 3.1 or newer.
- Node.js and npm installed
- TypeScript 3.5 or newer for fp-ts 2.0.x
- TypeScript configured with strict mode enabled
Install fp-ts with npm
Install the stable version with npm from your project directory.
npm install fp-tsKeep a single fp-ts version in your project
Make sure only one version of fp-ts is installed. The README notes that multiple versions are known to cause tsc to hang during compilation.
To check installed versions, run npm ls fp-ts. There should be a single version, and any others should be marked as deduped.
npm ls fp-tsLearn the core types: Option, Either, IO and Task
fp-ts includes the most popular data types and abstractions from functional languages. Option and Either are typed ways to handle missing values and errors, which the README highlights as a common use case. IO and Task describe effectful computations. Functor, Applicative and Monad are the type classes that connect them.
Each of these has its own module page in the official docs at gcanti.github.io/fp-ts. Read the module for the type you need rather than trying to learn the whole library at once.
- Option: a value that may be absent
- Either: a value that is either an error or a success
- IO: a computation that performs side effects when run
- Task: an asynchronous computation
- Functor, Applicative, Monad: abstractions for composing these types
Know what fp-ts does that other libraries do not
The README describes one distinctive feature: fp-ts implements Higher Kinded Types, which TypeScript does not support natively. This is what lets the library express type classes like Functor and Monad generically.
The project is inspired by Haskell, PureScript and Scala, so readers who know those languages will recognise many of the patterns.
Decide whether to start a new project with fp-ts
The README announces that fp-ts is merging into the Effect-TS ecosystem. It states that Effect-TS can be regarded as the successor to fp-ts v2 and embodies what would be considered fp-ts v3.
For that reason, new projects that want the newest direction should look at Effect-TS first. Teams that already depend on fp-ts can keep using it. The README also points to the announcement and to effect.website for Effect-TS documentation.
Find help and documentation
The official docs are at gcanti.github.io/fp-ts, with a learning resources page and an ecosystem page. The API reference for version 2.x is listed as current, and version 1.x is documented separately.
For questions, the README links to a Discord server and to the #fp-ts channel on the FP Slack. The docs say teaching functional programming is out of scope, so beginners may need outside material first.
What people use it for
- Modelling a value that may be missing with Option instead of null checks
- Handling errors as typed values with Either
- Describing async work with Task and side effects with IO
- Maintaining an existing codebase that already depends on fp-ts
Frequently asked questions
Is fp-ts free to use?
Yes. fp-ts is released under the MIT License, as stated in the README's license section.
What do I need to install fp-ts?
You need Node.js and npm, plus TypeScript 3.5 or newer for fp-ts 2.0.x. The library is designed for TypeScript with strict mode enabled.
How do I install fp-ts?
Run npm install fp-ts in your project. The README gives this as the command for the stable version.
Why does my TypeScript compile hang with fp-ts?
The README says multiple versions of fp-ts are known to cause tsc to hang. Run npm ls fp-ts and make sure there is a single version, with any others marked deduped.
Is fp-ts still recommended for new projects?
The README points new users to Effect-TS, which it describes as the successor to fp-ts v2. Check that announcement before starting a new project on fp-ts.
What are alternatives to fp-ts?
The project lists Effect, purify-ts, neverthrow and ramda as comparable projects. Effect is the direction the README points to for new work.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
fp-ts suits experienced functional programmers who use strict TypeScript and want Option, Either and related abstractions, or who maintain code that already uses it. Beginners, and teams starting new projects who want the newest direction, should look at Effect-TS, which the README names as fp-ts's successor, or at the other comparable libraries listed in the project.
Install options & downloads