Development environment
***********************

| In this section we will explain a bit more the environment used for developing with mapstore
| So, make sure to have the requested tool installed before moving on

See all requirements details `here <https://mapstore.readthedocs.io/en/latest/developer-guide/requirements/>`__

.. _ref_create_local_project_dev:

Create a local project
======================

| To start working with MapStore we can create a new standard project
| by following this :ref:`Getting Started <ref_Getting_Started_projects>` section

| In particular the paragraphs **Create Project** and **Include print module**
| but you can read all the remaining parts which are indeed helpful

Build the application
=====================

You can run ``build.sh`` script to run all the commands to compile front-end, back-end and pack everything in a deployable package.

.. code-block:: sh

  ./build.sh [version_identifier]

``version_identifier`` is an optional identifier of the generated war that will be shown in the settings panel of the application.
You can deploy the generated ``mapstore.war`` file (in ``web/target``) to your favorite J2EE container (e.g. Tomcat).

By default there are two users in a new MapStore instance:

- ``admin``, a user with ADMIN role, with password ``admin``
- ``user``, a user with USER role, with password ``user``

You can use a running instance of MapStore in a tomcat as your own development back-end service
by configuring appropriately the ``devServer`` ``proxy`` in the webpack configuration file.

.. note::
   MapStore uses:

   - `npm <https://www.npmjs.com/>`_ for JS dependencies
   - `babel <https://babeljs.io/>`_ for compatibility with all browsers
   - `webpack <https://webpack.js.org/>`_ as module bundler (and dev server, with proxy)
   - `karma <https://karma-runner.github.io/>`_ as unit test runner
   - `maven <https://maven.apache.org/>`_ to Java dependencies and to build the final web application

   Running ``build.sh`` you run basically runs:

   .. code-block:: sh

      npm install # download npm dependencies
      npm run fe:build # build JS/HTML/CSS bundled
      mvn install #download JAVA dependencies and build the final war

   .. figure:: ./img/build.jpg
      :alt: build procedure

      ``npm run fe:build`` executes the part in blue, while ``mvn install`` the part in red.
      The copy of ``dist`` directory and ``*.html`` files made by maven allow to include the client
      in the final ``war`` file created in ``web/target``.

Running unit tests
==================

The project will provide you a setup ready for running your unit tests. This setup will run automatically the test contained in the files that ends with ``-test.js`` or ``-test.jsx``.
We use to store them in ``__tests__`` folders by convention.

Here the commands to run the unit tests:

Run tests:

.. code-block:: sh

  npm test

Run test with hot reload:

.. code-block:: sh

  npm run test:watch

.. note ::

   You can change or reduce the number of tests executed by ``npm run test:watch`` by editing ``tests.webpack.js``, changing the base path or the regex used for searching the files.
   See the main developer documentation `here <https://mapstore.readthedocs.io/en/latest/developer-guide/requirements/>`__  for more details

Running in Dev Mode
===================

MapStore is a single page application, so you can run it in development mode using the webpack dev server. It uses a Java back-end. Both can run using the commands

.. code-block:: sh

   npm start

This command runs both the back-end on port 8080 and the front-end on port 8081.

You can run the 2 services separately (even in 2 different terminal instances):

.. code-block:: sh

   # Run back-end on port 8080
   npm run be:start

.. code-block:: sh

   # Run front-end on port 8081
   npm run fe:start


Debugging the Backend
---------------------

| MapStore Back-end is a Java Application that uses Spring. So standard techniques to run and debug Java applications are valid.
| For instance Eclipse remote debugging with Tomcat using JPDA
| You can import the code of MapStore (or your custom project), geostore, etc… in  Eclipse IDE by running:

.. code-block:: sh

  mvn eclipse:clean eclipse:eclipse

This creates the projects that can be imported in the Eclipse IDE.

.. note::
   You may not need to develop on MapStore back-end. You can use instead your favorite back-end framework, and integrating authentication using database and/or REST services
   (GeoServer integration uses this techniques). If you want, you can follow the `debug section of developer guide <https://mapstore.readthedocs.io/en/latest/developer-guide/developing/#debug>`_ for more information.

Recommended Browser Extensions
==============================

Adding :ref:`redux dev tools <ref_redux_dev_tool>` extension to your browser and adding ``debug=true`` to the query string you can monitor all redux actions and state modification during the execution of MapStore in development.

.. figure:: img/redux-dev-tools.png
   :alt: dev tools for redux

   redux-dev-tools

Recommended IDE Extensions
==========================

All people in mapstore team has switched to VS Code and we strongly recommend it.
Here is a list of needed extensions that will make your life, as programmer, easier

- `ESLint <https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint>`__
- `Auto Import - ES6, TS, JSX, TSX <https://marketplace.visualstudio.com/items?itemName=NuclleaR.vscode-extension-auto-import>`__
- `Npm intellisense <https://marketplace.visualstudio.com/items?itemName=christian-kohler.npm-intellisense>`__
- `Path autocomplete <https://marketplace.visualstudio.com/items?itemName=ionutvmi.path-autocomplete>`__

Not necessary, but nice to have

- `Status bar error <https://marketplace.visualstudio.com/items?itemName=JoeBerria.statusbarerror>`__
- `Peacock <https://marketplace.visualstudio.com/items?itemName=johnpapa.vscode-peacock>`__
- `Code Spell checker <https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker>`__

We do not use prettier yet, so it's up to you to install it in your project