Development setup
=================

Please configure your editor to respect the EditorConfig_ settings.

Code and build process is split between frontend and backend part.  Note that
the frontend must be build before the backend, as its results will be
incorporated as static files into the Python package.

Frontend
--------

The frontend support code is written in TypeScript and Less, and compiled and
bundled using Webpack.  To install the dependencies and start a development
server:

.. code:: shell-session

	% npm install        # may update package-lock.json, or instead:
	% npm clean-install  # uses package-lock.json exactly
	% npm run start

This starts a development server that watches for changes and automatically
rebuilds the bundle, and instructs the browser to reload using a WebSocket
connection.  To build for production:

.. code:: shell-session

	% npm run build

Backend
-------

Dependencies are managed using PDM_, the build process is handled by
PDM-Backend_.

You may want to create a virtualenv explicitly in order to install pip_ as well,
and/or activate the virtualenv:

.. code:: shell-session

	% pdm venv create --with-pip
	% eval $(pdm venv activate)

To install dependencies, including those for development:

.. code:: shell-session

	% pdm install --dev

Create a directory ``instance`` for your instance configuration, and edit the
configuration:

.. code:: shell-session

	% cp -r examples instance
	% $EDITOR instance/config/config.py

Do replace ``SECRET_KEY`` with a unique, random value; and customise
``SQLALCHEMY_DATABASE_URI`` according to your environment.  See `SQLAlchemy
documentation`_ for details.  You may need to create a database in your database
server beforehand.

Run database migrations:

.. code:: shell-session

	% pdm run migrate

To start the development server:

.. code:: shell-session

	% pdm run serve

If you want to use the ``flask`` command-line tool without specifying the app
every time, you can use a ``.env`` file:

.. code:: shell-session

	% echo FLASK_APP=schilder2000 >> .env

.. _EditorConfig: https://editorconfig.org/
.. _PDM: https://pdm-project.org/
.. _PDM-Backend: https://backend.pdm-project.org/
.. _pip: https://pip.pypa.io/
.. _`SQLAlchemy documentation`: https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls