maproulette3 is a new front-end for MapRoulette built with React.
A back-end server from the maproulette2 project is still required. You can either install and configure it locally, or -- if looking to do front-end development only -- can connect to a pre-existing server if you have access to one (you will need your API key for that server). Please do not use the production server for development purposes.
.env.development.localfile and then look through
.envat the available configuration options and override any desired settings in your new
yarnto fetch and install NPM modules
yarn run startto fire up the front-end development server
As mentioned above, a back-end server from the maproulette2 project is also required. You can either install and configure it locally or, if you have access to a pre-existing server, connect directly to it by using your API key for that server.
Developing with a local back-end server
Install the back-end server using the instructions from the maproulette2 project, if you haven't already
Visit your OpenStreetMap account and go to My Settings -> oauth settings -> Register your application and setup a new application for development. For the
Main Application URLand
Callback URLsettings, put in
http://127.0.0.1:9000(assuming your back-end server is running on the default port 9000). The only app permission needed is to "read their user preferences". Take note of your new app's consumer key and secret key, as you'll need them in the next step
In your back-end server project, setup a .conf file that overrides properties as needed from
conf/application.conf(unless you'd prefer to set explicit system properties on the command line when starting up the server). Refer to the
conf/dev.conffile and maproulette2 docs for explanations of the various server configuration settings. At the very least, you'll want to make sure your JDBC url is correct and your OAuth consumer key and secret are set properly.
Fire up your back-end server, specifying the path to your .conf file with
-Dconfig.resourceor explicitly specifying the various system properties on the command line. See the maproulette2 docs for details on starting up the server
.env.development.localfile in your front-end project and set:
(assuming your back-end server is on port 9000 and front-end is on port 3000). Restart or startup your front-end server, and then navigate to the front-end at http://127.0.0.1:3000
Developing with a pre-existing back-end server
These instructions are for connecting to an existing back-end server, rather than a local one you have installed. Please do not use the production MapRoulette server for development use
Open MapRoulette on that server normally in your browser, visit your user profile, and take note of your API key at the bottom of the page. Alternatively, you can use the server's
super.keyif it has been setup with one and you have access to it
.env.development.localfile and override the following config variables:
Restart your front-end dev server if it's already running (ctrl-c then
yarn run startagain)
Point your browser directly at the front-end server, http://127.0.0.1:3000 by default. Once the page finishes loading, you should show up as signed-in if all is working correctly
Updating to the Latest Code
Note that the maproulette2 back-end server must be updated separately.
- Stop your front-end server (ctrl-c) if it's running.
- Pull the latest code
yarnto install new or updated NPM packages
yarn run startto restart the front-end server.
- Setup a
.env.productionfile with the desired production setting overrides.
REACT_APP_URL='https://myserver.com/mr3'(substituting your domain, of course)
- if you wish to use Matomo/PIWIK for
REACT_APP_MATOMO_SITE_IDto your tracking url and site id, respectively (see
.envfile for example).
- set feature flags to
- override any other settings from the
.envfile as needed or desired.
yarnto install and update NPM packages.
yarn run buildto create a minified front-end build in the
Adding Additional and Custom Map Layers
Default map layers are determined by pulling in data from the OSM Editor Layer
Index at build time and
extracting layers marked as default layers with global coverage. These are
stored in the
src/defaultLayers.json file. Modifying this file is not
recommended as it will be overwritten automatically by the build process.
Layer ids of additional desired layers from the Layer Index can be specified in
REACT_APP_ADDITIONAL_INDEX_LAYERS .env config variable (see the .env file
for documentation), and these will also be included in the
file. The default .env file includes the OpenCycleMap layer this way.
Custom and 3rd-party layers that aren't included in the Layer Index can be
manually added to
src/customLayers.json following the same structure as the
default layers. The build process does not modify this file other than creating
a stub if it doesn't exist.
Setting API Keys for Map Layers
API keys for any layers -- default or custom -- can be set through the
REACT_APP_MAP_LAYER_API_KEYS .env file configuration variable (see the .env
file for documentation). For custom layers, an API key can also simply be
included in the specified layer url in
src/customLayers.json if that is
Enabling the Mapillary Map Layer
MapRoulette has built-in support for a Mapillary map layer during task
completion, allowing the mapper to make of use of available street-level
imagery. To enable the layer, simply set the
key to your Mapillary client id and restart your dev server (or rebuild your
dev front-end for staging/production). If you don't have a client id, you can
set one up through the
Mapillary Developer Tools
The project was bootstrapped with Create React App.
Branch management follows
active development occurring on the
develop branch. Pull requests should
develop branch. The master branch always contains the latest
release, and the
prerelease branch contains features and fixes promoted from
develop that are candidates for the next release to
It is okay for pull requests to the
develop branch to rely on server features
or fixes that have only been merged into the server's
dev branch, but they
will not be promoted to the
prelease branch until the server-side code makes
it into the server's
Release versions follow Semantic Versioning.
yarn test to run them in watch mode.
Note: End-to-End tests are temporarily disabled as the Chimp framework is not compatible with Node 10 LTS.
Prior to running tests locally, you'll need to tell Chimp the URL to your
MR3 app. Copy
chimp.js, edit the file and modify the
mr3URL setting. You only need to do this once.
yarn e2e to run the tests, or
yarn e2e --watch to enter watch mode and only
run tests with a
@watch tag (useful when working on new tests).
Sauce Labs has also graciously provided us with free access to their cross-browser testing platform.
CSS Styling and Naming
We are currently in transition between the old styling that used the
Bulma framework with SASS and new styling using Tailwind
CSS with PostCSS. New CSS classes are prefixed with
mr- to distinguish them from any existing Bulma classes, but during this
transition there are still situations where a mix of both Tailwind and Bulma
are in play.
Tailwind configuration is controlled with the
src/tailwind.js file. New CSS
classes can be found in
Internationalization and Localization
Internationalization and localization is performed via
react-intl. Most components feature
co-located Messages.js files that contain messages intended for display,
along with default (U.S. English) versions of each message. Translation files
that contain translated versions of these messages for supported locales are
stored in the
src/lang/ directory. A fresh en-US.json file can be built from
the latest messages using
yarn run build-intl, which is also run
automatically as part of the
yarn build script used for creating production
builds. Translation files for other locales must be updated manually.
By default, the en-US locale will be used for users who have not set a locale in
their MapRoulette user settings. This default locale can be changed with the
REACT_APP_DEFAULT_LOCALE .env setting. Users who have set a locale will
always have their locale honored regardless of the default locale.
Note that MapRoulette makes use of its own locale setting and does not use the setting from the user's OpenStreetMap account at this time.