IdleKit

Appearance

Installation ​

IdleKit is published on npm as a set of focused packages under the @idlekitjs scope. Install the ones you need with your package manager of choice — IdleKit works with pnpm, npm and Yarn.

Requirements ​

  • Node.js 20+
  • pnpm, npm or Yarn
  • IdleKit is ESM-only (see ESM-only below)

Install a package ​

Every package installs the same way. For example, to add the engine:

bash
pnpm add @idlekitjs/core
bash
npm install @idlekitjs/core
bash
yarn add @idlekitjs/core

Install the common stack ​

A typical browser game composes a few packages — the engine, the economy layer and reusable gameplay mechanics:

bash
pnpm add @idlekitjs/core @idlekitjs/economy @idlekitjs/mechanics
bash
npm install @idlekitjs/core @idlekitjs/economy @idlekitjs/mechanics
bash
yarn add @idlekitjs/core @idlekitjs/economy @idlekitjs/mechanics

Add @idlekitjs/dom, @idlekitjs/browser, @idlekitjs/storage and @idlekitjs/plugins as your game needs rendering, browser frame handling, persistence and engine policies. See the packages overview for what each one does.

@idlekitjs/devtools is private

The development overlay (@idlekitjs/devtools) is not published to npm. It is an internal, development-only package and is not part of the installable public surface.

ESM-only ​

IdleKit ships ES modules only — there is no CommonJS build. That means:

  • Use ESM import syntax, not require.
  • For a standalone Node script, set "type": "module" in your package.json (or use an .mjs file extension).
  • Modern bundlers (Vite, esbuild, Rollup, webpack 5+) consume the packages directly with no extra configuration.
json
{
  "type": "module",
  "dependencies": {
    "@idlekitjs/core": "^0.1.0",
    "@idlekitjs/economy": "^0.1.0",
    "@idlekitjs/mechanics": "^0.1.0"
  }
}

What to import from where ​

All imports go through public package entry points — the root barrel or a documented subpath:

ts
import { createEngine, SaveManager } from "@idlekitjs/core";
import { Renderer, bindText } from "@idlekitjs/dom";
import { createRafScheduler } from "@idlekitjs/browser/raf-scheduler";
import { createEconomy, stateKey } from "@idlekitjs/economy";
import { producers } from "@idlekitjs/mechanics/producers";
import { economyPurchase } from "@idlekitjs/mechanics/producers/economy";
import { crafting } from "@idlekitjs/mechanics/crafting";
import { boosts } from "@idlekitjs/mechanics/boosts";
import { autosave } from "@idlekitjs/plugins/autosave";
import { pageLifecycle } from "@idlekitjs/browser/page-lifecycle";
import { LocalStorageAdapter } from "@idlekitjs/storage/local-storage";

Never import a module's internal files (@idlekitjs/mechanics/crafting/extension is not public API). See module conventions.

Next ​

Head to the quickstart to build a running game.