Skip to main content
The achievements-manager library is distributed as two separate npm packages, depending on whether you’re using React or another framework.

​
Which Package Do I Need?

achievements-react

For React 19+ applicationsIncludes the core engine plus React Provider, hooks, and factory. This is the only package you need for React projects.

achievements

For everything elseFramework-agnostic core engine for vanilla JS, Vue, Svelte, server-side, or any non-React environment.
If you’re in a React app, install achievements-react - it includes the core. If you’re working outside React (vanilla JS, a server, Svelte, Vue…) install achievements directly.

​
Installing for React

For React 19+ applications, install the achievements-react package: 
npm install achievements-react

​
Peer Requirements

The React package requires React >= 19.0.0 as a peer dependency. The achievements core is bundled - no separate install needed.
package.json
{
  "dependencies": {
    "achievements-react": "^0.3.0",
    "react": "^19.0.0"
  }
}

​
Installing for Vanilla JS / Other Frameworks

For vanilla JavaScript, Vue, Svelte, or any other framework, install the core achievements package: 
npm install achievements

​
Zero Dependencies

The core package has zero runtime dependencies. It ships only ESM format and requires a modern bundler or environment that supports ES modules.
package.json
{
  "dependencies": {
    "achievements": "^0.3.0"
  }
}

​
TypeScript Support

Both packages are written in TypeScript and ship with complete type definitions. No additional @types packages are needed.
tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2020"
  }
}
The library uses literal type inference to derive your achievement IDs from definitions, giving you autocomplete and type safety with zero boilerplate.

​
Package Exports

Both packages use modern ESM exports:

​
achievements (core)

import {
  createAchievements,
  defineAchievements,
  localStorageAdapter,
  inMemoryAdapter,
  fnv1aHashAdapter,
  type AchievementDef,
  type AchievementState,
  type AchievementEngine,
  type StorageAdapter,
  type HashAdapter,
} from "achievements";

​
achievements-react

import {
  // Factory & components
  createAchievements,
  AchievementsProvider,
  
  // Hooks
  useAchievements,
  useIsUnlocked,
  useProgress,
  useAchievementToast,
  useUnlockedCount,
  useTamperDetected,
  
  // Re-exported from core
  defineAchievements,
  localStorageAdapter,
  inMemoryAdapter,
  fnv1aHashAdapter,
  
  // Types
  type AchievementDef,
  type AchievementState,
  type AchievementEngine,
  type StorageAdapter,
  type HashAdapter,
  type AchievementsConfig,
} from "achievements-react";
achievements-react re-exports everything from achievements, so you rarely need to import from two packages.

​
Verifying Installation

After installation, verify the packages are available: 
import { createAchievements } from "achievements-react";
console.log(typeof createAchievements); // "function"

​
Next Steps

Quick Start

Get up and running with a complete working example for React and vanilla JavaScript

Build docs developers (and LLMs) love

Get started for freeTalk to us