fission.toml manifest

Fission

Product

▾

Setup

›

fission.toml manifest

fission.toml is the project manifest read by the Fission command-line interface and the static-site shell. It is the place for stable project facts: the app identity, enabled targets, declared host capabilities, site build settings, package references, release entries, provider configuration, and release workflow commands.

Keep this file human-reviewable. Short identifiers and paths belong here. Long release notes, localized store descriptions, review instructions, privacy declarations, screenshots, videos, certificates, private keys, and tokens should live in referenced files, provider tools, CI secrets, or the Fission credential vault.

Minimal app manifest

Most app projects need only this at the start:

targets = ["linux", "macos", "windows"]

[app]
name = "my-app"
app_id = "com.example.my_app"

Contract completeness checklist

Use this checklist when wiring fission.toml manifest into an app or shell implementation.

Requirement	Why it matters
Public entrypoint	The app code must call the documented helper, command, or configuration field rather than a platform-specific shortcut.
Required setup	Native manifests, plist entries, entitlements, service-worker files, domains, protocols, credentials, or provider registration must be present before production use.
Typed success and error	The implementation should return a truthful typed result. Silent success, swallowed errors, and string-only failure paths make apps unsafe to retry.
Retry behavior	Operations that can fail because of permission, network, hardware, store, or packaging state should document whether retrying is useful and what must change first.
Tests	Cover the happy path, unsupported host path, bad configuration path, and any security-sensitive rejection path.

Failure behavior and safe retry

Treat failures as product states, not surprises. A Fission app should be able to tell the user whether the problem is missing configuration, missing provider support, denied permission, unavailable hardware, invalid input, expired credentials, or a transient host error. Reducers should update state from typed results and keep retry buttons idempotent so pressing them twice cannot corrupt state or duplicate unsafe work.

fission init writes this file for you. fission add-target and fission add-capability update it idempotently.

Parsing rules

Fission commands currently read the sections they need instead of requiring one giant schema object. That has a few practical consequences:

Rule	Contract
File location	The manifest must be named fission.toml and live at the project root passed by --project-dir.
Required for app commands	fission run, fission build, fission test, fission package, fission add-target, and fission add-capability require [app] and targets.
Required for site commands	fission site ... requires [app].name. The [site] table is optional but needed for non-default site behavior.
Unknown fields	Unknown fields are tolerated by current TOML deserializers, but they do not affect behavior. Do not rely on an undocumented field unless the command that reads it is listed here.
Paths	Paths are project-relative unless explicitly described as absolute or provider-owned. Absolute paths are accepted in some release/package paths, but project-relative paths are easier to review and reproduce.
Secrets	Do not put secrets in this file. Use environment variables, provider command-line tools, platform key stores, CI secrets, or fission auth import.

Root fields

Root fields appear before any table header.

Field	Type	Required	Accepted values	Meaning
targets	array of strings	Yes for app/package commands	android, ios, linux, macos, server, site, web, windows	Declares which generated hosts belong to the project. Commands use it to reject packaging/running a target that has not been added.
capabilities	array of strings	No	barcode-scanner, biometric, bluetooth, camera, geolocation, haptics, microphone, nfc, notifications, passkeys, volume-control, wifi	Declares host capabilities the app intends to use. fission add-capability updates this list and generated Android/iOS files where the configuration is deterministic.

Clipboard and deep-link APIs are runtime/platform capabilities, but they are not currently accepted values in the root capabilities array. Deep-link routes still need product-owned native or web routing configuration, and clipboard currently does not require root manifest declaration.

The terminal user interface shell is currently a shell/tooling surface rather than a root targets value, so terminal and tui are not accepted in targets.

[app]

[app] identifies the product and package. It is required by normal app commands.

Field	Type	Required	Meaning
name	string	Yes	Rust package/app name used by generated scripts and site fallback title. Prefer a Cargo-compatible kebab-case name such as field-inspector.
app_id	string	Yes	Stable application identifier used by generated mobile/desktop package metadata. Use a reverse-domain identifier such as com.example.field_inspector.
splash	table	No	Native launch-screen configuration for iOS and Android. When omitted, generated mobile targets use assets/app-icon.png on a neutral background instead of showing an empty black startup window.

app.name should match the Cargo package name for normal generated projects. fission init refuses to set a conflicting name for an existing Cargo package because the generated scripts call Cargo by package name.

[app.splash]

[app.splash] controls the platform-owned launch surface shown before the first Fission frame is ready. This is not an in-app loading page; it is native startup configuration generated into the Android activity theme and the iOS launch storyboard so the operating system has something branded to draw while the process, renderer, and app code start.

Use it when mobile startup currently shows a blank or black screen, or when the app needs a product-specific launch mark. Keep the content simple. The launch surface should introduce the app, not perform onboarding, advertising, account selection, or any work that belongs in the real Fission widget tree.

Field	Type	Required	Default	Meaning
background_color	string	No	#F8FAFC	Hex color in #RRGGBB or #RRGGBBAA form. Android receives the matching Android color literal; iOS receives an sRGB storyboard color.
image	string	No	assets/app-icon.png	Project-relative image used as the static splash mark. Android accepts PNG, JPEG, and WebP. iOS accepts PNG and JPEG.
resize_mode	string	No	contain	How the image is placed where the platform supports it: center, contain, or cover. Use contain for logos and cover only for artwork designed to crop safely.
android_animated_icon	string	No	none	Project-relative Android XML drawable used for Android's native animated splash icon. This is Android-only and should be an animated vector drawable or other Android XML drawable accepted by the platform packager.
android_animation_duration_ms	integer	No	800	Android native splash icon animation duration. Must be greater than zero when set.

Example:

[app.splash]
background_color = "#06131F"
image = "assets/splash-mark.png"
resize_mode = "contain"
android_animated_icon = "assets/android/splash-animated.xml"
android_animation_duration_ms = 900

iOS launch screens are static by platform design. If an app needs a longer animated handoff after launch, implement that as the first route or app state in the Fission widget tree, then transition into the main screen when the required data is ready.

[site]

