Development

Development

npm workspaces monorepo. Node 20.19 or newer. Run everything from the repo root.

git clone https://github.com/BaryoDev/dopaminejs.git
cd dopaminejs
npm ci

Commands

npm test                 # vitest, in the Asia/Manila timezone
npm test -- tests/RewardSystem.test.js -t "streak"
npm run test:watch
npm run typecheck        # tsc over types/ and type-tests/
npm run build            # every package
npm run size             # needs a build first
npm run check-zero-deps
node scripts/check-versions.js --dist   # needs a build first
npm run dev              # vite dev server for the core

CI runs all of the checks on Node 20.19 and 22.12, plus npm audit --omit=dev --audit-level=high. Run them all before calling a change done.

Layout

packages/
  dopaminejs/                 core, MPL-2.0
    src/
      index.js                public exports
      engine.js               the dopaminejs/engine entry
      dopamine/               RewardSystem, DataService, GameUI,
                              ParticleSystem, SoundManager, the facade
      core/                   kernel, EventBus, registries, Game, Scene,
                              GameObject, Component, Collider
      systems/                Ticker, Physics, Input, Loader, Director
      renderer/               Canvas 2D renderer
    types/index.d.ts          hand-written declarations
    type-tests/               compile-time checks of the declarations
    tests/                    every test, including plugin and React tests
  dopaminejs-react/           MIT
  dopaminejs-themes/          MIT
  plugin-*/                   MIT, published as dopaminejs-plugin-*
scripts/                      test runner, version checks, publish

The source is plain JavaScript with JSDoc. All tests live in packages/dopaminejs/tests/. A vite alias maps dopaminejs to the core source, so plugin sources are tested without a build.

Why the tests pin a timezone

Streaks use local calendar dates. A bug that mixes local and UTC dates cannot be seen on a machine that runs in UTC, which is what CI does by default. scripts/run-tests.js starts vitest with TZ=Asia/Manila so that kind of bug fails. Override it with DOPAMINE_TEST_TZ.

Rules

• The public API is snapshot tested. tests/publicApi.test.js compares each package's exports with tests/approved-api/*.approved.txt. An intended change updates the approved file in the same commit.
• The declarations match the exports. tests/types.test.js fails when types/index.d.ts declares something that is not exported, or misses something that is.
• No runtime dependencies in the core. npm run check-zero-deps.
• Size budget. The ESM and CJS entries each stay under 14 KB.
• Streak dates are local calendar dates, never UTC.
• Look up by own property. Game names, achievement ids and sound keys come from callers.
• Saved state is untrusted. Anything read from storage goes through RewardSystem._migrate.
• achievement.icon is HTML on purpose. Every other field is text.
• Whatever adds a listener, timer or DOM node removes it in destroy(), and a test proves it.
• The v1 globals stay until a major version.

Style: 4-space indent, semicolons, single quotes, underscore prefix for private members, one class per file. Comments say why, not what.

Commits and pull requests

Short imperative subject in plain words, for example "stop the ticker loop dying on one bad callback". A body only when the reason is not clear from the diff.

The repo has a pull request template. Say what changed and show the proof: the test that fails without the change, or the command output.

Contributing

Comment /take on an issue to assign it to yourself. Changes to the public API need the approved-API file and the type declarations updated in the same pull request.

Releases

See Releasing.