Skip to content

Node.js SDK Deployment Cookbook

Reference recipes for packaging, deploying, and operating TypeScript/Node.js extensions.

1. Project scaffold

kiket extensions scaffold my-extension --sdk node
cd my-extension
npm install

The scaffold includes:

  • .kiket/manifest.yaml and .kiket/modules/** (if you choose custom data)
  • src/main.ts with sample handlers
  • Replay payloads (replay/) for kiket extensions replay
  • GitHub Actions workflow for lint/test/package

2. Environment management

  • Commit .env.example listing all required KIKET_* variables.
  • Use kiket extensions secrets:pull / :push to sync per-installation secrets.
  • When deploying to Cloud Run / Fly.io / Heroku, map secret manager entries to KIKET_SECRET_* env vars so the SDK hydrates them automatically.

3. Packaging & deployment

Cloud Run

  1. Build a container that runs node dist/main.js.
  2. Expose port 8080 and set KIKET_WEBHOOK_SECRET, KIKET_WORKSPACE_TOKEN.
  3. Enable minimum instances (≥1) if you need near real-time guards (workflow.before_transition).

Serverless / Functions

Wrap the Express app exported by sdk.app:

import * as functions from 'firebase-functions';
import { KiketSDK } from '@kiket/sdk';

const sdk = new KiketSDK();

export const kiketWebhook = functions.https.onRequest(sdk.app);

CI/CD via CLI

kiket extensions lint
kiket extensions test
kiket extensions package . --output dist
kiket extensions publish dist --registry marketplace

4. Observability

  • Leave telemetry enabled so /api/v1/ext/telemetry captures latency/error metrics across installations.
  • Use feedbackHook to stream structured logs to Datadog, Honeycomb, or your logging pipeline.
  • Add a /health check in your load balancer to restart misbehaving instances automatically.

5. Performance and resiliency

  • Keep handlers idempotent; the platform retries failed deliveries.
  • For workflow.before_transition guards, respond within 10 seconds; otherwise the transition is denied.
  • Use context.endpoints.notify for actionable errors instead of throwing generic exceptions—notifications become part of the alert stream.

6. Custom data & SLA helpers

  • Declare custom_data.permissions in the manifest to access shared modules. The scaffold creates .kiket/modules/<module>/schema.yml for you.
  • context.endpoints.customData(projectId) exposes typed CRUD methods. Wrap them with your own repository classes to centralise validation.
  • SLA helpers (context.endpoints.slaEvents) allow you to suppress duplicate alerts or enrich notifications with historical data.

7. Local replay workflow

kiket extensions replay --template before_transition --url http://localhost:8080/webhooks/workflow.before_transition

Replays sign payloads with your local secret and highlight signature mismatches, missing event versions, or handler exceptions. Combine with GitHub Actions to run replays in CI for every change.

8. Upgrade strategy

  • Register new handler versions (sdk.webhook('issue.created', 'v2')) instead of breaking v1.
  • Use context.eventVersion to branch behaviour until all projects adopt the new version.
  • Update manifest version and publish via kiket extensions publish so installations can opt in using the upgrade assistant.

9. Access controls

  • Rely on extension API scopes: issues.read, issues.write, workflows.execute, custom_data.read, etc.
  • When you request additional scopes, document them in the README and manifest permissions block so admins understand why they’re required.

10. Useful references