[site] configures the static-site target. It is used by fission site ..., fission package --target site --format static, and static-site publishing providers.

Field	Type	Required	Default	Meaning
entry	string	No	none	When present, fission site ... delegates to the project's Rust site builder by running the Cargo package and passing build, check, routes, or serve. Use this for custom Fission-rendered marketing pages.
title	string	No	[app].name	Site title used in generated document titles and the default header.
description	string	No	none	Default SEO description used when a route does not provide front matter description.
logo	string	No	none	Site asset path for the header logo, such as /img/fission-mark.svg.
favicon	string	No	none	Site asset path for the generated <link rel="icon">.
base_url	string	No	none	Absolute public origin used to generate canonical URLs and sitemap entries, such as https://fission.rs.
base_path	string	No	/	Static package metadata base path. GitHub project pages often use /<repo>/; custom domains usually use /.
canonical_url	string	No	none	Static package metadata canonical URL. Use this when a distributor needs the public site URL recorded in package metadata.
out_dir	string	No	target/fission/site	Output directory for generated HTML, CSS, assets, search index, sitemap, and robots file.
default_locale	string	No	en	Locale used for the HTML lang attribute and search index metadata.
asset_dirs	array of strings	No	[]	Directories copied into the generated site root. This documentation site uses static.
css_files	array of strings	No	[]	Project CSS files appended after Fission's generated CSS. Later rules can override generated rules.
generate_sitemap	boolean	No	false	Writes sitemap.xml when enabled. base_url must be set for route URLs to be emitted.
generate_robots	boolean	No	false	Writes robots.txt. If base_url is set, the file includes a sitemap URL.
cache_control	string	No	public, max-age=31536000, immutable	Static package cache policy written into package metadata and _headers.

The current documentation manifest also contains locales and pretty_urls. Those fields are tolerated by the current parser but are not authoritative behavior switches today. default_locale is the locale field currently consumed by the static-site shell, and generated output already uses pretty route URLs.

[[site.nav]]

Each [[site.nav]] entry adds one top-level navigation link to the generated documentation template. A link can also contain nested children, which the static-site shell renders as dropdown menus. Nested children can continue recursively, so a top-level product menu can contain a Resources item, and Resources can contain a Documentation item. Keep blog navigation on the blog landing page itself rather than stuffing every post into the global header.

Field	Type	Required	Meaning
title	string	Yes	Text shown in the header navigation.
href	string	Yes	Site route or absolute URL. Site routes should start with /.
children	array of nav entries	No	Nested dropdown entries. Each child has the same title, href, and optional children fields.

Example:

[[site.nav]]
title = "Product"
href = "/product/overview/"

[[site.nav.children]]
title = "Platform overview"
href = "/product/overview/"

[[site.nav.children]]
title = "Resources"
href = "/docs/intro/"

[[site.nav.children.children]]
title = "Documentation"
href = "/docs/intro/"

The dropdown is generated from data, not from hand-written HTML. Keep href on parent items even when they have children, because keyboard users and search engines still need a normal destination for the parent item. The menu can nest beyond three levels, but a production navigation should stay shallow enough that users can scan it quickly.

Blog navigation is generated from content metadata instead of global dropdown children. When a [[site.routes]] entry uses path = "/blog", the static-site shell generates /blog/ if you have not provided a Markdown file for it. That landing page lists recent posts, categories, and tags. Individual posts also get older/newer post links unless a post disables them in front matter.

[[site.routes]]

Each [[site.routes]] entry maps a content directory to generated routes. If no routes are configured, Fission uses content/ at /content.

Field	Type	Required	Default	Meaning
kind	string	No	content	Only content routes are currently consumed. Other values are ignored by the content-route loader.
path	string	Yes	none	URL prefix for generated pages, such as /docs, /reference, or /blog.
source	string	Yes	none	Project-relative directory containing .md or .mdx files. The directory must exist and contain Markdown files.
template	string	No	default documentation page	Template identity. fission::site::documentation selects the standard documentation layout in the current site app.
sidebar	string	No	none	Project-relative TOML file describing left-sidebar entries for this content route.

Example:

[[site.routes]]
kind = "content"
path = "/reference"
source = "content/reference"
template = "fission::site::documentation"
sidebar = "site/reference-sidebar.toml"

Content route front matter

Markdown and MDX files may start with front matter. The static-site shell reads these fields before rendering the page body.

Field	Type	Required	Default	Meaning
title	string	No	File stem converted to title case	Page title used in headings, browser metadata, search, sidebars, and blog lists.
description	string	No	none	Page summary used in SEO metadata, search excerpts, and generated blog landing entries.
authors	array of strings	No	[]	Author identifiers for blog and release posts.
tags	array of strings	No	[]	Topic labels used by the generated blog landing page, blog sidebar taxonomy, and article chips.
categories	array of strings	No	[]	Higher-level group labels used by the generated blog landing page, blog sidebar taxonomy, and article chips.
show_adjacent_posts	boolean	No	true for blog posts, false otherwise	Shows older/newer post links below a blog article.
prev_next	boolean	No	same as show_adjacent_posts	Alias accepted for authors who prefer shorter front matter.

Example:

---
title: Fission 0.4.0
description: A release note for the authoring API update.
authors:
  - fission
categories:
  - Releases
tags:
  - release
  - authoring
show_adjacent_posts: true
---

# Fission 0.4.0

Write the post body here.

[[site.elements]]

[[site.elements]] inserts raw trusted document-level HTML. Use it for analytics snippets, verification tags, consent scripts, preload hints, or other document features that do not belong in a Fission widget.

Field	Type	Required	Accepted values / condition	Meaning
placement	string	Yes	head-start, head-end, body-start, body-end; underscores and head:start/body:end aliases are accepted	Where the raw HTML fragment is inserted.
html	string	Required unless file is set	Mutually exclusive with file	Inline raw HTML.
file	string	Required unless html is set	Mutually exclusive with html	Project-relative file containing raw HTML.
routes	array of strings	No	[]	Exact route filters. Empty means every route unless route_prefixes is set.
route_prefixes	array of strings	No	[]	Prefix route filters, such as /docs/.

