Skip to main content
achievements is a small, framework-agnostic library for adding achievements to any web application. You define your achievements once; the engine handles persistence, progress, auto-unlock, and notifications.

​
What is achievements-manager?

achievements-manager is a type-safe achievement tracking SDK that provides a tiny core with optional React bindings. It’s designed to add gamification features to your web applications with minimal overhead and maximum type safety.

Two Packages, One System

  • achievements: Framework-agnostic core engine (zero dependencies)
  • achievements-react: React 19+ bindings with hooks and factory

​
Key Features

Zero Runtime Dependencies

The core ships nothing but your own code - no external dependencies to bloat your bundle.

Type-Safe IDs

Your ID union is inferred from definitions; typos become compile errors automatically.

Auto-Unlock

Progress-based achievements unlock themselves when the threshold is reached.

Anti-Cheat

Stored data is integrity-checked on every load (FNV-1a by default, pluggable).

Tamper Response

Know immediately when localStorage has been edited and respond accordingly.

Pluggable

Swap storage (localStorage, in-memory, your own) and hash adapters at will.

React-Ready

Fine-grained hooks that only re-render the components that need to.

Framework-Agnostic

Use with vanilla JS, Vue, Svelte, or any framework - the core is universal.

​
When to Use This Library

The achievements-manager library is perfect for:
  • Web applications that need gamification features
  • Progressive web apps with achievement systems
  • SaaS products tracking user milestones
  • Educational platforms rewarding learning progress
  • Analytics dashboards celebrating user engagement
  • Developer tools tracking usage patterns
If you need a lightweight, type-safe solution for tracking user achievements without pulling in heavy dependencies, this library is built for you.

​
How It Works

The engine is a plain TypeScript object. No framework, no context, no magic. You configure it once with your definitions and call methods like unlock(), setProgress(), or collectItem() from wherever it makes sense in your app. 
import { createAchievements, localStorageAdapter } from "achievements";

const engine = createAchievements({
  definitions: [
    { id: "first-visit", label: "First Visit", description: "Open the app." },
    { id: "click-frenzy", label: "Click Frenzy", description: "Click 50 times.", maxProgress: 50 },
  ],
  storage: localStorageAdapter("my-app"),
});

engine.unlock("first-visit");
engine.incrementProgress("click-frenzy"); // auto-unlocks at 50
Persistence, progress tracking, anti-cheat, and toast queuing are all handled internally.

​
Architecture

1

Define Achievements

Use defineAchievements() to create your achievement definitions with full type inference.
2

Create Engine

Call createAchievements() with your definitions, storage adapter, and optional callbacks.
3

Track Progress

Use methods like unlock(), setProgress(), or collectItem() to update achievement state.
4

Respond to Events

Subscribe to state changes or use React hooks for automatic UI updates.

​
Bundle Size

The core library has zero runtime dependencies and ships as a tiny ESM module. React bindings add minimal overhead for context and hooks.
For React applications, install achievements-react - it includes the core automatically. For other frameworks or vanilla JS, install achievements directly.

​
Next Steps

Installation

Install the library for React or vanilla JavaScript

Quick Start

Get up and running with a working example in minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us