Documentation / Packaging

Packaging and distribution#

blitsen build checks static output, collects reachable assets, links the target runtime and adds platform packaging. The default desktop result embeds the application in one executable.

Build a desktop artifact#

From project configuration:

npx blitsen build

From an existing output directory:

npx blitsen build dist --name "My App" --out MyApp

The build stops rather than replacing an existing output. Pass --force only when replacement is intentional.

Run the result on the target operating system and test startup, rendering, input, navigation, networking and shutdown. A successful build proves that the artifact was created, not that every application path is compatible.

Embedded and side-loaded assets#

The default embeds reachable application files:

npx blitsen build dist --assets embedded

Choose side-loaded assets for large or replaceable content:

npx blitsen build dist --assets side-loaded

This writes <output>.assets/ beside the executable. Distribute both together. On macOS Blitsen moves that directory inside the .app bundle beside its executable.

Files not reachable from index.html are omitted. Keep intentional runtime-loaded files with repeatable --include globs.

Names, icons and versions#

npx blitsen build dist \
  --name "My App" \
  --out MyApp \
  --icon assets/icon.png \
  --app-version 1.2.3

A PNG is converted into the target platform's normal icon form. You may also provide a native .ico, .icns or .svg where appropriate.

Packaging differs by target:

Set a stable macOS identity with --bundle-id com.example.myapp. --app-version is normalized for the target's metadata format.

Sign the artifact#

--sign runs a command after packaging and passes the finished artifact as its only positional argument:

npx blitsen build dist --sign 'codesign --force --sign "Developer ID Application: Example"'

On macOS the argument is the .app bundle; elsewhere it is the executable. A non-zero signing exit code fails the build. Blitsen never reads or stores signing credentials.

Signing is not notarization. Complete the platform's required release process after signing. In particular, distribute macOS applications only after notarization when Gatekeeper coverage matters.

Build for another desktop target#

npx blitsen build dist --target win32-x64 --out MyApp.exe

Supported triples are:

darwin-arm64  darwin-x64  linux-arm64  linux-x64  win32-arm64  win32-x64

Blitsen downloads and caches the exact runtime version for the requested target. Cross-building can create ELF, Mach-O and PE artifacts and their packaging files, but you still need the target system for realistic testing and usually for signing/notarization.

Native addons#

Carry a Node-API addon with project configuration or a repeatable flag:

npx blitsen build dist --addon native/physics.node

An application containing a .node addon uses the Bun-based host because the standard runtime has no Node-API implementation. This produces a much larger artifact and brings Bun/JavaScriptCore redistribution requirements that the default notice flow does not automate. Treat addons as an escape hatch and obtain a licensing review before distribution.

The addon must match the target operating system and architecture. Cross-building does not compile or translate it.

Build an Android APK#

Android is a separate artifact selected by --android, not a desktop target triple:

npx blitsen build dist --android --android-abi arm64-v8a --out MyApp.apk

The current Android entry crate is not published. Run from a Blitsen source checkout or point the CLI at one:

BLITSEN_ANDROID_CRATE=/path/to/blitsen/crates/blitsen-android \
  npx blitsen build dist --android --out MyApp.apk

The build machine needs:

• Rust targets for the requested Android ABIs and cargo-ndk
• Android SDK API 33, an NDK and build-tools containing aapt2, zipalign and apksigner
• libclang for generated QuickJS bindings
• A JDK for apksigner and keytool

Without an ABI option, the APK contains arm64-v8a and x86_64. Add --android-debug for an unoptimized native build whose manifest is marked debuggable.

Without --android-keystore, Blitsen uses the standard debug key. That APK is installable but not distributable. Supply release credentials without putting passwords on the command line:

BLITSEN_ANDROID_KEYSTORE_PASSWORD='...' \
  npx blitsen build dist \
  --android \
  --android-abi arm64-v8a \
  --android-package com.example.myapp \
  --android-keystore /path/to/release.jks \
  --app-version 1.2.3 \
  --out MyApp.apk

BLITSEN_ANDROID_KEY_ALIAS selects one key in a multi-key store. BLITSEN_ANDROID_KEY_PASSWORD supplies a distinct key password.

Android has no published platform package from which to copy audited notices. Set BLITSEN_NOTICES_PATH to the generated, audited NOTICES.txt for the Android crate before redistribution. Without it the build reports that the APK is not cleared for distribution.

Third-party notices#

Desktop exports embed the notices carried by the resolved runtime package. Inspect the actual artifact:

./MyApp --licenses

Keep those notices with every distributed copy and follow the source-availability terms named in them. Read Licensing for the obligations the default and addon-based exports carry.

Release checklist#

• Build fresh static output and run blitsen doctor for every target.
• Review every warning against a real application path.
• Build without --accept-errors unless a documented exception is intentional.
• Test the packaged artifact on each target operating system.
• Verify the application name, version, icon and bundle/package identity.
• Sign and, where required, notarize the final packaged artifact.
• Run the artifact with --licenses and retain all required notices/source offers.
• Test installation or extraction on a clean machine without a development toolchain.