Exactly one of html or file must be set. Setting both is an error.

[site.code_highlighting]

Code highlighting is optional and only loads highlighting assets on pages that contain code blocks.

Field	Type	Required	Default	Meaning
enabled	boolean	No	false	Enables client-side code highlighting.
stylesheet_href	string	No	hosted Highlight.js dark CSS URL	CSS URL inserted on pages with code blocks.
script_src	string	No	hosted Highlight.js script URL	Script URL inserted on pages with code blocks.

[site.search]

Client-side search is optional. When enabled, the build writes a local search index and script into the generated site.

Field	Type	Required	Default	Meaning
enabled	boolean	No	false	Enables generated client-side search assets.
output_path	string	No	search	Output directory below the site root for search.js, manifest.json, document metadata, and shards.
min_token_len	integer	No	2	Minimum token length included in the search index.

[server]

[server] configures the server-rendered web target. It is used by fission server ..., fission run --target server, and fission package --target server --format docker-image.

Field	Type	Required	Default	Meaning
entry	string	Yes for server commands	none	Rust path to the function that returns the FissionServerApp, such as pokemon_card_store::pokemon_card_store_server. The top-level CLI reads this field and generates/runs the server binary entrypoint.
default_locale	string	No	en	Locale written to the rendered HTML lang attribute unless a route or future locale layer overrides it.
default_route_mode	string	No	app default	Route mode applied to routes declared through the default server route helper. Accepted values are static, server, dynamic, server_private, private, revalidated, client_app, and client. dynamic is an alias for server; private is an alias for server_private.
render_pass_limit	integer	No	4	Maximum render passes allowed while jobs/resources settle before the server returns HTML. fission server check, fission server serve, and the server binary read this value.

Route modes are intentionally explicit. Use server_private for pages that depend on a session or user, server for request-rendered public pages, and revalidated for public pages that can be cached and reconverted after a TTL. Fission rejects a revalidated page if the rendered HTML contains signed server action forms, because action tokens are request-specific.

[server.http]

[server.http] controls public HTTP metadata used by generated pages. It does not replace the production web server, load balancer, or reverse proxy; it gives Fission enough information to produce correct canonical links.

Field	Type	Required	Default	Meaning
base_url	string	No	none	Absolute public origin used for canonical URLs, such as https://shop.example. A trailing slash is accepted and normalized away.
trust_proxy_headers	boolean	No	false	When true and base_url is absent, Fission may derive canonical URLs from X-Forwarded-Proto and X-Forwarded-Host. Enable this only behind a trusted proxy that overwrites those headers.

Example:

[server.http]
base_url = "https://cards.example"
trust_proxy_headers = false

[server.sessions]

[server.sessions] configures the built-in cookie session identifier used by ServerPrivate routes. The current provider stores only an opaque session id in the browser. App data still belongs in your service layer, database, cache, or other server-owned store keyed by that session id.

Field	Type	Required	Default	Meaning
provider	string	No	cookie	Session id transport. cookie is the currently supported provider.
cookie_name	string	No	fission_session	Name of the session cookie. It must be a valid HTTP cookie token.
signing_key_env	string	No	none	Environment variable containing the secret used to sign session cookie values. When set, Fission rejects tampered session cookies and creates a new session.
secure	boolean	No	false	Adds the Secure cookie flag. Set this to true in HTTPS production deployments.
same_site	string	No	lax	Cookie SameSite mode. Accepted values are strict, lax, and none. none requires secure = true.

Example:

[server.sessions]
cookie_name = "shop_session"
signing_key_env = "SHOP_SESSION_SECRET"
secure = true
same_site = "lax"

[server.cache]

[server.cache] selects the cache used for revalidated full pages and other server cache entries. The default is an in-process Moka cache. Redis is available when the server shell is built with the Redis feature, for example through the facade feature server-redis.

Field	Type	Required	Default	Meaning
provider	string	No	moka	Cache backend. Accepted values are moka, redis, and pipeline.
max_capacity	integer	No	10000	Maximum number of entries for the Moka in-memory provider.
ttl	duration string	No	route default	Default time-to-live used when default_route_mode = "revalidated" creates a route policy. Examples: 30s, 5m, 2h, 1d. default_ttl is accepted as an alias.
stale_while_revalidate	duration string	No	none	Stale window used when default_route_mode = "revalidated" creates a route policy. A stale entry can be served inside this window while the server prepares a fresh render.
redis_url	string	Required when Redis is selected and url_env is absent	none	Redis connection URL. url is accepted as an alias. Prefer url_env for production secrets.
url_env	string	Required when Redis is selected and redis_url is absent	none	Environment variable that contains the Redis connection URL.
redis_prefix	string	No	fission	Key prefix used by the Redis cache provider. prefix is accepted as an alias.

Example in-memory cache:

[server.cache]
provider = "moka"
max_capacity = 10000
ttl = "5m"
stale_while_revalidate = "1m"

Example Redis cache:

[server.cache]
provider = "redis"
url_env = "REDIS_URL"
prefix = "shop"

Revalidated route tags are set in code through RevalidationPolicy::tag(...) or RevalidationPolicy::tags(...). After a write, invalidate those tags through ServerRenderer::invalidate_cache_tag(...), ServerRenderer::invalidate_cache_tags(...), or the direct cache handle returned by ServerRenderer::cache().

[[server.cache.layers]]

Use a cache pipeline when you want multiple cache layers, such as a small process-local hot cache in front of Redis. The table is valid only when [server.cache].provider = "pipeline".

Field	Type	Required	Default	Meaning
name	string	No	layer-<index>	Human-readable layer name. It is also used as the Redis prefix fallback for that layer.
provider	string	No	moka	Layer provider. Accepted values are moka and redis. Nested pipelines are rejected.
policy	string	No	write-through	Layer write policy. Accepted values are write-through, read-only, and hot-only.
max_capacity	integer	No	10000	Maximum number of entries for a Moka layer.
redis_url / url	string	Required for Redis when url_env is absent	none	Redis connection URL for this layer.
url_env	string	Required for Redis when URL is absent	none	Environment variable containing the Redis URL for this layer.
redis_prefix / prefix	string	No	layer name	Redis key prefix for this layer.

