The intent of this repo is to help you get started with creating your own web component library for a FOSS GIS web mapping library. Although you could use any mapping library you'd prefer, we're going to use MapLibre GL JS as an example.
We only include one component as part of this component library / package. That is the <mlibre-point-map></mlibre-point-map> component which allows you to add a series of points to a map. There are no plans to include additional components.
You can view this component live here in a Storybook.
npm installStart local server. This will serve index.html
npm run devBuild the project to the specified output folder (/dist)
npm run buildStart local server to serve the specified output folder. You must run build before preview
npm run previewWe run an instance of Storybook to test the component API
npm run storybookDocumenting a component's API can be time consuming. We can simplify things by using Storybook. This repo has a github action that publishes the Storybook to github pages on every commit to the main branch.
npm run build-storybookSince we're using Lit, the first thing you'd have to do is run npm create vite@latest in your terminal and select lit from the CLI options. Then you'd run npm install to generate a /node_modules. Next, running npx storybook@latest init will include Storybook in your project.
At this point you'll have a few unnecessary files. You can clear out stories you don't need. If you want to work with typescript you'll need to update your tsconfig.json and if you want to externalize any dependencies you would have to add or update your vite.config.ts file.
Now you can begin developing and testing your component(s).
- An open-source library for mapping on the web
- Build / development tools
- Lit for writing web components
- Vite since Lit doesn't have its own compiler
- Typescript
- Testing
- Storybook (@storybook/web-components-vite)
- Sample code for using the component in frameworks
Web components are a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages and web apps. Custom components and widgets build on the Web Component standards, will work across modern browsers, and can be used with any JavaScript library or framework that works with HTML. Web components are based on existing web standards. Features to support web components are currently being added to the HTML and DOM specs, letting web developers easily extend HTML with new elements with encapsulated styling and custom behavior.
Source: https://www.webcomponents.org/introduction
To include maps in a web application, the easiest and most common way is through mapping libraries. Mapping libraries provides out-of-box support for visualizations and interactions in maps. Common choices are as follows:
- Open-source libraries:
- Commercial libraries:
We are also seeing a growing number of mapping libraries as React, Angular, web, or Vue components. Some notable component libraries are:
- Open-source:
- Commericial libraries:
Choosing the best web mapping libraries that suit end user and developer needs is a crucial step for all web development involving maps and/or location services.
You can run npm pack for a preview of what an npm package of your components would look like. Additionally, Lit has documentation on publishing your component package and if necessary, a React 18 framework wrapper too. React 19 seems to work fine without a framework wrapper. This is demonstrated in one of the samples in this repo.
The web components community recommends the community standard custom-elements-manifest JSON.
If you're looking to write some truly "enterprise-ready" web components, you will face a series of challenges for consideration:
- Whether or not to include framework wrappers
- E.g., React wrapper for React 18
- Publishing on npm
- How well a GIS web mapping library can work with web component technology (e.g., slots and Shadow DOM)
- Typings
- Including HTML typings is basically a freebie. Typings for JSX would be an additional effort
- Documentation
- How will you output and share documentation?
- E.g., TypeDoc, JSON, MDX, etc.
- Support module formats other than ECMAScript Modules (ESM), like AMD
- If we only support ESM applications then that means vanilla JavaScript script-tag users who prefer writing quick apps in an
index.htmlfile will struggle. The level of complexity for implementing this support can depend on how well your mapping library plays with certain module formats.
- If we only support ESM applications then that means vanilla JavaScript script-tag users who prefer writing quick apps in an
- How to handle styling (e.g., adoptedStyleSheets, light DOM / shadow DOM, etc.)
- Asset management (if the component package requires assets)
- Icons, translation files, etc.
- Support disconnected / self-contained environment setups
- Support server-side rendering (SSR)
- Development system for web components
- Does it include a built-in compiler? How much can this compiler do for you?
- Can it bundle components together if necessary?
- Can it support lazy loading web components? Lazy loading prevents tree shaking and increases an app's bundle size
- Can it externalize dependencies?
- Maintenance
- Testing
- Managing dependencies
- Breaking changes
These are only some of the considerations, but ultimately, if you're aiming for a bare minimum component library you could probably ignore some of or all of the considerations.
Lit is a lightweight, un-opinionated, and customizable development system for writing web components. Since Lit doesn't have its own compiler, we use Vite for our development server and build tool. In comparison, Stencil has its own compiler but may not be flexible enough to adapt to the requirements of GIS web mapping libraries who want to be "enterprise-ready". Another comparison is that Stencil supports JSX, but Lit does not. FAST is also lightweight and doesn't include its own built-in compiler. Technically, you could write web components with frameworks such as Vue, but then your component library might be less portable and become tightly coupled to that framework.
The component relies on MapLibre GL JS. You can look for errors in DevTools. For example, if an invalid style.json is passed to the mapStyle property then there will be an AJAX error in the console.
https://github.com/web-padawan/awesome-web-components
https://github.com/joewdavies/awesome-frontend-gis
This repo was prepared for a session at FOSS4G NA 2024