Get started with the library

This guide will help you get started with the Evolu Library.

Installation

npm install @evolu/common

Polyfills

Evolu uses JavaScript explicit resource management, which Safari does not support yet, so call installPolyfills during app startup before using Evolu.

import { installPolyfills } from "@evolu/common/polyfills";
installPolyfills();

For React Native apps, use @evolu/react-native/polyfills instead.

Learning path

We recommend learning the Evolu Library in this order:

1. Array

Start with Array, which provides helpers for improved type-safety and developer experience.

2. Result

Learn Result, a type-safe way to handle errors. It's the foundation for composable error handling.

3. Dependency injection

Explore dependency injection, the pattern Evolu uses to swap implementations and simplify testing.

4. Resource management

See resource management — using, DisposableStack, and how it integrates with Result.

5. Task

Continue with Task for JavaScript-native structured concurrency (promises that can be aborted, monitored, and more).

6. Type

Check the Type to enforce constraints at compile-time and validate data at runtime.

7. Conventions

Review the Evolu conventions to understand the codebase style and patterns.

8. Testing

Learn how to test Evolu code with dependency injection, deterministic test dependencies, and Task-aware helpers.

Exploring the API

After understanding the core concepts, explore the full API in the API reference. All code is commented, and tests are written to be read as examples—they demonstrate practical usage patterns and edge cases.