Build and package

Packaging turns a working Fission app into something another person, device, store, host, or deployment system can consume. It is separate from distribution: packaging creates the artifact, distribution uploads or submits it.

Use this overview to choose the correct target page, then follow that page for the exact package shape.

Build, package, release, and publish are different steps

Fission keeps the release pipeline explicit. That makes local developer releases and CI releases easier to reason about because each step has a concrete input and output.

Step	Command family	Input	Output
Build	fission build	Shared app source, generated target files, native modules	Target build output for local validation.
Package	fission package	Build output, icons, signing references, package config	Installable/uploadable artifact plus artifact-manifest.json.
Release content	fission release-content and fission release-config	Release notes, screenshots, store metadata, review/privacy files	Validated provider-facing release files.
Publish	fission publish or fission distribute	Artifact manifest, provider config, credentials, release content	Provider upload/submission plus receipt.

Do not publish raw build output. Publish the artifact manifest produced by the package step. It records exactly which files, hashes, versions, package ids, checks, and secondary artifacts are being handed to a provider.

The package loop

A reliable package flow has four steps:

Step	Command shape	Why it exists
Check readiness	fission readiness package ...	Finds missing SDKs, generated targets, signing references, icons, package ids, and provider tools early.
Package	fission package ...	Builds the target artifact and writes an artifact-manifest.json.
Verify locally	Target-specific run, install, serve, or open	Proves the packaged output behaves like the product users will receive.
Hand off to release	fission release-content ... and fission distribute ...	Uses the manifest instead of guessing which file should be uploaded.

Do not skip readiness when preparing a release. It is cheaper to discover a missing Android NDK, Xcode tool, icon, or signing reference before the package command starts.

Pick the target page

Output	Start here	Typical package formats
macOS app	macOS packages	.app, .pkg
Windows app	Windows packages	.exe, .msi, .msix
Linux app	Linux packages	.run
Android app	Android packages	.apk, .aab
iOS app	iOS packages	.ipa
Browser app	Web packages	static web artifact directory or archive
Terminal app or command tool	Terminal packages	release binary and manifest
Documentation, marketing, reference, blog	Static site packages	static artifact or Docker image
Ecommerce, portal, dashboard, dynamic web process	Server site packages	Docker image

If a page is mostly read-only and should be crawlable, use the static site target. If it needs request-time data, sessions, signed actions, cache revalidation, workers, or islands, use the server site target. If it is a full interactive browser app, use the web target.

Native products belong in native modules

If the package needs platform-owned code such as a macOS extension, Windows driver package, Linux helper binary, Android Gradle dependency, or iOS Swift package, declare it with [[native.modules]] in fission.toml. Fission then builds, tests, stages, signs, and manifests the native outputs as part of the normal command lifecycle.

Start with Native modules before adding ad-hoc scripts. For macOS extensions specifically, also read macOS native XcodeGen, which explains the platforms/macos/native/project.yml file Fission-generated projects use for Xcode target graphs. Use package scripts only at the installer boundary, for example when linux/run or windows/exe must install services, drivers, privileged helpers, repair/uninstall logic, or other operating-system-owned integration.

Artifact manifests are the handoff point

Every package format should produce an artifact-manifest.json. That manifest records project identity, target, format, profile, paths, hashes, sizes, MIME types, validation checks, and related files.

Release commands should consume the manifest. That keeps publishing safe to retry because the command can tell exactly what was built and what it is about to upload.

Application resources

Put runtime files that must travel with a desktop or terminal application under the project's assets/ directory. Fission preserves the complete directory tree for both fission run and fission package; projects without assets/ remain valid.

Desktop applications resolve the staged tree from the application resource root:

Target	Staged path
macOS	Contents/Resources/assets/ inside the .app
Linux	assets/ beside the packaged application directories
Windows	assets/ beside the executable

Custom Windows packaging scripts receive the source directory in FISSION_WINDOWS_ASSETS_DIR and are responsible for preserving that tree in their installer. Fission rejects an assets path that exists but is not a directory. On macOS, resources are staged before the application bundle is signed.

Use the manifest path directly:

fission publish \
  --project-dir . \
  --provider play-store \
  --artifact target/fission/release/android/aab/artifact-manifest.json \
  --track internal \
  --yes

If a publish flow does not receive --artifact, it packages the provider's default target/format first. That is useful for local guided publishing. CI should usually pass the manifest explicitly so the build and publish jobs share one immutable handoff file.

Version and build numbers are release inputs

Store targets are sensitive to version/build values. Google Play rejects reused Android versionCode values. App Store Connect and Microsoft Store also have provider-side version and package-state rules. Use release-config commands to make those values explicit before packaging:

fission release-config add-release --project-dir . --version 1.2.3 --build 42 --yes
fission release-config bump-build --project-dir . --target android --yes
fission release-config version-state --project-dir . --provider play-store --target android --track internal --json

Package commands sync the resolved version/build into target-native config where Fission owns that generated configuration. If provider state says a build number has already been used, fix the release config and rebuild instead of uploading a known-bad artifact.

Signing boundaries

Signing is platform-owned. Fission orchestrates checks, configuration, command flow, and receipts, but platform signing should use the tools provided by the platform owner.

Do not commit signing passwords, private keys, tokens, or certificates into fission.toml. Use CI secrets, environment variables, authenticated platform tooling, or operating-system key stores.

Next steps

After packaging, move to Release and distribute. If the release needs notes, screenshots, or store metadata, start with Release content.

Screenshots and release metadata are build inputs

Packaging does not end at producing a binary. App stores and distribution providers need release metadata, screenshots, icons, version fields, signing references, and provider-specific identifiers. Use Build metadata to keep those fields explicit, and use Store screenshots to generate reviewable screenshots from real Fission targets.

Write a live interface test

Store screenshots