flkr

Edit and publish your app's Flick views from the terminal.

npm install --global @flickfyi/flkr
flkr

Requires Node.js 24 or later. Run flkr from your app's Xcode project directory.

1. Quick start: sign in, edit views, and publish
2. Public-key infrastructure: authorize publication with your app's trust root
3. Continuous integration: publish from GitHub Actions with a delegate credential

Development

From the monorepo root:

bunx --no-install turbo run build --filter=@flickfyi/flkr
bun run --filter @flickfyi/flkr typecheck
bun run --filter @flickfyi/flkr lint
bun run --filter @flickfyi/flkr test

Build and install a release tarball locally:

bun run --filter @flickfyi/flkr pack:release
bun run --filter @flickfyi/flkr test:release "$PWD/.build-storage/flkr-release/flickfyi-flkr-0.0.0.tgz"

Packaging includes the internal JavaScript packages and their dependencies. TSRS stays an npm dependency so installation selects its native binary for the user's platform. The tarball test checks the executable, subcommands, and generated SDK discovery in a separate installation.

The pinned TSRS release ships compiler binaries for Apple Silicon macOS and Linux x64/arm64 (GNU and musl). It does not ship Windows or Intel macOS binaries.

The version comes from this package's package.json. Follow the release workflow's clean production-install steps before packing: it uses Bun's hoisted production layout with a workspace hoisting boundary so native bun pm pack includes the complete bundled dependency tree.

Pulling a canvas inside this monorepo registers its directory as a private Bun workspace. Core and Photon use workspace:*, so their source and builds stay local to the checkout. Bun updates the ordinary root manifest and lockfile; no package registration or path-link protocol is required. External Bun projects use published SDK dependencies, with React and editor type versions supplied by the SDK manifest.

npm releases

flkr-release.yml builds, checks, and installs the release tarball on PRs that change flkr or its dependencies. On merges to main, it publishes @flickfyi/flkr to npm with version 0.0.<GitHub run number>. Documentation-only changes to packages/flkr/docs/ do not publish a release.

The workspace and published package both use the name @flickfyi/flkr.

First publication

Before merging the release workflow, an npm account with publishing access to the @flickfyi scope must create the package. Use Node.js 24 or later, npm 11.5.1 or later, and an account with two-factor authentication enabled.

From the monorepo root, build and test the bootstrap version, then publish it using your own npm login:

bunx --no-install turbo run build --filter=@flickfyi/flkr
bun run --filter @flickfyi/flkr pack:release
bun run --filter @flickfyi/flkr test:release "$PWD/.build-storage/flkr-release/flickfyi-flkr-0.0.0.tgz"
npm login
npm publish .build-storage/flkr-release/flickfyi-flkr-0.0.0.tgz --access public

Version 0.0.0 leaves the workflow's 0.0.<run number> versions available. Complete the trusted publisher setup below before merging; no npm publishing secret is needed in GitHub.

Trusted publishing

Once the package exists, configure its npm trusted publisher for GitHub Actions:

| Setting | Value | | --- | --- | | Organization or user | zshannon | | Repository | crayon | | Workflow filename | flkr-release.yml | | Environment | Leave empty | | Allowed actions | Allow direct npm publish |

Only the release job on main receives id-token: write. PRs build and test the same tarball with read-only permissions. npm exchanges the GitHub identity for a short-lived publishing credential.

After the first workflow publication succeeds, select Require two-factor authentication and disallow tokens under the package's Settings → Publishing access. Revoke any old publishing tokens for this package and remove any corresponding NPM_TOKEN GitHub secret.

Private repository publishing

npm trusted publishing supports private source repositories. This workflow publishes the public @flickfyi/flkr npm package directly from private zshannon/crayon. npm omits provenance for private repositories; publication still works. The workflow does not request provenance or change repository visibility.

Consumers can check npm registry signatures in a project where the package is installed:

npm audit signatures

Registry signatures verify package integrity at the registry; they do not establish which source commit produced the package.

Staged publishing can require a maintainer's 2FA approval for every release. This workflow uses direct publishing to keep releases automatic after merges to main.