@north-light/applet-sdk
v1.7.0
Published
The ESM-only Core and Cloudflare contract for Northlight applets. It is intentionally split into four environment-specific subpaths and has no root export:
Downloads
1,117
Keywords
Readme
@north-light/applet-sdk
The ESM-only Core and Cloudflare contract for Northlight applets. It is intentionally split into four environment-specific subpaths and has no root export:
@north-light/applet-sdk/server— Worker bindings, platform operations, jobs, device events, visitor reads, the legacy runtime schema helper, Core proxy, and platform routes.@north-light/applet-sdk/client— dependency-free browser conversation, artifact, activity, revision, repair, and host-message protocol.@north-light/applet-sdk/theme— the dependency-free pre-paint theme contract.@north-light/applet-sdk/build— the Workers Vite SSR block and manifest reader.
Ambient modules
Importing @north-light/applet-sdk/server brings the declarations for cloudflare:workers and node:async_hooks into your TypeScript program, so import { env } from 'cloudflare:workers' resolves with no @cloudflare/workers-types or @types/node installed — both of those packages' global libs clash with the DOM lib React needs. An applet must therefore not declare either module itself: two ambient declarations of the same module are a duplicate-identifier error. The binding shapes (AppletEnv, D1Database, R2Bucket, and friends) are ordinary exported types on /server, not globals.
nl-applet snapshot and nl-applet upload run from an applet repository's current working directory. snapshot produces snapshot.json and publish-meta.json, retaining src/server/schema.sql at database/schema.sql so deployment can apply it before activation; upload sends an existing verified snapshot to the applet source bucket.
The package uses tsc per-module ESM output instead of this monorepo's sibling-package tsup dual-format convention. Applet Vite builds inline this package under workerd conditions; a CJS entry can select Node interop and break the one-file Worker upload.
Core compatibility — major 1
Deployments bundle this SDK permanently. Core must preserve the meaning of every wire surface emitted by every published 1.x release:
POST /v1/cli/invokePOST /v1/artifactsGET /v1/artifacts/:id/content- the allow-listed five
/v1/crouter/conversations*calls: create, deliver, stop, follow, and result - the
x-nl-credentialheader in both directions - the
/__nl/ready,/__nl/jobs, and/__nl/eventsroutes and response shapes Core calls into an applet - the
applet-v1snapshot envelope and its digest arithmetic
There is no runtime version negotiation. A breaking Core change requires redeploying every live applet and is a product decision, not an SDK fallback.
