Getting started with FS2, the functional streaming library for Scala, requires understanding the ecosystem and the specific steps needed to integrate it into your project. FS2 is built on top of Cats Effect and provides a powerful, purely functional way to handle streams of data, whether they come from files, network sockets, or in-memory collections. This guide walks through the practical methods of acquiring and setting up FS2 for your next Scala application.
Understanding the FS2 Ecosystem
Before diving into the installation, it is important to recognize that FS2 is not a standalone library; it is deeply integrated with the Typelevel ecosystem. It relies on Cats Core and Cats Effect for its foundational abstractions, such as `IO` and `Resource`. Therefore, adding FS2 to your build automatically pulls in these essential dependencies, ensuring a consistent and type-safe foundation for your streaming logic.
Dependency Management with SBT
The most common way to obtain FS2 is through sbt, the standard build tool for Scala. You will need to add the appropriate module to your `build.sbt` file. Because FS2 is organized into separate modules for different functionalities, you should choose the one that matches your needs to avoid unnecessary bloat.
Core Library Setup
For the majority of users, starting with the core module is recommended. This provides the core combinatorics for streams and `IO` integration. Add the following dependency to your `build.sbt` file, replacing `X` with the desired version compatible with your Scala version:
libraryDependencies += "org.typelevel" %% "fs2-core" % "3.11.0"
Acquiring the Entire Suite
If your project requires advanced features like JSON parsing, gRPC integration, or reactive streams compatibility, you will likely need the full suite of FS2 libraries. These modules build upon the core and provide specialized connectors for various technologies. The version numbers across all FS2 modules must match to ensure compatibility.
Version Coordination
Managing multiple dependencies can be tricky, but sbt simplifies this with the `fs2-recommended` BOM (Bill of Materials). By importing this BOM, you guarantee that all FS2 modules and their transitive dependencies align perfectly, eliminating version conflicts and saving you hours of debugging.
libraryDependencies += "org.typelevel" %% "fs2-recommended" % "3.11.0"
Using Mill and Maven
While sbt is prevalent, FS2 is also accessible to users of other build systems. For Mill, the dependency syntax is concise and mirrors the sbT approach. Maven users, common in enterprise environments, can include the core artifact in their `pom.xml`. The group ID is `org.typelevel`, and the artifact ID varies based on the specific module required.
Setting Up the Development Environment
After successfully adding the dependency, refreshing your build configuration will download the necessary artifacts. Once resolved, you can begin writing your first stream. You will import `fs2.Stream` and `cats.effect.IO`. The REPL becomes a valuable tool for experimenting with basic combinators like `covary` and `compile`, allowing you to validate your setup without running a full application.