Example layered cache:

[server.cache]
provider = "pipeline"

[[server.cache.layers]]
name = "hot"
provider = "moka"
policy = "hot-only"
max_capacity = 2048

[[server.cache.layers]]
name = "shared"
provider = "redis"
policy = "write-through"
url_env = "REDIS_URL"
prefix = "shop"

[server.workers]

[server.workers] controls progressive browser workers declared on server routes. Workers are compiled as separate route-local browser artifacts; the server runtime serves them from /assets/....

Field	Type	Required	Default	Meaning
separate_artifacts	boolean	No	true	Must be true today. Fission rejects false because workers are intentionally compiled as separate artifacts.
bridge	string	No	generated	Browser bridge mode for generated worker shims. generated is the current supported value.

[server.islands]

[server.islands] controls focused browser-side WASM islands declared on server routes. Islands can be full Fission widget sub-apps with their own state, reducers, and HTML bridge output.

Field	Type	Required	Default	Meaning
separate_artifacts	boolean	No	true	Must be true today. Fission rejects false because islands are intentionally compiled as separate artifacts.
preload	string	No	route	Preload policy for island and worker artifacts. route emits preload links for artifacts used by the current route; none disables those preload links.

[package]

[package] contains packaging and signing references. It is read by fission package, fission signing ..., and readiness checks.

Field	Type	Required	Meaning
icon	string	No	Legacy shorthand for [package.icons].source. Prefer [package.icons] for new projects because it supports target-specific icon sources.

[package.icons]

[package.icons] declares the application icon sources used by generated run bundles, platform packages, and release readiness checks. assets/app-icon.png is only the default seed written by fission init; it is not the only supported icon path.

Use the shared source when one high-resolution icon can represent the app everywhere. Add platform-specific overrides when a platform needs a different source, file format, silhouette, background plate, or store treatment. All paths are project-relative.

fission add-target, fission run, and fission package preserve this table when they update targets, capabilities, or generated platform files. For Android and iOS, adding or syncing a mobile target copies configured platform icons into platforms/android/res/... or platforms/ios/AppIcon.* so the checked-in platform scaffold remains reproducible. Desktop development bundles resolve the same table at run/package time and copy the selected icon into the generated .app, Linux desktop bundle, or Windows development bundle.

Field	Type	Required	Default	Meaning
mode	string	No	generate	Icon handling intent. generate means Fission may generate platform outputs from sources, provided means the project supplies target-ready files, and mixed means platform-provided outputs win while missing outputs can be generated. Current run/package flows consume the declared sources directly and validate paths early.
source	string	No	assets/app-icon.png fallback	Shared full-colour launcher icon source. The file must be usable by every target that falls back to it; set platform-specific overrides when one format does not work everywhere.
monochrome	string	No	none	Shared monochrome/silhouette source for platforms that support themed icons.
background_color	string	No	none	Hex colour used when a target icon requires a background plate and no platform-specific background is supplied.
safe_zone	string or number	No	platform	Padding/cropping intent for generated icon outputs. Accepted design values are platform, none, or a numeric fraction such as 0.72.
allow_upscale	boolean	No	true	Whether generated icon output may enlarge raster sources when a target output needs more pixels than the source provides. Current development run bundles validate and copy the selected source directly; release icon generation uses this as a quality rule.

Example:

[package.icons]
mode = "mixed"
source = "assets/brand/app-icon.png"
monochrome = "assets/brand/app-icon-monochrome.svg"
background_color = "#07111F"
safe_zone = "platform"
allow_upscale = false

[package.icons.android]

Field	Type	Required	Meaning
source	string	No	Android launcher icon source. Current generated Android packages copy PNG, JPEG, WebP, or XML drawable sources into the APK resource set as app_icon.
foreground	string	No	Adaptive-icon foreground source. If source is omitted, current generated packages use this as the launcher icon source.
background	string	No	Adaptive-icon background source or plate.
monochrome	string	No	Android themed-icon monochrome source.

[package.icons.ios]

Field	Type	Required	Meaning
source	string	No	iOS app icon source copied into generated simulator bundles as AppIcon.*. Use PNG for best compatibility with the current simulator bundle flow.
dark	string	No	Dark appearance app icon source for release icon generation.
tinted	string	No	Tinted appearance app icon source for release icon generation.

[package.icons.macos]

Field	Type	Required	Meaning
source	string	No	macOS bundle icon source. .icns is preferred for release packages; PNG is accepted by current development bundles.

[package.icons.windows]

Field	Type	Required	Meaning
source	string	No	Windows app icon source. .ico is preferred for packaged release output; PNG is accepted by current development bundles.
light	string	No	Light-theme tile/icon source for package generation.
dark	string	No	Dark-theme tile/icon source for package generation.
unplated	string	No	Unplated Store icon source.

[package.icons.linux]

Field	Type	Required	Meaning
source	string	No	Linux desktop icon source. SVG is copied to the scalable icon directory; PNG is copied to the generated hicolor bitmap icon directory.

[package.icons.web]

Field	Type	Required	Meaning
source	string	No	Web app icon source used by web packaging flows.
favicon	string	No	Browser favicon source for web/package metadata. Static sites separately use [site].favicon.
maskable	string	No	Maskable web app icon source.

[package.docker]

[package.docker] configures fission package --format docker-image for static sites and server-rendered sites.

Field	Type	Required	Default	Meaning
adapter	string	No	axum	Static-site image server adapter. Accepted values are axum and actix. Server-rendered app images ignore this field because the app binary is the server.
port	integer	No	8080	Container port exposed by the generated Dockerfile and used as the default PORT environment value.
base_image	string	No	debian:bookworm-slim	Runtime stage base image. The builder stage uses the official Rust image because the package is compiled inside the Docker build.
tags	array of strings	No	<app-name>:<cargo-version>	Docker tags applied during docker build. Include registry prefixes here when you want the package step to tag for publishing.
build	boolean	No	true	When true, Fission runs docker build. Set to false to generate only the Docker context and manifest for CI to build later.

