CONTRIBUTING.md

Contributing to melonJS

melonJS is a community-driven project that has been shaped by contributors from around the world since 2011. Whether you're fixing a bug, adding a feature, improving the documentation, or simply helping others on Discord — every contribution matters and helps make the engine better for everyone.

We believe great software is built in the open, and we're always excited to welcome new contributors. No contribution is too small!

Please read our Code of Conduct to keep our community approachable and respectful.

Reporting issues

Found a bug or have a feature request? Open an issue and include:

• A clear description of the problem or suggestion
• Steps to reproduce the issue (if applicable)
• Your browser, OS, and melonJS version
• A minimal code example or link to a reproduction — this helps us fix it faster

Please search existing issues first to avoid duplicates.

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js version 20 or higher
• pnpm package manager

You can install pnpm using any of these methods:

# using Homebrew (macOS/Linux)
brew install pnpm

# or using npm
npm install -g pnpm

# or using Corepack (bundled with Node.js)
corepack enable

Setting up the project

melonJS is organized as a monorepo with the following structure:

Package	Description
packages/melonjs	The core game engine
packages/debug-plugin	Debug overlay plugin
packages/examples	Interactive examples and demos

To get started:

# 1. Clone the repository
git clone https://github.com/melonjs/melonJS.git
cd melonJS

# 2. Install all dependencies
pnpm install

# 3. Build the library
pnpm build

After building, the output files are located in packages/melonjs/build/:

File	Description
index.js	Tree-shakeable ESM bundle
index.js.map	Source map
*.d.ts	TypeScript declarations
*.d.ts.map	TypeScript declaration source maps

Development workflow

Start the development server to build the engine, watch for changes, and serve the examples with hot reload:

pnpm dev

This launches a Vite dev server. Open the URL displayed in your terminal to browse the included examples (platformer, isometric RPG, drag-and-drop, lighting, and more). Any changes you make to the engine source will be reflected immediately.

Running tests

melonJS uses Vitest with Playwright for browser-based testing.

# Run the full test suite
pnpm test

# Run linting (ESLint + Biome)
pnpm lint

# Run type checking
pnpm -F melonjs test:types

Building the documentation

The API documentation is generated with TypeDoc:

pnpm doc

The output is written to packages/melonjs/docs/ and can be viewed by opening index.html in your browser.

Code style

melonJS uses ESLint and Biome to enforce consistent code style. Running pnpm lint will check your code against the project's rules. Key conventions:

• Use tabs for indentation
• Use strict equality (===)
• Follow the existing patterns in the codebase
• If you fix a bug, consider adding a test to prevent it from recurring

Submitting changes

1. Fork the repository and create a new branch from master
2. Make your changes and ensure pnpm lint and pnpm test pass
3. Write a clear commit message describing what you changed and why
4. Open a Pull Request against the master branch

Not sure where to start?

• Browse open issues for bugs to fix or features to implement
• Check our discussions for ideas and feature requests
• Improving documentation and examples is always welcome

Questions, need help?

• Discord — chat with the team and community
• Wiki — guides, tutorials, and resources
• Discussions — ask questions and share ideas

Contributors

Sponsors

Support the development of melonJS by becoming a sponsor. Get your logo in our README with a link to your site or become a backer and get your name in the BACKERS list. Any level of support is really appreciated and goes a long way!