Bundle tools
@flower-js/sdk/bundle turns your TypeScript application into a deployable bundle. It is Node only; keep it out of the application itself.
| API | Contract |
|---|---|
BuildOptions | Optional initialization: "static" | "per-invocation". Default: static. |
buildBundle(entry: string, options = {}): Promise<Bundle> | Bundles a file whose default export is define(...), using esbuild. Returns the JavaScript and its SHA-256. Relative paths resolve from the current directory. |
loadBundle(path: string, options = {}): Promise<Bundle> | Builds a source file, or loads and verifies a .json bundle. A built bundle can’t take a new initialization. |
writeBundle(entry, output, options = {}): Promise<Bundle> | Builds and writes the JSON bundle. The output directory must exist. |
staticruns module setup once at deploy, includingdefine()and every component, without database access or randomness. Every callback starts from a copy-on-write snapshot of the result; a setup heap over 8 MiB falls back to the shared base image plus compiled code.per-invocationreruns module code in every callback. Use it only if setup must run per call.- Either way, each callback gets a fresh copy. Globals never persist.
- Bundled packages must be synchronous and need no filesystem or network.
- A bundle that builds may still fail to deploy. Deployment runs the code under real limits.
The flower CLI
Run npx flower in a project, or node sdk/cli.ts in a checkout. Commands print JSON. On failure they print the error to stderr and exit nonzero; a method’s failure prints as flower: CODE: message, followed by its details as JSON. watch prints one value per line until Ctrl-C.
| API | Contract |
|---|---|
build FILE [OUTPUT] | Builds a bundle. Default output: <basename>.flower.json in the current directory. |
deploy FILE | Builds a .ts file or loads a .json bundle, then deploys it. Needs an admin token. |
init --members ID=ADDR,... | Bootstraps a new cluster only. IDs are positive integers; addresses are host:port. |
call NAME [JSON_ARGS] | Calls any exposed alias. |
mutate NAME [JSON_ARGS] | Calls an exposed mutation or transaction. |
query NAME [JSON_ARGS] | Calls an exposed query. |
watch NAME [JSON_ARGS] | Watches a query and prints each new value. |
--url URL | Server URL. Falls back to FLOWER_URL, then http://127.0.0.1:7101. |
--admin-token TOKEN | Needed for admin commands. Or set FLOWER_ADMIN_TOKEN. |
--credentials JSON | Credentials for call, mutate, query and watch, checked by the app’s access rules. Or set FLOWER_CREDENTIALS. @file.json reads a file. |
--request-id ID | Idempotency key for call, mutate, deploy and key changes. Reuse it when retrying after an unclear failure. |
--expected-revision N | For call and mutate: fail unless the database is at this revision. |
--preparation MODE | Deploy only. online (default) keeps serving while preparing; blocking pauses writes. After DEPLOYMENT_CONFLICT, keep the same --request-id. |
--initialization MODE | static (default) or per-invocation, for build and deploy from source. |
--max-event-bytes N | Watch only; default 17,825,792. |
--max-value-bytes N | Watch only; default 16,777,216. |
--max-patch-operations N | Watch only; default 256. |
--partition ID | Target a named partition for application, deploy and key commands. |
key list | cache | List keys, or show key cache stats. See managed keys. |
key generate NAME --algorithm ALG [--bits N] | Generates a key on the server. --bits is for RSA only. |
key import NAME FILE --algorithm ALG | Imports a sealed (encrypted) JSON key. Use - for stdin. |
key bind ALIAS NAME --usages sign,verify,... | Lets the application use a key for the listed operations. |
key unbind ALIAS | Removes that permission. |
key rotate NAME [--bits N] | Creates a new key version and makes it current. |
key revoke NAME [--version N] | Revokes one version, or all of them. |
key retire NAME [--version N] | Limits versions to verify, decrypt and public-key use. |
key destroy NAME [--version N] | Deletes stored key material but keeps its metadata. Backups aren’t affected. |
key rewrap NAME [--version N] | Re-encrypts versions with the current wrapping key. Keep old wrapping keys mounted until it succeeds. |
--help / -h | Prints help. Flags take --name VALUE or --name=VALUE. Unknown or repeated flags are rejected. |
JSON_ARGSdefaults tonull. Use@file.jsonto read arguments from a file.- All key-changing commands accept
--request-id. None accept--expected-revision. - The CLI doesn’t retry, find the leader or reconnect watches. Use the operator HTTP APIs for membership changes.