{"id":28434499,"url":"https://github.com/geosolutions-it/mapstoreextension","last_synced_at":"2026-03-14T23:33:38.104Z","repository":{"id":38201100,"uuid":"320565779","full_name":"geosolutions-it/MapStoreExtension","owner":"geosolutions-it","description":"A MapStore project to develop mapstore extensions","archived":false,"fork":false,"pushed_at":"2025-04-29T14:53:08.000Z","size":972,"stargazers_count":1,"open_issues_count":7,"forks_count":22,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-06-05T19:09:09.286Z","etag":null,"topics":["gis","hacktoberfest","mapstore","mapstore2"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/geosolutions-it.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-11T12:19:13.000Z","updated_at":"2025-04-29T14:49:38.000Z","dependencies_parsed_at":"2023-02-13T20:31:36.421Z","dependency_job_id":"66a197fc-ec34-4dc8-8661-54b685707299","html_url":"https://github.com/geosolutions-it/MapStoreExtension","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/geosolutions-it/MapStoreExtension","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geosolutions-it%2FMapStoreExtension","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geosolutions-it%2FMapStoreExtension/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geosolutions-it%2FMapStoreExtension/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geosolutions-it%2FMapStoreExtension/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geosolutions-it","download_url":"https://codeload.github.com/geosolutions-it/MapStoreExtension/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geosolutions-it%2FMapStoreExtension/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262765628,"owners_count":23360945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gis","hacktoberfest","mapstore","mapstore2"],"created_at":"2025-06-05T19:09:09.108Z","updated_at":"2026-03-14T23:33:33.059Z","avatar_url":"https://github.com/geosolutions-it.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Template project to create MapStore extensions\n\nThis repository is a template where to start to create [MapStore Extensions](https://mapstore.readthedocs.io/en/latest/developer-guide/extensions/).\n\nIt is basically a customized MapStore project that allows to run, test and build a sample extension.\nYou can copy this repository and modify the sample extension to develop your own one.\n\nFrom 26-08-2022 we started following the release branching procedure we have on main MapStore project. This means two things:\n\n- **master** branch here will follow and submodule revision will be aligned to master branch [here](https://github.com/geosolutions-it/MapStore2)\n- **stable branch** will do the same, will follow and submodule revision will be aligned to latest stable branch available\n\n## Quick Start\n\nClone the repository with the --recursive option to automatically clone submodules.\n\n`git clone --recursive https://github.com/geosolutions-it/MapStoreExtension`\n\nInstall NodeJS \u003e= 12.16.1 , if needed, from [here](https://nodejs.org/en/download/releases/).\n\nYou can start the development application locally:\n\n`npm install`\n\n`npm start`\n\nThe application runs at `http://localhost:8081` afterwards. You will see, opening a map, the sample plugin on top of the map.\n\n## Start creating your own extension\n\nIf you have to create an extension, you will have to\n\n- find a name for it\n- write the code/css for the plugin and its reducers/epics to implement the effective extension.\n\n### Naming the plugin\n\nThe first step to create the plugin is to name it. To do it, you have to edit 3 files:\n\n- Edit `config.js` to change the name of your extension.\n- Edit `assets/index.json` and change the \"name\" entry with the name of your plugin. (here you can customize dependencies, if needed)\n- Edit `localConfig.json` replacing \"SampleExtension\", in `plugins/desktop` section, with the name of your Extension (for running local development)\n- *[only for version \u003c= 2020.01.xx]* Edit  `package.json` changing `name` entry with a unique name for your extension. E.g. `mapstore-extension-\u003cext-name\u003e.`\n\n\u003e **note** Edit the `name` in `package.json` is not strictly needed from version 2021.02.xx. Anyway it is a good practice to choose a unique `name` in your `package.json` for a new npm project, in general.\n\n### Start developing\n\nThe main entry point of the plugin is `js/extension/plugins/Extension.jsx`. It contains a sample plugin with a sample reducer (probably you will need to rename the reducer), and a sample epic that you can see as example and replace with yours.\nYou should not move or change the `js/extension/plugins/Extension.jsx` file, but you can change all the other files inside `js/extension/` directory. You edit the oher files and add new ones from this starting point.\n\nMoreover you can edit:\n\n- `assets/index.json`: to customize extension dependencies.\n- `assets/translations/`: to set up your translations.\n\n### Build Extension\n\nTo build the extension you should run\n\n- `npm run ext:build`\n\nThis will create a zip with the name of your extension in `dist` directory.\n\n### Test Module\n\nThe current project contains the plugin on its own. In a production environment the extension will be loaded dynamically from the MapStore back-end.\nYou can simulate in dev-mode this condition by:\n\nCommenting `js/app.js` the lines indicated in `js/app.jsx`, that allow to load the plugin in the main app.\n\n```javascript\n// Import plugin directly in application. Comment the 3 lines below to test the extension live.\nconst extensions = require('./extensions').default;\nplugins.plugins = { ...plugins.plugins, ...extensions };\nConfigUtils.setConfigProp('translationsPath', ['./MapStore2/web/client/translations', './assets/translations']);\n// end of lines to comment\n```\n\n- run, in 2 different console the following commands:\n  - `npm run ext:start`\n  - `npm run ext:startapp`\n\nThis will run webpack dev server on port 8081 with MapStore, simulating the `extensions.json` on the default extensions path (the path is relative), and will run on port 8082 the effective modules to load.\n\n## Under the hood\n\nMapStore extensions are based on WebPack 5 [Module Federation](https://webpack.js.org/concepts/module-federation/).\nMapStore uses `ModuleFederationPlugin` to expose the shared libs and provide the proper entry points.\n\nAn extension can `build/createExtensionWebpackConfig.js` utility to create an extension with the same shared libs.\nThis utility function create the base structure to export the proper files as a federate module compatible with MapStore (passing the `name` of the extension and the exposes argument).\nThis project basically uses this utility function, and is configured to:\n\n- Run MapStore and debug the plugin, as a normal plugin\n- Run the test mode of the module, simulating the effective installation\n- Build the final zip file ready to be installed\n\n### Limitations\n\nFor now, components retrieved from MapStore (using the import) will be a **copy of the existing ones**, so calling methods directly on some files imported from MapStore will not have any effect (e.g. register MapInfo Viewers, trying to load resolutions or from `ConfigUtils` or in general access rules using `libs/ajax`).\n\nYou can add to your extension **only** `css`, `js` and `png`, `jpg`, `gif` image files (other than translations folder and `index.json`). Future improvements could allow to add other assets types(icons, fonts, json ...)\n\n### Compatibility\n\nMapStore and MapStoreExtension are usually released in couples. So, generally speaking, MapStoreExtension `2022.02.00` will be compatible with `2022.02.00` ,`2022.02.01` with `2022.02.01` and so on. \nAnyway, depending on the effective usage of the shared libraries and their updates, an extension can continue to be compatible across many different versions. \n\n*note: Sometimes it can happen that we need to release some patch release for one or both the projects. In this case look at the release notes to check if there are know compatibility issues.*\n\n## Dev Hints\n\nHere a list of hints to develop your extension:\n\n- In order to keep your changes as much self contained as possible we suggest to put all your code (and assets) in `js/extension/`. (Put css in `js/extension/assets/`, etc...)\n- Use the `@mapstore` alias to refer to MapStore components. This helps your code to be compatible with future enhancements when mapstore will be published as a separated package, that can be shared\n- In order to debug the extension in `ext:start` + `ext:startapp` mode, you need to add `devtool: 'eval'` to `build/webpack.config.js`.\n- Most of the times you will develop extensions for the main map. For this reason you can find in `app.json` some code comments dedicated to configuring this project to have a plain map on startup. It has not been configured as default because this project is intended to have less differences as possible from a standard project.\n- When the `extensions.json` is configured in `app.jsx` via `extensionsRegistry` and `extensionsFolder`, in order to emulate the `extensions.json` from Webpack DevServer for testing, the paths configured in `build/module.app.webpack.config.js` and `build/webpack.config.js` needs to be modified accordingly\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeosolutions-it%2Fmapstoreextension","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeosolutions-it%2Fmapstoreextension","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeosolutions-it%2Fmapstoreextension/lists"}