Example:

[package.docker]
adapter = "axum"
port = 8080
tags = ["ghcr.io/example/pokemon-card-store:0.1.0", "ghcr.io/example/pokemon-card-store:latest"]

[package.macos]

Field	Type	Required	Meaning
bundle_id	string	No	Overrides [app].app_id for macOS .app and .pkg output.
minimum_os	string	No	Records the intended minimum macOS version for package metadata.
entitlements	string	No	Project-relative entitlements plist passed to codesign when signing.
signing_identity	string	No	Developer ID/Application identity used to sign .app bundles. If omitted, the app is not code-signed by Fission.
installer_identity	string	No	Developer ID Installer identity passed to pkgbuild/productbuild for .pkg output.
notarize	boolean	No	When true, notarization requires APP_STORE_CONNECT_API_KEY_PATH, APP_STORE_CONNECT_KEY_ID, and APP_STORE_CONNECT_ISSUER_ID.

[package.android]

Field	Type	Required	Meaning
keystore	string	No	Project-relative upload/signing keystore path recorded for signing readiness.
upload_keystore	string	No	Alternate upload keystore path for app-store release workflows.
keystore_alias	string	No	Alias inside the keystore.
package_name	string	Required for Android signing readiness	Android package name expected by signing/release checks. Usually matches [app].app_id.

Keystore passwords are not stored in fission.toml. Use ANDROID_KEYSTORE_PASSWORD and ANDROID_KEY_PASSWORD or an OS/CI secret store.

[package.ios]

Field	Type	Required	Meaning
bundle_id	string	No	iOS bundle identifier used by signing readiness. Usually matches [app].app_id.
team_id	string	No	Apple Developer Team ID for signing workflows.
entitlements	string	No	Project-relative entitlements plist.
provisioning_profile	string	No	Project-relative provisioning profile reference.
signing_identity	string	No	Signing identity for release packaging.

[package.windows]

Field	Type	Required	Meaning
identity_name	string	No	MSIX package identity name.
publisher	string	No	Windows package publisher distinguished name.
certificate	string	No	Project-relative certificate file reference.
certificate_thumbprint	string	No	Certificate thumbprint used when signing through the Windows certificate store.

Certificate passwords are not stored in fission.toml. Use WINDOWS_CERTIFICATE_PASSWORD or an OS/CI secret store.

[[package.secondary_artifacts]], [[package.symbols]], and [[package.crash_assets]]

These entries add extra files or directories to the artifact manifest. [[package.symbols]] defaults kind to debug_symbols; [[package.crash_assets]] defaults kind to crash_diagnostics.

Field	Type	Required	Meaning
path	string	Required to include an artifact	File or directory to add. The path must exist during packaging.
kind	string	No	Artifact kind. Defaults to secondary_artifact, debug_symbols, or crash_diagnostics depending on the table.
purpose	string	No	Human-readable purpose. Defaults to kind.
platform	string	No	Platform label recorded in the artifact manifest.
upload_provider	string	Recommended for symbols/crash assets	Provider or backend that should receive this artifact.

[distribution]

[distribution] configures publishing providers. Provider names in CLI flags use kebab-case, such as github-pages; TOML table names use snake_case, such as distribution.github_pages.production.

Distribution providers that support multiple profiles use [distribution.<provider>.<profile>]. The CLI selects a profile with --site, defaulting to production. Store providers currently use one table per provider instead of named profiles.

[distribution.github_pages.<profile>]

Field	Type	Required	Accepted values / default	Meaning
owner	string	Required unless inferable	GitHub owner/user/org	Repository owner. If omitted, Fission tries to infer it from the origin remote.
repo	string	Required unless inferable	repository name	Repository name. If omitted, Fission tries to infer it from the origin remote.
mode	string	No	actions; publish supports actions and branch; readiness also recognizes manual	Publishing model. actions generates/follows a workflow; branch pushes static output to a Pages branch.
source	string	No	github-actions	Pages source mode expected by readiness for Actions publishing.
source_branch	string	No	gh-pages for branch mode	Branch used by branch-mode publishing.
source_path	string	No	/	Subdirectory on the Pages branch used by branch-mode publishing.
site_kind	string	No	project site	user or organization means root Pages URL; otherwise project Pages URL is assumed.
base_path	string	No	computed from site_kind, repo, and custom domain	Expected site base path. Custom domains use /; project sites usually use /<repo>/.
custom_domain	string	No	none	Domain written to CNAME in branch mode and reported in receipts.
enforce_https	boolean	No	true	Recorded HTTPS policy for readiness/follow-up.
remote	string	No	origin	Git remote used by branch-mode publishing.
production_branch	string	No	main	Branch the generated workflow listens to.
workflow	string	No	fission-pages.yml	Workflow filename under .github/workflows/ for Actions mode.

[distribution.github_releases.<profile>]

Field	Type	Required	Accepted values / default	Meaning
owner	string	Required unless inferable	GitHub owner/user/org	Repository owner. If omitted, Fission tries to infer it from the origin remote.
repo	string	Required unless inferable	repository name	Repository name. If omitted, Fission tries to infer it from the origin remote.
tag	string	Required unless --deploy or Cargo version resolves one	release tag	Release tag. If omitted, Fission uses --deploy, then v<package.version> from Cargo metadata.
name	string	No	none	Release title passed to gh release create/edit --title.
target_commitish	string	No	provider default	Git ref passed as the release target.
notes	string	No	none	Inline release notes. If set, it wins over notes_file.
notes_file	string	No	none	Project-relative release notes file passed to gh. Used only when notes is absent.
draft	boolean	No	false	Creates/updates a draft release.
prerelease	boolean	No	false	Marks the release as a prerelease.
make_latest	string	No	provider default	Accepted values are true, false, and legacy.
replace_assets	boolean	No	false	Uses gh release upload --clobber to replace assets with the same name.
upload_artifact_manifest	boolean	No	true	Uploads the Fission artifact manifest JSON alongside package assets.

