leaflet-providers: Tile Layer Configs for Leaflet, Without the URL Bookkeeping

The bookkeeping leaflet-providers removes

A Leaflet basemap is an XYZ URL template plus an attribution string plus, often, a subdomain list. Writing that by hand is not hard, but it is repetitive and easy to get subtly wrong: a missing {s} placeholder, an attribution that omits the data source, a tile URL that changed after a provider rebranded. leaflet-providers collects those configurations into one file and exposes them through a single constructor, so the map code becomes a provider string instead of a URL. The intended audience is straightforward: JavaScript developers already using Leaflet who want a basemap running in a few lines, and who do not want to maintain a private registry of tile endpoints. The README frames the scope narrowly, describing the project as an extension to Leaflet that contains configurations for various free tile providers, with a footnote defining free as layers you can use without paying money rather than layers without limits.

One constructor, a string, and a returned L.TileLayer

The mechanism is a naming convention. Providers are addressed as provider[.<variant>] strings, and L.tileLayer.provider resolves that string to a configuration object and returns an ordinary L.TileLayer instance. Because the return value is a normal tile layer, everything you already know about tile layers still applies: you can add it to a map, swap it out, or attach it to a layer control. The README's example passes Stadia.StamenWatercolor and calls addTo, which is the whole integration. Providers that need credentials take them as options to the same constructor rather than through a separate API, and the option name is not uniform across providers. CartoDB and MapTiles API expect apikey, MapTiler expects key, HERE expects apiKey, Jawg expects accessToken, Thunderforest expects apikey, and Mapbox expects id plus accessToken. That inconsistency is inherited from the providers themselves, but it means you cannot guess an option name from the provider's brand.

Installing leaflet-providers and rendering a first basemap

There are two documented installation paths. With a bundler you install the npm package; without one you load a script tag from a CDN after Leaflet itself. The npm route is a single command and pulls in leaflet-providers as a dependency.

npm install leaflet-providers

The CDN route requires ordering. leaflet-providers.js reads the Leaflet global, so it must come after leaflet.js in the document. The README shows this head block.

<head>
  <script src="https://unpkg.com/leaflet@latest/dist/leaflet.js"></script>
  <script src="https://unpkg.com/leaflet-providers@latest/leaflet-providers.js"></script>
</head>

Once the script is present, adding a basemap is one call. This is the README's Stamen Watercolor example, which now resolves to Stadia-hosted tiles.

// add Stamen Watercolor to map.
L.tileLayer.provider('Stadia.StamenWatercolor').addTo(map);

What you should see is a watercolor-styled basemap filling the map container, with attribution rendered in the corner. If the tiles stay grey, the usual cause is the script order above, not the provider string. For a provider that requires registration, the same call takes an options object. CartoDB, for instance, wants your key under apikey, and the variant field selects a map id or stays blank for the default.

L.tileLayer.provider('CartoDB.Positron', {
    variant: '<insert map id here or blank for default variant>',
    apikey: '<insert API key here>'
}).addTo(map);

To find the right provider string in the first place, the project publishes a preview page that lists the free layers, shows the name to pass to L.tileLayer.provider, and prints the equivalent code for using that layer without the plugin at all. That last part is worth noticing: the preview is also an exit ramp.

Free means no invoice, not no limits

The README's own footnote is the most important sentence in the repository. It says the project tries to keep the included layers usable without paying money, and then states plainly that this does not mean no limits apply, and that you should always check before using these layers for anything serious. That is an honest boundary, and it should shape how you treat the plugin. leaflet-providers is a configuration catalogue, not a service level agreement. It does not proxy tiles, cache them, or negotiate on your behalf. If a provider changes its terms, starts requiring a key, rate-limits your traffic, or retires a style, the plugin cannot protect you; the worst case is a basemap that renders blank in production while your application code is unchanged. The Stamen to Stadia move is the documented precedent: as of July 31, 2023, Stamen's styles are hosted by Stadia Maps, and the README notes that no code changes were required to keep using them, but users still had to register with Stadia and whitelist their domain. The provider string survived. The account requirement did not.

When a tile catalogue is the wrong tool

leaflet-providers is the wrong choice in three situations that come up often. First, offline or air-gapped deployment: every configuration here points at a remote tile server, so a map that must render without network access needs a local tile source and a different layer setup. Second, vector tiles and custom styling: this plugin returns raster L.TileLayer instances, so a MapLibre or Mapbox GL style pipeline is a different architecture, not a variant of this one. Third, strict provenance requirements: if your organisation needs a signed contract with the tile supplier, a catalogue of mostly free endpoints is a starting point for research rather than a procurement answer. There is also a subtler cost. Because the provider strings are convenient, it is easy to add a basemap without reading the provider's terms, and the README's registration sections exist precisely because several providers require an account, a key, or a domain whitelist. The convenience is real, and so is the diligence it can hide.

How it compares to hand-written tile URLs and to GL-style stacks

The closest alternative is not another plugin. It is writing the tile URL yourself, which the preview page actively supports by showing the dependency-free code for each layer. A hand-written L.tileLayer call gives you exactly one endpoint, no catalogue to keep current, and no dependency to upgrade. The trade is that provider changes are now your problem to notice, and switching basemaps means editing code rather than a string. The other alternative is a vector-first stack, where styles are documents served by a rendering library rather than raster tiles assembled by Leaflet. That approach buys runtime restyling and sharper labels at high zoom, and it costs you a different rendering engine, different tooling and, usually, a paid tile host. leaflet-providers sits firmly on the raster side of that divide, and its value is proportional to how many raster basemaps you expect to try.

Maintenance, upgrades and the BSD-2-Clause licence

The repository is not archived, and the last push was on 2026-09-24. The package is versioned at 4.0.0 in package.json, so a major-version bump is the signal to read CHANGELOG.md before upgrading, since provider strings and option names are the public surface and can change when a provider rebrands. The published npm package contains only leaflet-providers.js, README.md, CHANGELOG.md and licence.md, so there is no build step for consumers and no transitive runtime dependency to audit. Development dependencies are linting and test tooling: eslint with the stylistic and html plugins, mocha with mocha-chrome for the browser test suite, and uglify-js for the minified build produced by the preversion script. The licence is BSD-2-Clause, which is permissive and places few conditions on redistribution; the file list spells the licence file as licence.md in package.json while the repository root has license.md, a small inconsistency worth knowing if you script against the package contents. The licence covers the plugin's code. It does not cover the tiles, and each provider's terms travel with its own layer. Nothing here is legal advice; if tile usage matters commercially, read the provider's terms directly.

Editorial conclusion

Adopt leaflet-providers if you are building a Leaflet map and want a basemap switched on in one line, and you are willing to read each provider's terms before you ship. Do not adopt it if you need an offline basemap, a vector tile pipeline, or a promise that a third-party tile URL will still answer next year. Before you commit, open the preview page at leaflet-extras.github.io/leaflet-providers/preview/, pick the exact layer you intend to use, check whether that provider requires registration and a key, and confirm the attribution string it prints matches what the provider asks for.

Frequently asked questions

Official sources

1. Issues
2. leaflet-extras/leaflet-providers on GitHub
3. License: BSD-2-Clause
4. Project website
5. README