IdleKit

Appearance

Installation ​

Not on npm yet

IdleKit is currently developed as a monorepo and its packages are not yet published to npm. The supported workflow today is to work inside the monorepo, where the packages are wired through npm workspaces. The package names and public APIs documented here are the supported surface inside the repo.

Requirements ​

  • Node.js 20+ (the repo is developed on current Node)
  • npm 10+ (workspaces)

Set up the monorepo ​

bash
git clone <your-fork-or-checkout-of-idlekit>
cd idlekit
npm install

Everything is TypeScript source consumed directly (no build step for the packages): games and tests import @idlekitjs/* and Vite/Vitest resolve them to sources via workspace wiring.

Verify the setup:

bash
npm run typecheck   # typecheck every package and game
npm test            # run the full test suite
npm run dev         # start the paperclips example game

Create your own game workspace ​

Games live in games/* and are regular Vite apps. The quickest start is to copy the smallest existing game and rename it:

bash
cp -r games/paperclips games/my-game

Then in games/my-game/package.json, set the name and keep the @idlekitjs/* dependencies you need:

json
{
  "name": "@idlekitjs/my-game",
  "private": true,
  "dependencies": {
    "@idlekitjs/core": "*",
    "@idlekitjs/dom": "*",
    "@idlekitjs/browser": "*",
    "@idlekitjs/economy": "*",
    "@idlekitjs/mechanics": "*",
    "@idlekitjs/plugins": "*",
    "@idlekitjs/storage": "*"
  }
}

Run npm install once at the root so the workspace links, then:

bash
npm run dev -w @idlekitjs/my-game

tsconfig and Vite aliases

Each game maps @idlekitjs/* to package sources in its tsconfig.json and vite.config.ts (so subpaths like @idlekitjs/mechanics/crafting resolve to packages/mechanics/src/crafting/index.ts). Copying an existing game brings that wiring along; adjust only if you move directories around.

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.