GitHub Releases publishing uses the GitHub CLI. A developer can authenticate with gh auth login, GH_TOKEN, GITHUB_TOKEN, or a token imported into the Fission credential vault.

[distribution.docker_registry.<profile>]

Docker registry publishing pushes image tags produced by fission package --format docker-image. Fission uses the Docker CLI for authentication and push operations, so the normal setup is docker login <registry> before publishing.

Field	Type	Required	Meaning
tags	array of strings	Required unless image-metadata.json from the package contains tags	Fully qualified tags to push, such as ghcr.io/example/app:1.0.0. If these tags differ from the package tags, Fission tags the local image before pushing.

Example:

[distribution.docker_registry.production]
tags = ["ghcr.io/example/pokemon-card-store:0.1.0", "ghcr.io/example/pokemon-card-store:latest"]

[distribution.cloudflare_pages.<profile>]

Field	Type	Required	Default	Meaning
account_id	string	Required unless CLOUDFLARE_ACCOUNT_ID is set	none	Cloudflare account id.
project_name	string	Yes	none	Pages project name.
environment	string	No	production	Non-production environments are passed as a branch to the provider CLI.
custom_domain	string	No	none	Public custom domain reported in receipts.
base_path	string	No	/	Should normally stay / for dedicated static hosting.

Cloudflare Pages upload intentionally shells out to the provider CLI. Fission does not implement a replacement deploy protocol.

[distribution.netlify.<profile>]

Field	Type	Required	Meaning
site_id	string	Yes	Netlify site id.
team_slug	string	No	Team slug shown during setup/status.
production	boolean	No	Whether the deploy should target production behavior.
custom_domain	string	No	Public custom domain reported in receipts.
base_path	string	No	Should normally stay / for dedicated static hosting.

[distribution.s3.<profile>]

Field	Type	Required	Default	Meaning
bucket	string	Yes	none	S3-compatible bucket name.
endpoint	string	No	provider default	Custom endpoint for S3-compatible object stores.
region	string	No	us-east-1 for URL generation	Region used by the S3 client/provider.
prefix	string	No	none	Remote object prefix.
profile	string	No	environment/provider default	Credential/profile name for provider SDK/tooling.
path_style	boolean	No	false	Enables path-style endpoint URLs.
visibility	string	No	private	Use public when the uploaded files should produce public URLs.
presign_ttl_seconds	integer	No	provider default	TTL for generated presigned links where used.

[distribution.google_drive.<profile>]

Field	Type	Required	Default	Meaning
folder_id	string	No	root/current provider default	Parent folder id. When set, uploaded files are placed in that folder.
name_prefix	string	No	none	Prefix applied to uploaded file names.
share	boolean	No	false	Requests shareable links after upload.

[distribution.onedrive.<profile>]

Field	Type	Required	Default	Meaning
root	string	No	provider default	OneDrive root selector used by the Graph upload backend.
path_prefix	string	No	none	Remote path prefix.
conflict_behavior	string	No	replace	Conflict behavior sent to the provider, such as replace, rename, or fail depending on provider support.

[distribution.dropbox.<profile>]

Field	Type	Required	Default	Meaning
path_prefix	string	No	none	Remote Dropbox path prefix.
mode	string	No	overwrite	Dropbox write mode.
autorename	boolean	No	false	Allows Dropbox to rename conflicting uploads.

[distribution.play_store]

Field	Type	Required	Default	Meaning
package_name	string	Required for Play publish, metadata, reviews, and beta operations	none	Android package name in Google Play.
default_track	string	No	command/provider default	Track used when --track is omitted.
service_account	string	No	environment/vault	Service-account JSON path, inline JSON, or token source used by release tooling when environment/vault credentials are absent.
release_status	string	No	provider default	Track release status sent to Play publishing.

Credentials can also come from PLAY_STORE_ACCESS_TOKEN, PLAY_STORE_SERVICE_ACCOUNT_JSON, GOOGLE_APPLICATION_CREDENTIALS, or the Fission credential vault.

[distribution.app_store]

Field	Type	Required	Meaning
app_id	string	Required unless bundle_id can resolve the app through the provider API	App Store Connect app id.
bundle_id	string	Required when app_id is omitted	Bundle id used to look up the app.
issuer_id	string	Required unless APP_STORE_CONNECT_ISSUER_ID is set	App Store Connect issuer id.
key_id	string	Required unless APP_STORE_CONNECT_KEY_ID is set	App Store Connect API key id.
api_key_path	string	Required unless key material comes from env/vault	Path to .p8 API key.
default_track	string	No	Default release/beta track label for commands that accept tracks.

API key material can also come from APP_STORE_CONNECT_API_KEY, APP_STORE_CONNECT_API_KEY_PATH, or the Fission credential vault.

[distribution.microsoft_store]

Field	Type	Required	Accepted values / meaning
product_id	string	Required	Microsoft Store product id.
package_identity_name	string	No	Package identity name for package metadata.
tenant_id	string	Required unless AZURE_TENANT_ID or PARTNER_CENTER_TENANT_ID is set	Microsoft Entra tenant id.
client_id	string	Required unless AZURE_CLIENT_ID or PARTNER_CENTER_CLIENT_ID is set	Microsoft Entra client id.
seller_id	string	Required unless MICROSOFT_STORE_SELLER_ID or PARTNER_CENTER_SELLER_ID is set	Partner Center seller id.
package_url	string	Required for MSI/EXE Store submissions unless --deploy <https-url> supplies one	HTTPS URL to an uploaded package.
package_type	string	No	Usually exe, msi, msix, or msixupload; if omitted, Fission infers from the primary artifact extension.
flight_id	string	Required for MSIX private flight when --track private is used	Package flight id. Passing a non-empty custom --track can also be treated as a flight id.
package_rollout_percentage	integer	No	Must be between 0 and 100.
msstore_project	string	No	Project directory passed to Microsoft Store Developer CLI for MSIX publishing. Defaults to the Fission project root.
msstore_reconfigure	boolean	No	When true, Fission attempts to configure the provider CLI using configured credentials before publishing.
languages	array of strings	No	Listing/package languages for provider setup.
architectures	array of strings	No	Package architectures for provider setup.
is_silent_install	boolean	No	Installer metadata for MSI/EXE submissions.
installer_parameters	string	No	Installer command-line parameters for MSI/EXE submissions.
generic_doc_url	string	No	Documentation/support URL for installer submissions.
submit	boolean	No	When true, publishes/submits instead of creating a non-committed package submission where the backend supports that distinction.

