Contributing

Development Workflow

Clone the repository and install dependencies:

git clone https://github.com/Woosmap/maps-js.git
cd maps-js
bun install

Start the dev server:
```
bun start
```
This runs on http://localhost:8082 with WOOSMAP_ENV=local, watches for changes, and recompiles automatically.
Run tests before committing:
```
bun run test
```
Run the full lint + type check:
```
bun run lint
```

Code Style

Type System

This project uses Flow (// @flow annotations), not TypeScript. Flow types are stripped at build time by the Rollup Flow plugin.

Formatting Rules

Rule	Value
Indentation	4 spaces
Max line length	120 characters
Object curlies	No spaces (`{foo}` not `{ foo }`)
Quotes	Not enforced (single or double)
Arrow functions	Preferred over function expressions
`const`	Preferred (`destructuring: "all"`)
Template literals	Preferred over string concatenation
Unused args	Only `_` allowed as ignored arg name
Imports	ES modules only — CommonJS (`require()`) is prohibited
Camelcase exception	`_changed$` suffix allowed (MVCObject pattern)

ESLint Configuration

The project extends:

mourner — base style
plugin:flowtype/recommended — Flow type checking
plugin:react/recommended — React/Preact JSX rules
plugin:import/recommended — import/export validation

Info

src/mapbox/** is excluded from linting — this is vendored Mapbox GL source.

Preact / JSX

Both ESLint and Webpack alias react to preact/compat. JSX in this project uses Preact under the hood. Write JSX as you would for React — the alias handles the rest.

Testing

Runner: Karma
Framework: Jasmine
Bundler: Webpack (with Babel for Flow + React preset)
Browser: ChromeHeadless
Test location: src/tests/**/*.spec.js

Running Tests

bun run test                # Standard run
DEBUG=yes bun run test      # With Istanbul coverage

Focusing Tests

There is no CLI flag to run a single test. Use Jasmine's built-in focus:

fdescribe("MyFeature", () => {
    fit("should do something", () => {
        // Only this test runs
    });
});

Warning

Remember to remove fdescribe/fit before committing.

CI Pipeline

CI runs these checks in order:

flow check — type validation
eslint src — linting
bun run test — unit tests

All three must pass for a PR to merge.

Documentation

Documentation lives in docs/ and uses zensical (mkdocs-compatible).

Building Docs Locally

cd docs
pip install -r requirements.txt
make serve

The make reference target generates API reference pages from JSDoc annotations using documentation (JSON export) and jsdocgen (markdown generation).

Documentation Structure

Hand-written pages: docs/docs/*.md — architecture, guides, configuration
Generated pages: docs/docs/reference/*.md — API reference from source JSDoc

Project Structure

See the Architecture page for a detailed source organization map and module hierarchy.