How to get started

Background

iD has been the default editor on OpenStreetMap.org for over 10 years now. Because of its age, the source code has a few quirks which makes it slightly unusual to get into. Especially compared to current days' javascript SPA frameworks, some of the design patterns used in iD are a bit more low level as the user interface parts of iD are implemented using D3 as a core library.

Helpful Resources

• D3's getting started guide.
• ARCHITECTURE.md gives an detailed explanation of the data model abstractions used in iD
• The old Mapbox dev blog (available on archive.org) has many interesting articles about the development of the iD editor in its early days.
• The CONTRIBUTING.md document contains information about coding conventions, etc.

Data Model and Concepts

The ARCHITECTURE.md describes iD's data model, patterns and core concepts in much more detail, but here's a few things to keep in mind to get started:

• The used data model is based tightly on top of OSM's data types (i.e. nodes, ways and relations).
• A collection of OSM data entities is called a graph
• In order to provide the mapper with the ability to undo/redo changes, iD maintains a history of graphs, where for each state before and after an edit action a separate (immutable) graph exists. The graphs in different stages of the edit history share the same wrapper objects to the underlying OSM data entities, except for the ones which have been changed by the respective map edit action:
• The difference of the graphs at the start and the end of the edit session is used to upload a diff to the OSM API in a changeset:
• Actions are implemented to take a graph as input and produce an altered graph as output
• User interface code is divided into different stages called modes, operations and behaviours and result in an action.

File Structure

The directories in the repository should be mostly self-explanatory, but here is a short list of where you can find the most important stuff:

• modules contains all of iD's javascript code, from ui user interface code, to the core data models, wrappers for osm data entities, code to handle tagging presets, interfaces to handle external services (like the OSM API, taginfo, etc.), code for data validations, and so on.
• unit tests for these are found in the tests directory
• data contains auxiliary data sets used in iD: some of these are generated automatically (e.g. languages.json or currently also the imagery.json), others like the set of translatable strings in core.yaml are meant to be edited directly
• svg contains icons

Build and Test Instructions

Here's a minimal set of instructions for how to set up your system to work on iD

Installation

Prerequisites

If you haven't already, install Node.js version 18 or newer, and install git. Now you should be able to follow the instructions below.

• Note for Windows users: Edit $HOME\.gitconfig: Add these lines to avoid checking in files with CRLF newlines

  [core]
  autocrlf = input

Cloning the Repository

The repository is reasonably large, and it's unlikely that you need the full history. If you are happy to wait for it all to download, run:

git clone https://github.com/openstreetmap/iD.git

To clone only the most recent version, instead use a 'shallow clone':

git clone --depth=1 https://github.com/openstreetmap/iD.git

If you want to add in the full history later on, perhaps to run git blame or git log, run git fetch --depth=1000000

Building iD

1. cd into the project folder
2. npm clean-install to install dependencies (npm install also works, but is slower as it also checks for available updates for the to be installed dependencies)
3. npm run all to generate static assets (translation strings, icons, etc.)
4. npm start to start up a development instance locally
5. open http://127.0.0.1:8080 in a web browser

The development server refreshes itself automatically whenever you change something in the code (except for static assets like translation strings, icons, etc.). However, this does not yet support hot code reloading, so you need to refresh the page in the browser in order to get the respective changes also live there.

Other Commands

A few more useful commands are:

• npm test runs test suite: please execute these at least before submitting a pull request
• npm lint checks the code for for code formatting mistakes
• npm run build generates a production build, whose results (static html, js, css and assets) are written to the dist directory. This directory is self-contained; you can copy it into the public directory of your webserver to deploy iD.
• Detailed instructions about building a packaged version of iD see RELEASING.md.