The Microsoft Store provider supports both Store API metadata operations and MSIX-specific publishing through the platform provider tooling. Fission uses the provider tooling/API; it does not build a custom replacement for platform submission systems.

[release] and [[releases]]

Release configuration keeps long content out of fission.toml by referencing sidecar files.

[release]

Field	Type	Required for release-config validate	Meaning
active_release	string	Yes	Id of the [[releases]] entry currently being edited, validated, or pushed.
metadata_root	string	Yes	Root directory for release metadata sidecar files.
content_output_dir	string	Yes	Output directory for generated/captured release content.
default_locales	array of strings	Yes	Locales used when a release entry does not override locales.

[[releases]]

Field	Type	Required	Meaning
id	string	Required when referenced by release.active_release	Stable release id, commonly <version>+<build>.
version	string	Yes for validation and App Store metadata sync	User-facing version string.
build	integer	Yes for validation	Monotonically increasing platform build number.
status	string	Yes for validation	Release status label, such as candidate, internal, or production. Fission records the string and provider-specific commands interpret tracks/status separately.
tracks	array of strings	Yes for validation	Provider destinations, such as play-store:internal, app-store:testflight, or microsoft-store:public.
locales	array of strings	No	Overrides release.default_locales for this release.
metadata	string	Yes for validation	Project-relative sidecar file with provider-specific localized metadata.
release_notes	string	Yes for validation	Project-relative directory containing localized <locale>.md release notes.
review	string	No	Project-relative review-instructions sidecar file.
privacy	string	No	Project-relative privacy sidecar file.

[release.store_listing.<provider>.<locale>]

Store listing tables hold short stable listing fields. Long localized paragraphs still belong in the active release metadata sidecar file referenced by [[releases]].metadata.

Provider keys currently read from fission.toml are play_store, app_store, and microsoft_store.

Field	Providers	Type	Required condition	Meaning
title	all	string	Required for Play if name is absent	Store title.
name	all	string	Alternative to title for Play; also read by App Store/Microsoft metadata flows	Store display name.
short_description	Play, Microsoft	string	Required for Play listing push; recommended for Microsoft	Short store summary.
subtitle	App Store, Microsoft	string	No	Subtitle where supported.
keywords	App Store, Microsoft	array of strings	No	Search keywords. App Store joins these for provider payloads.
support_url	App Store, Microsoft	string	Recommended/required by some store review flows	Support URL.
marketing_url	App Store	string	No	Marketing URL.
privacy_url	all	string	Recommended/required by store policy	Privacy URL.
video	Play	string	No	Play listing video URL.
video_url	Play	string	No	Alternate video URL field accepted by the local schema.

The release metadata sidecar referenced by [[releases]].metadata can contain:

[play_store.en-US]
full_description = "Long Play Store description."
description = "Optional shorter description."

[app_store.en-US]
description = "Long App Store description."
promotional_text = "Optional promotional text."

[microsoft_store.en-US]
description = "Long Microsoft Store description."
features = ["Fast", "Private", "Cross-platform"]
search_terms = ["notes", "tasks"]

[release.screenshots] and [release.assets]

Release-content settings live under [release] because screenshots, preview media, and store assets are part of the release lifecycle.

[release.screenshots]

Field	Type	Required	Default	Meaning
raw_dir	string	No	release-content/screenshots/raw	Directory where raw captures are written/read.
rendered_dir	string	No	release-content/screenshots/rendered	Directory where store-ready rendered assets are written.

[[release.screenshots.scenarios]]

Field	Type	Required	Meaning
id	string	Yes for useful output names	Stable scenario id.
name	string	No	Human-readable scenario name.
targets	array of strings	No	Target labels this scenario applies to.
script	string	Required unless command is set	Project-relative script started before capture.
command	string	Required unless script is set	Command started before capture.
test_port	integer	No	Test-control port. If omitted, Fission chooses a free loopback port.
timeout_ms	integer	No	Timeout while waiting for the test-control server.
wait_for	string	No	Reserved wait condition label for scenario orchestration.

[[release.screenshots.scenarios.steps]]

Field	Type	Required	Meaning
cmd	string	Yes	One of tap_text, type_text, press_key, tap, scroll, wait, pump, resize, screenshot, capture_screenshot.
text	string	Required for tap_text and type_text	Text to tap or type.
key	string	Required for press_key	Key name.
modifiers	integer	No	Modifier bitset for press_key; defaults to 0.
ms	integer	No	Wait duration for wait; defaults to 250.
x, y	numbers	Required for tap; optional origins for scroll	Coordinates.
dx, dy	numbers	No	Scroll deltas; default to 0.
width, height	integers	Required for resize	Simulated viewport size.
name	string	No	Screenshot filename label.
path	string	No	Explicit screenshot path below raw_dir.

[release.assets.app_store], [release.assets.play_store], and [release.assets.microsoft_store]

Table	Field	Type	Meaning
[release.assets.app_store]	screenshot_sets_dir	string	Directory containing App Store screenshot sets.
[release.assets.app_store]	app_previews_dir	string	Directory containing App Store preview videos.
[release.assets.app_store]	review_attachments	array of strings	Project-relative files attached for review workflows.
[release.assets.play_store]	screenshot_sets_dir	string	Directory containing Play Store screenshot sets.
[release.assets.play_store]	preview_video_dir	string	Directory containing Play preview videos.
[release.assets.play_store]	feature_graphic	string	Feature graphic path.
[release.assets.microsoft_store]	screenshot_sets_dir	string	Directory containing Microsoft Store screenshots.
[release.assets.microsoft_store]	trailers_dir	string	Directory containing trailers.
[release.assets.microsoft_store]	logo_dir	string	Directory containing Store logos.

