ambleloftDefine an extension icon
Make your app recognizable in the sidebar and extension manager. An icon needs both a manifest declaration and a packaged asset.
Outcome: See the installed extension icon and check light and dark themes.
Before you begin: Prepare the files and tools specified on this page. The previous page in the learning path is not automatically a dependency.
On this page
01Prepare the PNG
Create assets/icon.png. Prefer 128×128 with transparency and about 10% padding. It must be a static, square PNG with a lowercase .png extension, 16–512 pixels per side and at most 64 KiB. The sidebar displays it at 18×18 CSS pixels, so avoid tiny text and fine lines.
02Edit extension.json
Merge icon into the top level of the existing manifest, preserving other fields. This is a manifest fragment, not a replacement file. Paths are package-relative; URLs, data URLs, absolute paths, .. and symlinks are unsupported.
"icon": "assets/icon.png"03Copy the asset into the build
Inside the scaffold build.cjs async function, after output has been created, add this code. The template already defines root, output, fs and path. Build, verify dist/package/assets/icon.png exists, then validate and pack.
await fs.cp(path.join(root, 'assets'),
path.join(output, 'assets'), { recursive: true });04Light and dark variants
For theme variants, replace the string with this object and package both files. Both light and dark are required. The host chooses the resolved theme and does not recolor the image. There is no runtime setIcon API.
"icon": {
"light": "assets/icon-light.png",
"dark": "assets/icon-dark.png"
}05Acceptance and troubleshooting
After installation, switch themes and inspect the sidebar and extension manager. An omitted icon uses the default; an invalid declared asset fails installation validation. Check archive paths, PNG format, byte size and dimensions before investigating host compatibility.
Open the complete runnable sampleCheck the result and troubleshoot
See the installed extension icon and check light and dark themes.
Check actual results using this page’s verification steps. For business integrations, inspect UI submission, tool receipts and server records separately.
Open the error reference →