imessage with the "imessage" platform ID. The local package exports
localIMessage with the "local_imessage" platform ID.
Because their platform IDs are different, a macOS application can register
both providers in one
Spectrum() instance. Use message.platform to
distinguish "imessage" cloud messages from "local_imessage" messages.Cloud quick start
Use the cloud provider for deployed applications and managed phone lines. It is already installed by the batteries-includedspectrum-ts package.
imessage.config() call.
Explicit cloud clients
Pass clients only when you need to restrict the SDK to a known subset of cloud lines or supply independently managed credentials:Local macOS quick start
Use the local provider only when the application runs on the Mac whose Messages database it should access.~/Library/Messages/chat.db.
Node.js uses better-sqlite3 through imessage-kit; Bun uses its built-in
SQLite implementation. If a Node package manager was configured to omit
optional dependencies, install better-sqlite3 explicitly.
Do not install
@spectrum-ts/imessage-local in a cloud deployment. Keeping it
out of spectrum-ts is what prevents the native SQLite dependency from
entering cloud dependency graphs.Feature comparison
Local inbound attachments remain readable from incoming message content. The
cloud-only
imessage(app).getAttachment(guid) lookup is not available locally.
Keep deployment entrypoints separate
If one repository has both a deployed cloud worker and a Mac development tool, give them separate composition modules so bundlers see only the correct import:Migrating from local: true
The combined-package API has been removed. Replace the old import and flag:
@spectrum-ts/imessage or
spectrum-ts/providers/imessage.
Runtime compatibility
Separating the packages removesimessage-kit and better-sqlite3 from cloud
installs. The current cloud transport still uses Node-compatible gRPC, so use a
Node.js or Bun deployment runtime. Strict browser and worker isolates without
Node APIs are not supported yet.
Explore iMessage
Connection and routing
Compare the two packages and learn line allocation, quotas, spaces, and per-phone cloud routing.
Messaging features
See which effects, group operations, cards, attachments, and tapbacks each package supports.