[beta.play_store.tracks.<track>]

Beta group configuration currently reads Google Play track tester configuration from fission.toml.

Field	Type	Required	Meaning
tester_source	string	No	Source label for tester/group sync.
group	string	No	One tester group email/name.
groups	array of strings	No	Additional tester groups.

App Store beta operations use provider API groups and command flags today rather than a dedicated fission.toml beta table.

[release_workflows.<name>]

Release workflows let a project name repeatable lifecycle command sequences.

Field	Type	Required	Meaning
commands	array of strings	Yes	Commands run by fission release-workflow run <name>. Each string is split with shell-like quoting and executed through the current fission binary.

Example:

[release_workflows.production]
commands = [
  "readiness package --target site --format static --release",
  "package --target site --format static --release",
  "distribute publish --provider github-pages --site production --yes",
]

Complete static site example

targets = ["site"]

[app]
name = "example-docs"
app_id = "com.example.docs"

[site]
entry = "crate::site_app"
title = "Example Docs"
description = "Documentation and marketing pages for Example."
base_url = "https://docs.example.com"
base_path = "/"
canonical_url = "https://docs.example.com"
out_dir = "dist/site"
default_locale = "en-GB"
generate_sitemap = true
generate_robots = true
logo = "/img/logo.svg"
favicon = "/img/favicon.svg"
asset_dirs = ["static"]
css_files = ["site/overrides.css"]

[site.code_highlighting]
enabled = true

[site.search]
enabled = true
output_path = "search"
min_token_len = 2

[package.docker]
adapter = "axum"
port = 8080
tags = ["ghcr.io/example/example-docs:1.0.0"]

[[site.nav]]
title = "Learn"
href = "/docs/learn/overview/"

[[site.routes]]
kind = "content"
path = "/docs"
source = "content/docs"
template = "fission::site::documentation"
sidebar = "site/docs-sidebar.toml"

[[site.elements]]
placement = "head-end"
file = "site/analytics.html"
route_prefixes = ["/docs/", "/reference/"]

[distribution.github_pages.production]
owner = "example"
repo = "example-docs"
mode = "actions"
source = "github-actions"
site_kind = "project"
base_path = "/"
custom_domain = "docs.example.com"
enforce_https = true
workflow = "publish-website.yml"
production_branch = "main"

[distribution.docker_registry.production]
tags = ["ghcr.io/example/example-docs:1.0.0"]

Complete server-rendered site example

targets = ["server"]

[app]
name = "pokemon-card-store"
app_id = "ai.worka.fission.examples.pokemon-card-store"

[server]
entry = "pokemon_card_store::pokemon_card_store_server"
default_route_mode = "server_private"
render_pass_limit = 4

[server.cache]
provider = "moka"
max_capacity = 10000
ttl = "5m"
stale_while_revalidate = "1m"

[server.workers]
separate_artifacts = true
bridge = "generated"

[server.islands]
separate_artifacts = true
preload = "route"

[package.docker]
port = 8080
tags = ["ghcr.io/example/pokemon-card-store:0.1.0"]

[distribution.docker_registry.production]
tags = ["ghcr.io/example/pokemon-card-store:0.1.0"]

Complete release skeleton

targets = ["android", "ios", "windows", "macos", "linux"]
capabilities = ["camera", "geolocation", "notifications"]

[app]
name = "example-app"
app_id = "com.example.app"

[package.android]
package_name = "com.example.app"
keystore = "release-content/signing/android/upload.keystore"
keystore_alias = "upload"

[package.ios]
bundle_id = "com.example.app"
team_id = "ABCDE12345"
entitlements = "platforms/ios/Entitlements.plist"
provisioning_profile = "release-content/signing/ios/App.mobileprovision"

[package.macos]
bundle_id = "com.example.app"
signing_identity = "Developer ID Application: Example Ltd"
installer_identity = "Developer ID Installer: Example Ltd"
entitlements = "platforms/macos/Entitlements.plist"
notarize = true

[package.windows]
identity_name = "Example.App"
publisher = "CN=Example Ltd"
certificate_thumbprint = "0123456789ABCDEF"

[distribution.play_store]
package_name = "com.example.app"
default_track = "internal"
release_status = "draft"

[distribution.app_store]
bundle_id = "com.example.app"
issuer_id = "00000000-0000-0000-0000-000000000000"
key_id = "ABC123DEFG"
api_key_path = "release-content/signing/app-store/AuthKey_ABC123DEFG.p8"
default_track = "testflight"

[distribution.microsoft_store]
product_id = "9ABCDE12345"
package_type = "msix"
flight_id = "private-flight-id"
package_rollout_percentage = 10

[release]
active_release = "1.0.0+1"
metadata_root = "release-content/metadata"
content_output_dir = "release-content"
default_locales = ["en-US"]

[release.store_listing.play_store.en-US]
title = "Example App"
short_description = "A focused app for real work."
privacy_url = "https://example.com/privacy"
support_url = "https://example.com/support"

[[releases]]
id = "1.0.0+1"
version = "1.0.0"
build = 1
status = "candidate"
tracks = ["play-store:internal", "app-store:testflight", "microsoft-store:private"]
locales = ["en-US"]
metadata = "release-content/metadata/1.0.0+1/release.toml"
release_notes = "release-content/metadata/1.0.0+1/notes"
review = "release-content/metadata/1.0.0+1/review.toml"
privacy = "release-content/metadata/1.0.0+1/privacy.toml"

Validation commands

Use the reference above while editing, then let the CLI check the fields it can verify locally:

fission readiness package --target site --format static --project-dir .
fission readiness distribute --provider github-pages --site production --project-dir .
fission release-config validate --project-dir .
fission release-content validate --project-dir .
fission signing status --target android --project-dir .

Those commands do not replace provider review, store policy review, or platform signing setup. They catch missing paths, missing fields, unsupported target/format pairs, unavailable tools, and credentials that the local machine can see.