# GoogleChrome/chrome-extensions-samples: A Working Reference for Manifest V3 Extensions

> The official sample repository for Chrome Extensions shows how each API is wired up in a real manifest, split into single-API samples and full extensions. It is a reference to copy from, not a framework to build on.

**GoogleChrome/chrome-extensions-samples** — Chrome Extensions Samples

- Repository: https://github.com/GoogleChrome/chrome-extensions-samples
- Website: https://developer.chrome.com/docs/extensions
- Stars: 17,790 · Forks: 9,011
- Language: JavaScript
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/googlechrome-chrome-extensions-samples

## What the samples repository is actually for

The README describes this as the official samples for Chrome Extensions and the Chrome Apps platform, and notes that Chrome Apps are deprecated with a link to the Chromium blog. That sentence sets the boundary of the project. It is a teaching corpus, not a library. Nothing here is published to npm for consumption, and package.json sets "private": true, so there is no installable artifact to depend on.

The audience is narrow and specific: someone who has decided to write a Chrome extension and needs to see how a given API behaves inside a real manifest. The README points readers to the Chrome Developers site for general extension documentation and to the Samples page on that site to discover extensions by type, permissions and extension API. So the repository is the code half of a two-part resource, with the prose half living elsewhere.

If you are evaluating a framework for building extensions, this is the wrong place. If you want to know what a working manifest.json looks like for, say, a content script plus a background service worker, this is the most direct source available.

## api-samples versus functional-samples: two different reading modes

The README lays out the directory structure explicitly. api-samples/ holds extensions focused on a single API package. functional-samples/ holds full featured extensions spanning multiple API packages. There are also two archive directories: _archive/apps/ for the deprecated Chrome Apps platform, which the README says is not listed below, and _archive/mv2/ for manifest version 2 resources.

That split is the most useful design decision in the repository, because it tells you how to read each directory. An api-samples entry is documentation with a manifest attached: minimal permissions, one API call path, no UI polish. A functional-samples entry is closer to a small product, and it is where you look when the question is how several APIs cooperate in one extension.

The practical consequence is that copying from functional-samples is riskier than copying from api-samples. A full featured sample carries permissions and structure that exist to make that one demo work, and the README does not describe any per-sample rationale. Read the manifest of the sample you copy rather than assuming the repository has a house style.

The _archive/mv2/ directory is a trap for anyone arriving from an older tutorial. Manifest V2 code is kept there as a resource, and the README does not present it as a migration guide. If your extension already targets V3, that directory is history, not reference.

## Installing the repository and loading your first sample

There is no package to install. The README's installation section says to clone the repo and use Load Unpacked Extension, linking to the Development Basics page under the mv3 path on Chrome Developers for the full walkthrough. The repository itself is not an extension, so you load an individual sample directory, not the repository root.

Clone first, then pick a sample directory to load.

```bash
git clone https://github.com/GoogleChrome/chrome-extensions-samples.git
cd chrome-extensions-samples
```

The repository has a package.json, but its scripts are for repository maintenance rather than for running a sample.

```bash
npm install
npm run lint
```

Running npm install pulls the devDependencies listed in package.json, which are tooling: eslint, prettier, husky, lint-staged, globals, chrome-types and the eslint plugin packages. npm run lint runs eslint over the JavaScript files. Neither command builds or serves an extension.

To actually see a sample run, open chrome://extensions, enable Developer mode, choose Load unpacked, and select the folder of the sample you want, for example a directory under api-samples/. The sample appears in the extensions list, and any service worker it declares can be inspected from that page. If a sample appears with errors, the first thing to read is its own manifest.json, since the README does not document per-sample requirements.

## The maintenance scripts and what they do not cover

package.json defines four scripts. prettier runs npx prettier over markdown, HTML and JSON files in write mode. lint runs eslint over all JavaScript. lint:fix reruns lint with --fix. prepare runs husky install, which wires up the Git hooks. A lint-staged block then applies eslint --fix to JavaScript files and prettier --write to markdown, HTML and JSON on commit.

This is repository hygiene for Google's own contributors, and it is worth being honest about what it means for you. There is no test script and no build script. The devDependencies include eslint-plugin-jest, but package.json declares no test command, so a reader cannot tell from the manifest alone where tests would run. The repository also has a CONTRIBUTING.md and a README-template.md at the top level, which signals that sample READMEs are generated from a template rather than written ad hoc.

If you fork this to keep your own samples, the tooling is a reasonable starting point. If you fork it expecting a development environment for an extension you are shipping, you will be adding the build, bundling and test layers yourself.

## Where the samples stop being useful

