Skip to main content

Set up a GeoGirafe client

If you're new to GeoGirafe, this guide is the perfect place to start.

tip

GeoGirafe and this tutorial are written in TypeScript. However, it doesn't mean your project must be in TypeScript. We use Vite to bundle our project. Please ensure you follow the "Getting Started" guide for Vite before proceeding.

Requirements​

  • NodeJS version 20+
  • GIT

Install​

Install the latest development version​

The last version of GeoGirafe can be installed with just one command:

npm create @geogirafe/template@latest <application-name>

This will :

  • create a folder my-geogirafe-app containing a minimal project of GeoGirafe.
  • download all the dependencies and build the project
  • generate the SSL certificates used by GeoGirafe.

The whole process takes 2–3 minutes, depending on your network speed.

Please note that this installs the very latest development version of GeoGirafe. You will get all the newest changes, bugfixes and improvements. We do our best to keep GeoGirafe stable through our continuous deployment process, but development versions may still contain small bugs or regressions. If you prefer an officially released version, use the command described in the next section.

Install a specific version​

To install a specific version of GeoGirafe, you have to specify the version parameter:

npm create @geogirafe/template@latest my-geogirafe-app <version>

Versions follow the vX.Y.Z pattern, for example v1.0.0 or v1.2.1. The list of releases is available here: https://gitlab.com/geogirafe/gg-viewer/-/releases

Create SSL certificates​

Once the installation is done, SSL-Certificate that can be used for local development will be created automatically.
If, for some reason, they couldn't be created on your environment, you'll have to create them manually with the following commands.
This will help you to create this certificate, and tell the system and the browser to trust it:

On Windows:

cd my-geogirafe-app
npm run generate-dev-certs-win

On Linux:

cd my-geogirafe-app
npm run generate-dev-certs

This is important, because some functionalities will only work with a valid SSL Certificate.
This is a limitation of the browsers, that do not allow for example services-workers do work correctly is they are used on a non-secured website.

Start GeoGirafe​

You can now start the project :

npm start

That's it, you should now be able to see your first map, congratulations!

Next steps​

You can now start by reading the README file of the project, it contains the first explanations.
Each file in this project also contains comments. This will allow you to better understand how is working GeoGirafe, and how you can configure it to your needs, add your own layers, ...

If necessary, you can always get in touch with us on Discord: https://discord.com/channels/1194934479282778122

Have a nice journey with GeoGirafe! :-)