js-samples: the runnable sample code behind the Maps JavaScript docs

A corpus of examples, not a library

js-samples is the repository behind the Google Maps JavaScript API examples, and the distinction matters if you approach it as a dependency. It is not a library you install and call. It is a corpus of small, complete, runnable programs, and the samples are demoed on the official documentation site as well as being explorable as a gallery at googlemaps.github.io/js-samples.

The code is TypeScript, and the sample directories show how the catalogue is organised: add-map, the advanced-markers family with variants for accessibility, altitude, animation, basic style, collision, draggability, graphics, HTML content, simple and zoom, aerial-rotation and aerial-simple, the boundaries family with choropleth, click, simple and text search, circle-simple, combining-data, conserve-map-on-scroll, and control samples for bounds restriction and custom state.

The audience is a developer integrating the Maps JavaScript API who wants to see a feature working, and a Google engineer who wants every documentation snippet to be real code that is built and tested. The latter is the more important user, and it explains a lot about the shape of the repository, which is a documentation site generator, a bundler, a type checker and a browser test suite rather than a source tree with a public API.

The package is published as @googlemaps/js-samples at version 2.1.4, and the version numbers in the repository are not the same as the sample release tags, which run in the v3.27.x line.

Each sample is a playground, and that is the architecture

The build scripts describe how a sample is put together, and the answer is that each one is a small application with its own playground.

The build script for the playground bundles two entry points, the playground index and a resizer, with esbuild, targeting es2020, splitting the output and writing it into the dist folder. A separate build step bundles a worker from the playground-elements package, the TypeScript worker, for the node platform, and a third step runs Tailwind to produce the playground stylesheet.

Underneath that is Eleventy, the static site generator, run in incremental mode, and the repository has an .eleventy.js configuration and an .eleventyignore file. The samples directory holds the sample sources and the templates, including a README template written in nunjucks.

The interesting part for a reader is the shape of the contract. The playground is a live editing surface, a TypeScript worker compiles the code you type, and the resizer handles the frame. That machinery is what lets a documentation page embed a runnable example rather than a static snippet, and it is also why the build is a multi-target pipeline rather than a single bundle.

Build it and serve it locally

The development workflow is short, and it is the part of the repository a newcomer will actually use.

Two commands get you from a clone to a built site:

npm i
npm run build

The install pulls the dependencies and the build produces every target and updates the dist folder. The build script cleans dist first and then runs the build targets in parallel, so the Eleventy site, the esbuild bundles, the worker and the Tailwind stylesheet are all produced in one pass.

Serving it is the third command, npm start, which starts a server with all the samples. The package file shows the mechanics: it cleans and runs the watch targets, and the static server is http-server pointed at dist on port 8080, with the Eleventy watcher serving the site as it changes.

So the loop is: npm i once, npm run build when you want a full build, and npm start while you work. The gallery of all samples is then reachable locally, which is also the fastest way to check whether a sample does what you need before you adapt it.

The test suite is a type check plus Playwright

There is no unit test framework in the usual sense, because there is no library to unit test. The test script runs the test targets in sequence, and the first one is a type check:

tsc --noEmit --skipLibCheck

That is the whole test:jest target. Every sample in the repository has to type check against the Maps typings, which is a real check, because a sample that does not compile cannot be shown in the documentation.

The browser tests are Playwright, and there are three of them. One runs the end-to-end directory, one runs the playground tests, and one runs the app tests. The playground snapshot update has its own script, and the README explains a subtlety in it well.

By default the update script sets a custom environment variable so that only screenshots which differ from the previous ones are updated, because Playwright itself only supports none, all or missing as snapshot modes. To update every screenshot you pass the flag through, and you can target a single sample with the -g option:

npm run test:playwright:playground:update-snapshots -- --update-snapshots

That combination of a type check and visual snapshots is a sensible fit for a samples repository, since the thing that can break is either a compile error or a change in what the map renders.

Staging goes through Cloud Source Repositories

