@geogirafe/lib-geoportal

中文文档
1.3.0-dev.3060317043发布于 2026/11/12Apache-2.0TypeScriptES Module近 30 天下载 6333

GeoGirafe is a flexible application to build online geoportals.

原始使用文档
文档目录22 节
  1. Goal
  2. Development philosophy
  3. Architecture
  4. Development
  5. 1. Clone repository
  6. 2. Development Certificates
  7. 3. Build and start GeoGirafe
  8. Debugging using VSCode
  9. Configuration
  10. On Linux
  11. On Windows
  12. Testing
  13. unitests (with vitest)
  14. End-to-end tests (with playwright)
  15. Build for Production
  16. Build the NPM Package
  17. Build the library
  18. Publish Lib Package to npmjs.com
  19. Build the Android Application
  20. Deployment
  21. Using an existing WebServer
  22. Using Docker

Pipeline Status Docker Pulls

GitLab Contributors GitLab Issues GitLab Merge Requests GitLab last commit

Quality Gate Status Bugs Code Smells

Lines of Code Coverage Duplicated Lines (%)

Security Rating Vulnerabilities Reliability Rating Maintainability Rating

GitLab License

GeoGirafe

GeoGirafe is a flexible application to build online geoportals. This repository contains the web-viewer part of the project.

The project documentation can be found here: https://doc.geogirafe.org.
The demo instances of GeoGirafe can be tested here: https://demo.geomapfish.dev.

Goal

The goal of GeoGirafe is to allow the easy implementation of a stable, efficient and secure geoportal. GeoGirafe is also meant to be easily extensible, by allowing users to integrate their own plugins.

As the main users of GeoGirafe do not necessarily have advanced skills in computer development, we wanted to have a learning curve as smooth as possible. This is why the project does not use the latest frameworks and favours readable code over code corresponding to certain arbitrary "quality" criteria. GeoGirafe is therefore based on web standards (Vanilla Web Components) and limits the number of dependencies to other libraries.

Development philosophy

GeoGirafe is developed according to the following principles:

  • KISS: GeoGirafe is simple. It is developed with pure Vanilla-JavaScript. No complex framework like React or Angular is used. If you know JavaScript, you can understand how it works.

  • DevSecOps: GeoGirafe is baking security in at every phase of the software lifecycle, in order to deliver a secure-by-design application. Quality, readability, reliability and security are checked by the SonarCloud platform during our continuous integration processes: View SonarCloud Reports

  • Reactivity: GeoGirafe is meant to be responsive, resilient, elastic and message driven according to the Reactive Manifesto.

  • Agility: GeoGirafe is being developed according to the Agile methodology. We value individuals collaboration, and change responsiveness more than processes, tools and plans.

  • Accessibility: GeoGirafe is doing its best to make web content more accessible to individuals with disabilities: View Wave Report.

Architecture

Architectural choices made for the GeoGirafe project, including strategic objectives and technological choices, is explained in details here: https://doc.geogirafe.org/docs/introduction/architecture.

Getting Started

If you want to get started with GeoGirafe, the simplest way is to use the Docker Container : https://hub.docker.com/r/geogirafe/viewer. This will allow you to get a running instance of GeoGirafe with minimum effort. Please follow the small documentation in the Docker Hub Readme.

Work with GeoGirafe

Development

1. Clone repository

First, install Node.

Then, clone the Repository:

git clone https://gitlab.com/geogirafe/gg-viewer.git

2. Development Certificates

Certain features (e.g. service workers) require a valid HTTPS certificate for local development.
You can generate your own development certificates with:

On Linux

