Best Practices

Best Practices

Use these guidelines to keep extensions reliable, predictable, and easy to maintain.

Handle Errors Gracefully

Catch failures around network requests, file operations, and external processes. Show actionable error messages instead of failing silently.

Show Progress for Long Operations

Use sigma.ui.withProgress() for tasks that take more than a moment. Prefer cancellable workflows when the operation may run for several seconds or longer.

Validate Input Before Acting

Validate values collected from command arguments, prompts, and custom modals before performing filesystem, shell, or network actions.

Write Platform-Aware Code

Use sigma.platform to branch on operating system behavior and construct paths safely. If an extension only supports some platforms, declare that explicitly in the manifest.

Manage Runtime Dependencies Explicitly

If an extension depends on external tools such as ffmpeg or yt-dlp, declare them in package.json > binaries and resolve them at runtime with sigma.binary.getPath() or sigma.binary.getInfo().

Use one manifest for local installs and published installs

You do not maintain separate binary definitions for “dev” and “production.” The same manifest ships when you load an extension from a folder and when you publish it to the marketplace.

Integrity works at two different layers:

Layer	What is verified	Where you set it
Extension package	The GitHub release ZIP of your extension	releaseMetadata.<version>.integrity in the registry entry (Submitting to the Marketplace)
External binaries	The downloaded tool (archive or binary) from a manifest asset	integrity in package.json > binaries[].assets[], or checksum files the host can fetch next to that URL (see Manifest Reference and API Reference → sigma.binary)

For predictable binary installs:

1. Pin exact versions in binaries[].version and use versioned asset URLs whenever possible.
2. Ship explicit SHA-256 hashes in binaries[].assets[].integrity when you can.
3. Use supported checksum hosting only when the upstream project already publishes reliable sidecar checksum files next to the asset.
4. Do not rely on mutable latest download URLs for published extensions.

Nothing in the registry JSON replaces binary metadata; binary declarations live in the extension manifest, not in registry.json.

onInstall, binary downloads, and cancellation

The host resolves manifest-declared binaries during install and update. If a user cancels the download, the host aborts the extension install and rolls it back automatically.

Do not catch installation cancellation in a way that hides the failure from the host. If your activation code runs on onInstall and performs follow-up work after binaries are installed, let cancellation propagate or rethrow it when sigma.runtime.isExtensionInstallCancelledError(error) is true.

Bundle Runtime Assets Deliberately

Do not publish node_modules. Prefer self-contained local assets over CDN dependencies for extension pages so installs remain reliable and offline-capable.

Ship the compiled entry your manifest main references (usually under dist/) and any other runtime assets the extension loads. Manifest-only theme and icon theme extensions can omit main, but still need to ship every asset referenced by the manifest. Tag-based installs use a Git archive; the host does not run npm run build for users - see Submitting to the Marketplace.

Use Sigma APIs Instead Of Browser Assumptions

API extensions run in an isolated worker, and extension pages run in a sandboxed iframe bridge. Use Sigma APIs for clipboard, dialogs, storage, shell access, and translation instead of assuming unrestricted browser APIs are available.

Clean Up Resources

Dispose timers, subscriptions, and other long-lived resources in deactivate() when they are not automatically managed by the extension runtime.

Keep Permissions Minimal

Request only the permissions your extension actually needs. Smaller permission scopes improve user trust and reduce review risk.

Continue

← Previous: UI Reference

Next: Extension Architecture →