Web Map Kit guide

Everything you need to go from a QGIS project to a live, shareable web map, and keep it up to date.

Quick start (about 5 minutes the first time)

Install the plugin from the ZIP file.
Open Web Map Kit → Hosting settings once, paste a Cloudflare token, and let the plugin set everything up.
Open your project, click Publish web map, then share the link.

1. Install the plugin

In QGIS (3.28 or newer), open Plugins → Manage and Install Plugins…
Choose Install from ZIP, pick the webmapkit-….zip file you downloaded, and click Install Plugin.
A teal map-pin icon appears on the Web toolbar. Click it to publish; click the small ▾ arrow next to it for My published maps, Hosting settings and this guide. The same items are in the Web → Web Map Kit menu.

Updating: install the new ZIP the same way. Your hosting settings and published maps are kept. If the toolbar button looks unchanged, restart QGIS.

2. Set up hosting (once)

Your maps live in your own free Cloudflare account, using Cloudflare R2 storage. There's no monthly bill and no bandwidth charge, and only you control the files. Open Web Map Kit → Hosting settings and follow the three steps:

Sign in to Cloudflare in your browser, or create a free account. Sign in first, so the next link can fill everything in.
Create my token. Cloudflare opens with the token already filled in. Scroll down, click Continue to summary, then Create Token, then Copy. Using a different browser? Click Copy link and paste it there.
Paste the token into the plugin. It checks the token, finds your account, creates a storage bucket called maps, switches on its public address, and does a test upload.

“R2 isn't switched on yet”? New Cloudflare accounts need R2 turned on once: click Switch on R2, follow Cloudflare's steps (it asks for a card), then click I've done it, check again. The free tier costs nothing; see Costs and limits.

The Cloudflare page showed a list of tokens instead of a filled-in form

You probably weren't signed in when the link opened. Sign in, then click Create my token again. Or create it by hand:

Create Token → Create Custom Token → Get started, and name it Web Map Kit.
Add two permissions: Account · Workers R2 Storage · Edit and Zone · Zone · Read.
Continue to summary → Create Token → Copy, and paste it into the plugin.

Choose your map address

Free Cloudflare address (pub-….r2.dev) works straight away. It's good for drafts and personal maps.
Your own domain (for example maps.yourcompany.com) looks professional for clients. The domain must already be on Cloudflare. Pick it, type a name in front (such as maps), and the plugin connects it. That usually takes 1 to 5 minutes.

Already have R2 keys? On the first screen, choose I already have R2 keys and enter the Account ID, bucket, Access Key ID, Secret and public address yourself.

3. Publish a map

Open your project and style it in QGIS as usual (see Supported styles).
Click the Web Map Kit icon. Check the Title and Description, and tick the Layers to include. Visible ticks what's visible in QGIS.
Pick a Background map, a Points style (circles like QGIS, round icon badges or map pins) and a Detail level. Automatic is right for almost every map.
Leave Publish online ticked and check the Web address. The message under it tells you what will happen:
- ✓ New map: the address is free.
- ↻ Updates your map: this project's map will be replaced at the same link.
- ⚠ Already uses this address: a different map is there. Click Use a new address instead, or confirm you want to replace it.
Click Create web map. Large maps can take a few minutes, and QGIS may look busy until it finishes. At the end, copy the link or click Open map.

Your settings are saved inside the project, so next time it's one click. The web map files are also kept on your computer (by default in Documents/Web Map Kit/). Use Preview on this computer to check a map without publishing it.

What your viewers get

A fast map that works on phones and computers, with no login or app needed.
Click any feature for a popup. The popup title comes from the layer's Display name field (Layer Properties → Display), or else the first name-like text field.
Popup rows use your field aliases. To hide a field, set its widget type to Hidden in Layer Properties → Attributes Form.
A legend with layer toggles and transparency sliders, and an optional search box.

4. Supported QGIS styles

In QGIS	On the web map
Single symbol	✓ Fill, stroke, line width, point size and opacity
Categorized (by a field)	✓ Colours, widths and sizes per category, with legend labels
Graduated (by a field)	✓ Classes, colours and legend
Data-defined size (Size Assistant)	✓ Proportional circles with a size legend
Layer opacity, “no fill” polygons	✓
Labels (single field)	✓ Colour and size; polygon labels placed once per polygon
Categories or classes from an expression	One colour: use a field instead; you'll get a warning
Rule-based, heatmap, 2.5D, point clusters	One colour: not supported yet
SVG markers, patterns, geometry generators	Simplified to plain colours
Raster layers	✕ Vector layers only (points, lines and polygons)

After publishing, the finish screen lists anything under Worth checking, so nothing is dropped silently.

5. Update and manage your maps

Update a map: change your data or styling, click Publish web map again, and keep the same web address. The link stays the same, and visitors see the new version within a minute.
Publish another map: use a different title or web address. Each map gets its own link, and old maps stay online.
My published maps (toolbar ▾ menu) lists every map in your hosting, with a preview, size and date. From there you can Open, Copy link, Copy embed code (to put the map in a website or blog), Update from this project, or Delete a map. Deleting stops the link working for everyone and can't be undone; your QGIS project isn't touched.

6. Fine-tune the look (optional)

Each published map is a small folder of files you can edit, then publish again:

style.css controls colours, fonts and panel styles. It's created once and never overwritten, so your changes are kept.
config.json holds layers, colours, popups and labels. It's regenerated on every export, and the previous version is kept as config.backup.json. Most changes are best made in QGIS instead. CONFIG.md in the folder explains every option.

7. Troubleshooting

“Cloudflare didn't accept this token”

The token was copied incompletely, or it was deleted. Cloudflare shows a token only once, so create a new one with Create my token and paste it again.

“The upload server didn't answer” during set-up

Brand-new accounts and tokens sometimes need a minute before uploads work. Wait a minute and click Try again. If it keeps failing, email us the grey Details line.

“This address is already used by something else in Cloudflare”

The name is taken by another Cloudflare service, often a Pages website or an old DNS record. Remove it there (Workers & Pages → your site → Custom domains, or DNS → Records), or choose a different name.

The map link shows “Error 404 / Object not found”

Check the address in My published maps. The web address is made from the title, so it may differ from what you expected.
Right after connecting your own domain, give Cloudflare a few minutes.
If you switched Cloudflare accounts in Hosting settings, maps published to the old account stay there.

“Too detailed for an area this large”

You picked a high detail level for a big area, which would create millions of tiles. Choose Automatic, or a lower level.

Publishing takes a long time

World-wide data at high detail can take several minutes, and QGIS may look frozen until it finishes; that's normal. Automatic detail keeps it quick. The estimate under Detail tells you before you start.

A layer shows in one colour, or looks different from QGIS

Check the Worth checking notes on the finish screen, and the supported styles table. Categories and classes need to use a field, not an expression.

The background map doesn't appear

Background maps come from OpenFreeMap over the internet. If your network blocks it, the map falls back to a plain background, and your data still shows.

8. Costs and limits

Cloudflare R2 free tier: 10 GB of storage, and no charge for bandwidth, so a popular map doesn't cost more. A typical project map is 1 to 30 MB. Cloudflare's current limits are on its R2 pricing page.
Published maps are public: anyone with the link can view them. Don't publish confidential data.
Your data stays yours: it goes straight from your computer to your Cloudflare account and never passes through our servers. The plugin sends us no analytics.

9. Get help

Email [email protected]. Include your QGIS version and, if possible, a screenshot. Every message gets an answer, usually within a day. If Web Map Kit isn't right for you, you can get a full refund within 30 days (refund policy).