js-samples

Description

Samples for the Google Maps JavaScript API.

The samples can be demoed at the official documentation site.

Development

Template System

This project uses 11ty (Eleventy) static site generator with Nunjucks templates to build the sample showcase.

Nunjucks (.njk)

Nunjucks is a powerful JavaScript templating engine inspired by Python's Jinja2.

• .njk extension = Nunjucks template files
• Purpose: Generate dynamic HTML with variable interpolation, loops, conditionals, etc.
• Syntax example:

  {% for sample in collections.samples_ts %}
    <h4>{{ sample.data.name }}</h4>
  {% endfor %}

11ty/Eleventy

Eleventy (shortened as 11ty) is a static site generator.

• Naming origin: "Eleventy" = 11ty (11 = eleven, ty = ty)
• @11ty/eleventy is the npm package name, @ indicates a scoped package
• Purpose: Transform template files into static HTML websites

How They Work Together

index.html.njk  →  [11ty processes]  →  index.html

1. Input: index.html.njk (Nunjucks template)
2. Processing: 11ty reads templates and executes Nunjucks syntax
3. Output: Static index.html files

Collections System

The collections.samples_ts is automatically generated by scanning the samples directory:

Configuration (.eleventy.js):

eleventyConfig.addCollection("samples_ts", function (collectionApi) {
  const samples = collectionApi.getFilteredByGlob("samples/*/index.ts*");
  return samples;
});

Directory Structure:

samples/
├── add-map/
│   ├── index.ts          # ← Included in collection
│   ├── index.njk
│   └── ...
├── react-map/
│   ├── index.tsx         # ← Included in collection
│   └── ...

Build Process

samples/index.html.njk (template)
    ↓ (11ty processing)
dist/index.html (final static file)

Build

1. npm i Install dependencies.
2. npm run build Build all targets and update dist/ folder.

Test

1. npm test Test outputs.
2. (Optional) npm run lint Fix lint issues with npm run format
3. (Optional) npm run test:playwright:playground:update-snapshots Update snapshots. This uses an custom env var to only to only update screenshots that differ from the previous ones (Playwright only supports none, all, or missing). To update all screenshots, use npm run test:playwright:playground:update-snapshots -- --update-snapshots. It's possible to target a single sample by using -g <sample-name>.

Run

1. Start a server with all samples using npm start

Staging

For staging samples (not common), use Cloud Source Repositories which are controlled by an access control list.

1. gcloud auth login
2. git config --global credential.https://source.developers.google.com.helper gcloud.sh
3. git remote add google https://source.developers.google.com/p/geo-devrel-javascript-samples/r/js-samples
4. git push google
5. git rev-parse --short HEAD or visit the bucket.

Explore

All samples can be explored at https://googlemaps.github.io/js-samples/.

Other resources

• Google Maps JavaScript API Documentation
• Google Maps JavaScript API Reference Documentation
• Google Maps Typings - npm i -D @types/google.maps
• Google Maps Utilities

Support

These libraries are community supported. We're comfortable enough with the stability and features of the libraries that we want you to build real production applications on it.

If you find a bug, or have a feature suggestion, please log an issue. If you'd like to contribute, please read How to Contribute.