Skip to main content
create scaffolds files, configuration, and starter scripts for the selected template and optionally installs dependencies. For a file-by-file tour of the generated tree, see What create generates.

When to use create

  • Start a new extension from scratch.
  • Spin up multiple proof-of-concept ideas quickly.
  • Standardize onboarding for your teammates with consistent template defaults.

Create command capabilities

Usage

Using Yarn? The yarn dlx command requires Yarn 2 or later. Yarn 1 does not include dlx and fails with a “Command not found” error. On Yarn 1, use the npm tab (npx) instead.

Arguments and flags

When you want the default TypeScript starter, omit --template entirely. Add --template=<slug> only for another stack from the official examples. --template also accepts a GitHub URL or a ZIP URL, so you can scaffold from any repository. From 4.1.19, a template URL must use https://. create refuses a plain http:// URL, and a download that redirects to http://, before it writes the project. To allow http:// on a network that you trust, set EXTENSION_ALLOW_HTTP_TEMPLATE=true. The catalog holds 60 templates in 7 groups: starters, sidebar, content scripts, new tab, toolbar action, DevTools panel, and special folders. Run extension create --help for the full list. The default typescript template downloads the catalog archive like every other name. Only the javascript template ships inside the CLI. When you omit --template, EXTENSION_CREATE_TEMPLATE_URL is not set, and the download fails, create falls back to that bundled javascript template and says so, naming the network error, so an offline machine still gets a project. An explicit --template that fails to download fails loudly instead. A scaffold has one package manager. A starter’s packageManager pin (or a pnpm-workspace.yaml it ships) decides it, otherwise the manager that invoked create does. The packageManager field written to package.json, the --install run, and the printed next steps all name that same manager.

How create chooses the package manager

create reads the manager one time, after the template is on disk. The first signal that answers wins: create never reads which managers are installed on the machine or what is on PATH. Only the manager that started the command answers, so pnpx extension@latest create gives a pnpm project on a machine that also has Bun. For the packageManager field, create keeps the template’s pin when it names the chosen manager. Otherwise it writes the version of the manager that started create, when that is the chosen manager. When neither exists, it asks the chosen manager for its version with --version. With no answer, create leaves the field out. On Deno, create adds no packageManager field. The next steps that create prints use the same manager: With --install, create runs the install itself and prints only the run step. The README.md that create writes names the same manager in its commands. With --install, create also installs the build packages that the template integrations need, such as svelte-loader or vue-loader. They go into the Extension.js toolchain folder, not your project. From the release after 4.1.41, one run installs them for every integration, so a package that two integrations share installs once. A Svelte project without TypeScript no longer gets typescript in that run. Set EXTENSION_SKIP_INTERNAL_INSTALL=1 to skip this step. From the release after 4.1.41, EXTENSION_CREATE_INSTALL_TIMEOUT_MS sets a time limit for each install that create runs, 30 minutes by default. It has its own variable, so a longer download limit does not cut an install short. When an install runs out of time, create stops it and every process that it started. The run then fails with the reason The install did not finish within N seconds.

Template corpus pinning

Catalog downloads are pinned to one immutable commit of the templates repository. Two scaffolds of the same version therefore produce the same bytes. Two environment variables override the pin:
  • EXTENSION_CREATE_TEMPLATE_REF points at another ref. Set it to main to restore floating behavior.
  • EXTENSION_CREATE_TEMPLATE_URL points at another archive URL entirely. When it is set and that archive cannot be used, create fails and never falls back to the bundled template.
From the release after 4.2.0, create keeps the catalog archive of a pinned commit in a per-user cache. A second create from the same pin reads the archive from disk instead of downloading it again. The cache is used only when the ref is a full 40-character commit SHA, as the default pin is. A branch, a tag, or EXTENSION_CREATE_TEMPLATE_URL always downloads. The cache keeps the 3 newest archives, and a damaged copy is deleted and downloaded again. Set EXTENSION_CREATE_CACHE_DIR to move the cache. By default it lives at:
  • macOS: ~/Library/Caches/extension.js/templates
  • Linux: ~/.cache/extension.js/templates or $XDG_CACHE_HOME/extension.js/templates
  • Windows: %LOCALAPPDATA%\extension.js\templates
Each scaffold writes a .extension-create.json provenance file into the project. It records the create version, the template, and the source, plus the resolved ref when the template came from the catalog archive, so template drift stays auditable. The bundled javascript starter records "source": "bundled" and no ref. Every template also carries a .mcp.json file that MCP clients read. When the folder already has a .mcp.json, create keeps it as it is. From the release after 4.1.39, a create that fails partway in an existing folder puts your .gitignore and .mcp.json back as they were.

Machine output with --output json

--output json prints one schema-1 envelope on stdout and routes scaffold progress lines to stderr:
  • A successful run prints a status: "created" frame. Its value carries projectPath, projectName, template, and depsInstalled.
  • From the release after 4.2.0, value also carries packageName, the name written to package.json.
  • From the release after 4.2.0, the folder keeps the name you typed, in any language. package.json gets that name when npm takes it, a cleaned copy (lowercase, spaces as dashes, punctuation dropped) when no letter or digit is lost, or my-extension otherwise, and the run says so when the names differ. Only node_modules and favicon.ico are refused as folder names, with E_ARGS, before anything is created.
  • Failures print ok: false with an error.code: E_TEMPLATE_NOT_FOUND for an unknown catalog name, E_NETWORK for a failed download (a refused connection, an HTTP error, or a timeout), E_DESTINATION_NOT_EMPTY or E_DESTINATION_NOT_WRITABLE for destination problems, E_DEPENDENCY_INSTALL for a failed dependency install, and E_INTERNAL for a fault of no known kind.
  • A template URL that answers with something other than a ZIP archive, or with a damaged one, fails with E_REMOTE_ZIP_INVALID and leaves nothing on disk.
  • An archive with an entry outside its folder fails with E_REMOTE_ZIP_INVALID too, from a template URL or from EXTENSION_CREATE_TEMPLATE_URL. create checks every entry before it writes one, so the message says the archive was refused, names the entry, and gives no advice to try again.
  • EXTENSION_CREATE_TIMEOUT_MS bounds the whole template fetch, retry included. A fetch that runs out of time fails with E_NETWORK and the reason No answer within N seconds.
  • An EXTENSION_CREATE_TEMPLATE_URL that fails never falls back to the bundled javascript template. A page or a damaged archive fails with E_REMOTE_ZIP_INVALID, and a refused connection, an HTTP error, or a timeout fails with E_NETWORK. The message names the variable, and nothing is left on disk.
  • A plain http:// template URL without EXTENSION_ALLOW_HTTP_TEMPLATE=true fails with E_INVALID_OPTION.

Shared global options

Also supports Global flags.

Example commands

Available templates

For the full, continuously updated list of templates, browse the examples repository.

JavaScript

Minimal bundled starter. Use when you want a clean baseline or are offline.

TypeScript (default)

Typed sidebar starter with tsconfig.json preconfigured.

React

React UI wired for content scripts and popup views.

Vue

Vue UI with single-file component (SFC) support baked in.

Best practices

  • Start from a template that matches your UI/runtime needs to reduce setup drift.
  • Keep the first run small, then add extra tooling after verifying baseline command flow.