Get started with the library

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

Installation

npm install @evolu/common

Polyfills

Evolu uses modern JavaScript APIs that are not available in every supported runtime. 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 Evolu builds on them with disposable, Task and Run, and shared resources.

5. Type

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

6. Task

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

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.