Testing, packaging, and releasing an extension

Release the exact extension ZIP you have tested, with a clear version, compatibility requirements, and recovery instructions. A useful release check covers the package, its behavior on a test site, and what happens when an existing installation updates.

Start with Building your first extension if you have not yet produced an installable package. For integrations, use Working with extension data and integrations to plan data, permissions, provider failures, and retries.

Set the version and support requirements

Keep the same extensionId for updates to the same extension. Preserve the IDs of existing pages, blocks, records, routes, and jobs so installations can recognize them.

Choose a version that reflects the change:

• Patch: compatible fixes or improvements to existing features.
• Minor: new optional features or contributions that preserve existing behavior.
• Major: changes that can break existing installations, such as removed IDs, incompatible data changes, new required settings or secrets, or stricter permissions and dependencies.

Align the version across the canonical manifest, package-family metadata, package manifests, and runtime registrations. Regenerate the bootstrap and package projections from the canonical manifest. Review newly requested access as part of the release, even when the feature itself is optional.

Set the minimum Cedros host version to one that provides the contracts you use. For a Wasm backend, verify the target host's supported interface version and checksum. A package built against a newer interface is not automatically compatible with an older host.

Write down the oldest host you support, required extensions or providers, and any setup that must happen before enabling the release. Test those requirements rather than inferring them from an installed package version.

Build and validate the final archive

From your extension project, use the scripts supplied by the authoring kit:

1. Install the locked dependencies with npm ci after aligning package metadata and the lockfile.
2. Run npm run package. In the supplied examples, this synchronizes the manifest, builds the packages, validates them, runs the scaffold tests, and writes the ZIP under dist/.
3. Run your feature's own tests. The scaffold tests check package conventions; they do not test the behavior you added.
4. Inspect the final ZIP and record its SHA-256 checksum. If you change anything and rebuild, validate and test the new artifact before distributing it.

The kit also includes a deterministic verifier at docs/extension-authoring/scripts/cedros-authoring.mjs. Its focused commands include validate-manifest, check-runtime-alignment, and validate-package. Use the authoring reference for command usage. Build before checking compiled-file alignment, and resolve reported failures rather than treating a generated report as a pass.

Your release ZIP should contain:

• One cedros-extension.manifest.json and one cedros-extension.bootstrap.json, with matching manifest content.
• The matching React package metadata and compiled registration modules, together with every runtime chunk they import.
• cedros-extension.server.wasm when your feature uses a server backend. Declared routes and jobs must match the component's exports.
• Setup and release instructions, plus any source or provenance evidence required by your distribution channel.

Keep credentials, node_modules, Rust build output folders, and dependency caches out of the ZIP. The installing site does not build missing files or fetch your npm dependencies. Browser modules must run without Node-only globals, including in bundled dependencies and lazy-loaded chunks.

Check the packaging reference for the full archive contract. Current intake limits include 4,096 entries, 2 MiB per non-Wasm entry, and 8 MiB of uncompressed non-Wasm content. Those entries must be UTF-8 text; the compiled server component has a separate 64 MiB limit. Ordinary binary images or fonts cannot simply be added to this archive.

Test the installed feature

Use a separate development or test site with permission to install extensions. Upload the final ZIP through Extensions → Upload extension, review its requested access, and follow Uploading a private extension. Confirm the installed version and enabled state before testing.

Exercise the actual feature on the site:

• Admin pages: open each page, use its main controls, save a change, reload, and confirm the saved result.
• Public pages and blocks: visit the real public route, check desktop and mobile layouts, use the primary action, and test keyboard access and visible errors.
• Server routes: test a valid request, invalid input, unauthenticated access, and missing permissions. Confirm private records cannot be accessed by another user.
• Integrations and jobs: test missing configuration, a failed request, and a repeated operation. Check the destination result and confirm a retry does not duplicate an external effect.

For a feature that sends messages, makes payments, or uses a paid provider, prepare test accounts and the appropriate test mode first. Do not use a customer-facing action merely to prove a button works.

Package intake checks structure and compatibility; it does not execute your entire UI in a real browser. Test the packaged registration modules and their dependent chunks, not just source code served by a development server. A successful upload is not proof that a page renders or a job completes.

Test updates and recovery

A clean installation is only one test. Install the previous supported version, create representative settings and data, then update it with the new ZIP. Check that existing pages, links, records, credentials, and schedules still behave as documented.

Disable the extension and verify what becomes unavailable. Re-enable it and confirm its features return without duplicate setup or lost settings. For removal tests, use disposable data and distinguish retaining data from deliberately deleting it.

If a release changes data, define whether the change is reversible or requires a forward fix. Declaring migration IDs does not make Cedros run a data conversion automatically. Implement and test the supported migration path, including interruption and retry, before promising that an update is safe.

Keep the previous tested package available, but do not assume uploading an older ZIP will restore the site. Downgrades require the supported rollback path and compatible data; ordinary installation can reject an outdated version. Reinstalling a package does not reverse completed provider actions or data changes.

Document when to disable the feature, who owns recovery, which version can be restored, and how to handle data that cannot be downgraded. The release and upgrade reference covers versioning, compatibility, and rollback requirements.

Distribute the tested release

Prepare a short release handoff containing:

• Extension name, ID, version, source revision, exact ZIP, and checksum.
• Supported Cedros versions, required dependencies, requested access changes, and setup instructions.
• Tests performed, the environment used, results, and any unresolved limitation that affects installation or use.
• Update steps, expected data changes, disable behavior, and recovery instructions.
• Release notes describing the user-visible changes and a way to get support.

For private distribution, give the authorized site owner the tested ZIP and handoff. A local upload does not add the package to the public catalog. For catalog distribution, complete that catalog's review and publication process before telling users the version is available.

If you use MCP, discover the destination site's current extension tools and schemas. Package intake, catalog review and publication, installation, and enabling are separate operations even when a workflow combines them. Confirm the artifact's digest and resulting state at each relevant step; publishing a catalog version does not update an installed extension by itself.

Keep source, signature, and build evidence separate from a claim that someone verified it. Only report checks that actually ran. Do not put an enclosing ZIP's checksum inside its own manifest, because changing the manifest changes that checksum.

Verify the release on the destination site

After the owner installs or updates the release:

1. Confirm the exact installed version and enabled state in Extensions. Resolve any pending permission, dependency, or setup requirement.
2. Open the affected admin and public pages. Run the agreed smoke checks and confirm the expected saved state or external result.
3. Review relevant errors and job outcomes. If a request timed out, inspect the resulting state before repeating it.
4. Keep the tested artifact and recovery instructions available. If a critical check fails, follow the documented recovery plan and record the observed version and failure.

Use Updating, disabling, or removing an extension for the owner's lifecycle controls. Finish the release when the intended version and its core behavior are verified on the destination site, not when the upload finishes.