There is a staging path, and the README flags it as unusual, saying that for staging samples, which are not common, you use Cloud Source Repositories, which are controlled by an access control list.

The sequence is a credential helper, a remote, a push and a short hash:

gcloud auth login
git config --global credential.https://source.developers.google.com.helper gcloud.sh
git remote add google https://source.developers.google.com/p/geo-devrel-javascript-samples/r/js-samples
git push google
git rev-parse --short HEAD

The last command prints the short commit hash of what you pushed, and the alternative is to visit the storage bucket for the staging site directly, which is listed in the README as the geo-devrel-javascript-samples-staging bucket.

The structure of this tells you something about the project. The deployment target is a Google-owned repository behind an access control list, and the output lands in a storage bucket, so publishing a sample to the staging site is a privileged operation performed by people who already have Google Cloud access. For everyone else, the local build and the public gallery are the whole workflow.

There is also a sample-to-branch.sh script in the repository root, which is the kind of utility that suggests the samples are managed as branches during review rather than as a single trunk.

The licence says one thing in the metadata and another in the package

There is a discrepancy worth flagging, because it is the kind of thing that only shows up when someone checks.

The repository's licence metadata records a custom licence that GitHub cannot classify, with a pointer to a LICENSE file. The README carries an Apache-2.0 badge, and the package.json declares the same Apache-2.0 in its licence field. The LICENSE file in the repository root is the place to read.

The sensible reading is that the code samples are Apache-2.0, matching the badge and the package metadata, while something else in the tree, possibly the assets, carries terms that are not one of the standard licences, which is what causes the classification to fail. Whatever the split is, the LICENSE file answers it and the badge does not.

The other resources section is worth reading for a developer building against the API. It points at the Maps JavaScript API documentation and the reference documentation, at the Google Maps Typings in DefinitelyTyped with the installation line npm i -D @types/google.maps, and at the Google Maps Utilities repository, the v3 utility library, which is a separate codebase with its own release cadence.

On support, the README is careful with its wording. The libraries are described as community supported, and the project says it is comfortable enough with the stability and features of the libraries that it wants you to build real production applications on it. Bugs and feature requests go to the issue tracker, and contributors are pointed at the How to Contribute document.

Where the samples are not enough

The limits are obvious once you understand what the repository is, but they are worth stating for anyone planning to depend on it.

First, a sample is a demonstration, not a module. Each one shows a feature in isolation, with the plumbing that a real application would need removed. Adapting a sample means writing the parts that handle loading, errors, permissions and lifecycle, and the more of those you need, the less of the sample survives.

Second, the release cadence and the commit history have drifted apart. The sample releases are v3.27.0 from August 2024, v3.27.1 from September 2024 and v3.27.2 from October 2024, while the last push to the repository was on 2026-06-24. The published tags therefore tell you little about what is in the tree today, and for a repository whose whole value is that the examples are current, that is the fact to check before you copy anything.

Third, the whole thing assumes the Maps JavaScript API, its billing model and its key management. A team that needs a map component without an account and a key is in the wrong place entirely, and the alternative is a different library with a different API surface, not a different sample.

The pragmatic approach is to treat this repository as a reference implementation. Read the sample that does the thing you want, check its commit history to see how recently it was touched, and then write your own integration against the API reference. That way you take the pattern rather than the scaffolding, and you inherit a maintenance burden you can actually see.

Editorial conclusion

js-samples suits a developer who wants a working, current example of a Maps JavaScript feature rather than a snippet to adapt, and it is the wrong place to look for a supported library, because the support statement is about community maintenance and the releases stop at v3.27.2 in 2024 while the last push was on 2026-06-24. Verify first which API version a sample targets before copying it, and read the LICENSE file, because the repository licence field records a custom licence while the README badge and package.json both say Apache-2.0.

Frequently asked questions

Official sources

1. googlemaps/js-samples on GitHub
2. Issues
3. Project website
4. README
5. Releases