On Linux or macOS, generating your own certificates is mandatory (pre-generated ones won't work).

npm run generate-dev-certs-nix
On Windows
npm run generate-dev-certs-win

3. Build and start GeoGirafe

npm install
npm start

When working locally with authentication, and more generally with cookies, browsers treat single-label domains (domains without any dots) differently from multi-label domains (domains with at least one dot). Cookies set on single-label domains are often considered less secure because they can be more easily spoofed or misused. As a result, many browsers restrict or do not allow cookies to be set on single-label domains like localhost.

Therefore, working against https://localhost will NOT work, because the cookies cannot be correctly set.
You'll have to use https://app.localhost, which has been defined as the default domain when working locally with GeoGirafe.

Further discussions about this:

Debugging using VSCode

If you are using VSCode, there is a preconfigured debugging configuration in the .vscode directory.
After you've started the application in development mode, just press F5, and VSCode will attach to the running process. You will then be able to debug your code.

Configuration

The complete configuration of the application is done in the file config.json. This configuration will be loaded dynamically when the application starts. Therefore it is not necessary to rebuild the project when you modify this file.

The file config.json does not exists by default. The simplest way to create one is to pick up an existing one in the demo directory, and to adapt the content to your needs.

You can also preconfigure GeoGirafe for an existing demo configuration by using:

On Linux

npm run configure-demo <environment>

On Windows

npm run configure-demo-win <environment>

This will automatically copy the config.json file in the right place, and download the needed Mock objects.

Please note that today, the GeoGirafe Viewer is using a backend based on GeoMapFish. The services you will have to use in your configuration must therefore be compliant with GeoMapFish.

Testing

There are 2 kinds of tests in the GeoGirafe project:

unitests (with vitest)

To run the unitests, execute the following command:

npm run test

And that's it.

End-to-end tests (with playwright)

To be able to run the playwright tests, first install the headless chrome and firefox binaries:

npx playwright install

Then you must start the application:

npm start

And then in another console you can run the tests:

npx playwright test

The result page will omen at the end of the tests.

Build for Production

npm install
npm run build

This will output a complete built GeoGirafe app which can be served by a Webserver easily in the dist/app folder.

You can try the built asset with (you need docker for this example!):

docker run --rm -p 8088:80 -v $(pwd)/dist/app:/usr/share/nginx/html nginx:latest

This will spin up an NGINX and you can access it on app.localhost:8088.

Press CTRL+C to stop the container.

Build the NPM Package

Make sure to have run the command npm login before at least once

Build the library

npm install
npm run build-lib

This will output (beside others) a transpiled version of GeoGirafe's library part into dist/lib.

Publish Lib Package to npmjs.com

npm run publish-lib --access public

Build the Android Application

Make sure you have build the application for production before with npm run build.
The file config.json present in the dist\app directory will be used.

npm run build-apk

This will output an APK package of GeoGirafe into dist/apk.

Deployment

The deployment can be done in 2 ways:

Using an existing WebServer

After the build, everything that needs to be deployed is in the public directory. Copy the public directory content to any webserver, for example in the htdocs directory.

Using Docker

When the project has been built, you can build a docker image that will contains the application:

docker build -t <your_name>/viewer -f buildtools/Dockerfile dist

Then, you can start it:

docker run -p 8080:80 -p 8443:443 <your_name>/viewer

Contributing

Merge-Requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Contribution guidelines are available here: CONTRIBUTING.md.
Please read them before contributing.

Supporting

There are many ways to support GeoGirafe.

  • You can use the following tag on your project to help promote GeoGirafe: GeoGirafe
    code: [![GeoGirafe](https://geogirafe.org/wp-content/uploads/geogirafe-badge.svg)](https://geogirafe.org)

  • If you are interested in providing financial assistance, please reach out to us at [email protected].

  • If you have another idea how to support the project, we invite you to join us on the dedicaced discord server: https://discord.gg/kdrXjaqBbH.

License

Apache License, Version 2.0

版本与发布记录

@geogirafe/lib-geoportal 共发布 715 个版本,首次发布于 2024/02/07;过去 12 个月发布了 237 个版本。

版本发布日期距今
1.3.0-dev.3060317043latest2026/11/123 天前
1.3.0-dev.30534522052026/11/114 天前
1.3.0-dev.30460542362026/11/106 天前
1.3.0-dev.30183131512026/11/0213 天前
1.3.0-dev.30182849342026/11/0213 天前
1.3.0-dev.30084859842026/10/3016 天前

关于 @geogirafe/lib-geoportal 的常见问题

@geogirafe/lib-geoportal 是什么?

GeoGirafe is a flexible application to build online geoportals.

如何安装 @geogirafe/lib-geoportal?

在项目目录运行 npm install @geogirafe/lib-geoportal,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:ol(>=10.8)、olcs(2)、proj4(2)、cesium(>1.113)、ol-ext(4)、ol-mapbox-style(>=12)、@geoblocks/print(>=0.7.9)、@geoblocks/mapfishprint(>=0.3)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 lib-inline,可以用 npx lib-inline 直接运行。

@geogirafe/lib-geoportal 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geogirafe/lib-geoportal 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@geogirafe/lib-geoportal 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20.19.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@geogirafe/lib-geoportal 可以商用吗?

@geogirafe/lib-geoportal 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@geogirafe/lib-geoportal 的下载量有多少?

根据 npm 官方下载统计,@geogirafe/lib-geoportal 在 2026/10/16 – 2026/11/14 这 30 天内被下载 6,333 次,日均约 211 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geogirafe/lib-geoportal 还在维护吗?

最新版本 1.3.0-dev.3060317043 发布于 2026/11/12(3 天前);至今共发布 715 个版本,其中过去 12 个月发布了 237 个;首次发布于 2024/02/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。