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_REFpoints at another ref. Set it tomainto restore floating behavior.EXTENSION_CREATE_TEMPLATE_URLpoints at another archive URL entirely. When it is set and that archive cannot be used,createfails and never falls back to the bundled template.
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/templatesor$XDG_CACHE_HOME/extension.js/templates - Windows:
%LOCALAPPDATA%\extension.js\templates
.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. ItsvaluecarriesprojectPath,projectName,template, anddepsInstalled. - From the release after 4.2.0,
valuealso carriespackageName, the name written topackage.json. - From the release after 4.2.0, the folder keeps the name you typed, in any language.
package.jsongets that name when npm takes it, a cleaned copy (lowercase, spaces as dashes, punctuation dropped) when no letter or digit is lost, ormy-extensionotherwise, and the run says so when the names differ. Onlynode_modulesandfavicon.icoare refused as folder names, withE_ARGS, before anything is created. - Failures print
ok: falsewith anerror.code:E_TEMPLATE_NOT_FOUNDfor an unknown catalog name,E_NETWORKfor a failed download (a refused connection, an HTTP error, or a timeout),E_DESTINATION_NOT_EMPTYorE_DESTINATION_NOT_WRITABLEfor destination problems,E_DEPENDENCY_INSTALLfor a failed dependency install, andE_INTERNALfor 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_INVALIDand leaves nothing on disk. - An archive with an entry outside its folder fails with
E_REMOTE_ZIP_INVALIDtoo, from a template URL or fromEXTENSION_CREATE_TEMPLATE_URL.createchecks 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_MSbounds the whole template fetch, retry included. A fetch that runs out of time fails withE_NETWORKand the reasonNo answer within N seconds.- An
EXTENSION_CREATE_TEMPLATE_URLthat fails never falls back to the bundledjavascripttemplate. A page or a damaged archive fails withE_REMOTE_ZIP_INVALID, and a refused connection, an HTTP error, or a timeout fails withE_NETWORK. The message names the variable, and nothing is left on disk. - A plain
http://template URL withoutEXTENSION_ALLOW_HTTP_TEMPLATE=truefails withE_INVALID_OPTION.
Shared global options
Also supports Global flags.Example commands
Available templates
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.