The clearest limitation is that this is a reference corpus with no versioning contract. There are no releases, so there is no changelog to read when an API's behaviour shifts. The repository tracks the main branch of Chrome extension development, and a sample that worked in your copy can diverge from the current state without any signal in package.json, whose version field is a flat 1.0.0.

A second limitation is scope. The README's own framing includes the Chrome Apps platform, which it simultaneously marks as deprecated. Anyone scanning the top-level directory listing will see _archive/apps/ and _archive/mv2/ next to live directories, and nothing in the README's directory list explains the archive beyond a one-line note. That is a documentation gap, not a code gap, but it costs a new reader time.

Third, samples are not production code. A sample that demonstrates one API call does not need the error handling, permission minimization or message-passing structure a shipping extension needs. Treating a functional-samples entry as an architecture to imitate is the most common way to misuse this repository. It is the right tool when you need to see an API in context, and the wrong tool when you need a foundation.

## How it compares with a scaffolding generator

The obvious alternative is a scaffolding tool that generates a new extension project with a build step, a bundler, a TypeScript config and a dev reload loop. Those tools solve a different problem: they produce a project you own and extend. This repository produces nothing. You read it, copy a manifest shape and a service worker pattern into your own project, and move on.

The difference in approach matters for debugging. A generator gives you a working baseline whose behaviour you have to trace when something breaks. A sample gives you a minimal, legible example of one API where the entire surface is visible in a handful of files. When you are trying to work out why a permission is being rejected or how a message is routed between a content script and a service worker, the sample is faster to reason about.

The trade-off is the reverse when you are starting from zero. There is no generator here, no template command, and no dependency to add. If you want a project skeleton, you are looking at the wrong repository.

## Licence, attribution and upgrade cost

The README states that the samples are authored by Google and licensed under the Apache License, Version 2.0, with the full text in the LICENSE file at the repository root. package.json records the same licence as "Apache 2.0".

Apache-2.0 is permissive and includes an explicit patent grant, and it requires that you preserve copyright and licence notices for code you redistribute. That last point is the one to watch in practice: copying a sample file into your extension means carrying its notice with it. How that obligation applies to your specific distribution is a question for your own counsel, not something the repository answers.

The upgrade cost is unusual, because there is nothing to upgrade. You do not bump a dependency version. What you do instead is re-read the sample when Chrome's extension APIs change, and the repository's lack of releases means you have no changelog to tell you when that is necessary. The last push to the repository was on 2026-09-18, so the code is current as of that date, but currency is not the same as a versioning guarantee. Budget for periodic re-reading rather than for dependency updates.

## Conclusion

Adopt chrome-extensions-samples if you are writing a Manifest V3 extension and need a working manifest and service worker for a specific API before you commit to your own structure. Do not adopt it as a dependency, a build system or a starting codebase you intend to keep: package.json marks the project private, there is no extension entry point, and the samples are meant to be read and copied. Before you rely on any single sample, check which directory it lives in, since api-samples and functional-samples carry different expectations, and read the manifest.json of that sample rather than the repository README, which does not document per-sample permissions or versions.

## FAQ

### Can you give me some examples of Google Chrome extensions?

The repository itself is the example set. Its api-samples directory holds extensions focused on a single API package, and functional-samples holds full featured extensions spanning multiple API packages, so you can browse by how much surface area you want to see.

### Is the Chrome extension sample safe?

The README states the samples are authored by Google and licensed under Apache License 2.0. They are loaded through Chrome's own Load unpacked flow, and the repository README does not document any additional safety review, so the permissions of the individual sample's manifest are what you should read before loading it.

### How do I install chrome-extensions-samples?

There is no package to install. The README says to clone the repository and use Load Unpacked Extension, linking to the Development Basics page on Chrome Developers, and you load an individual sample directory rather than the repository root.

### Can I install chrome-extensions-samples from npm?

No. package.json sets "private": true and the repository publishes no releases, so the devDependencies such as eslint, prettier and chrome-types are repository tooling, not an installable extension package.

### What is the difference between api-samples and functional-samples?

The README describes api-samples as extensions focused on a single API package and functional-samples as full featured extensions spanning multiple API packages. The first is better for reading one API in isolation, the second for seeing several APIs work together.

## Sources

- [GoogleChrome/chrome-extensions-samples on GitHub](https://github.com/GoogleChrome/chrome-extensions-samples)
- [Issues](https://github.com/GoogleChrome/chrome-extensions-samples/issues)
- [License: Apache-2.0](https://github.com/GoogleChrome/chrome-extensions-samples/blob/main/LICENSE)
- [Project website](https://developer.chrome.com/docs/extensions)
- [README](https://github.com/GoogleChrome/chrome-extensions-samples/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/googlechrome-chrome-extensions-samples