---
product: Chilkat
product_version: 11.7.0
language: nodejs
language_label: Node.js
document: language guide
---
> Chilkat 11.7.0 · language=nodejs · this file: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/nodejs/guide.md`
> Class pages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/nodejs/classes/<Class>.md`

# Chilkat for Node.js — language guide — v11.7.0

## 1. Which Chilkat binding this is

This is the **Chilkat Node.js module**: a native addon, one npm package per Node.js major version and platform under `@chilkat/`, for example `@chilkat/ck-node24-win64`, `@chilkat/ck-node24-mac-universal`, `@chilkat/ck-node24-linux-x64`, `@chilkat/ck-node24-linux-arm64` (also `ck-node25-*`, `ck-node26-*`). Chilkat supports the three most recent Node.js major versions. Electron uses separate `@chilkat/ck-electron…` packages. Classes are `chilkat.Http`, `chilkat.Zip`, `chilkat.BinData`, … (no `Ck` prefix); properties are JavaScript properties. This is not the browser JavaScript/ActiveX binding and not React Native (`@chilkat/react-native`).

## 2. Install and requirements

```
npm install @chilkat/ck-node24-win64      # pick the package for your Node major version and OS/CPU
```

The full package list by Node version and platform: [https://www.chilkatsoft.com/nodejs.asp](https://www.chilkatsoft.com/nodejs.asp). Load it with `require` (the package name is the one installed):

```javascript
const chilkat = require('@chilkat/ck-node24-win64');
```

## 3. Unlocking and object creation

```javascript
const chilkat = require('@chilkat/ck-node24-win64');

// Required once per process, before any other Chilkat object. Any string unlocks a 30-day trial.
var glob = new chilkat.Global();
var success = glob.UnlockBundle("Anything for 30-day trial");
if (success !== true) {
    console.log(glob.LastErrorText);
    return;
}

var http = new chilkat.Http();
```

- Unlocking only sets a flag in memory: no license files, no network call, so the call is repeated each time the program runs. Extra calls are harmless no-ops; the `Global` object can be discarded afterwards.
- If a program forgets to unlock, Chilkat runs in trial mode and stops working when the trial expires — always include the call, and use the purchased unlock code in production.
- `UnlockBundle` unlocks every class; per-class `UnlockComponent` methods exist only in old code.

## 4. Error model

Chilkat methods **do not throw** for Chilkat-level failures (they are synchronous calls into the native library). The note under each method on the class page says how it reports failure: a boolean status method returns `false`; a string-returning method returns `null`; an object-returning method returns `null`; for a number result check `LastMethodSuccess`. `LastErrorText` holds the diagnostic in every case. Properties are plain properties (`http.Port = 443`).

Literals in Node.js: true is `true`, false is `false`, null/none is `null`.

## 5. Strings, bytes and encodings

- Strings are JavaScript strings; a `charset` argument names the encoding of the *bytes* being produced or read.
- Binary data is a Node `Buffer` in and out. Larger or reusable binary data goes through `chilkat.BinData` (`Bd` methods); text through `chilkat.StringBuilder` (`Sb` methods).
- Methods with `2`/`3` suffixes or `Quick*` prefixes are distinct members, not overloads.

## 6. Object lifetime and threading

Objects are released by the JavaScript garbage collector. Synchronous Chilkat calls block the event loop for their duration; use the `*Async` variants (below) for long network or file operations so the loop stays responsive.

A Chilkat object may be used from any thread, but **one object must not be used by two threads at the same time**: create one object per thread or protect it with a lock. Objects are independent — there is no shared global state other than the unlock flag and the few `Global` settings.

## 7. Progress callbacks and async

This binding has **no progress callbacks**. For progress, percent-done or cancellation, use the `*Async` variant of a method (every method with an "Async variant" line on its class page has one). `XAsync` takes the same arguments, returns a `Task` immediately, and the result is read from the task after it finishes: run it, poll `Finished` (or wait), then `GetResultBool` / `GetResultString` / `GetResultBytes` etc.; `PercentDone` and `Cancel` are on the task. No new Async methods are added from 11.7.0 on. In Node.js the idiomatic pattern is `task.Run()` then a `TaskCompleted` wait via polling `task.Finished` on a timer, or `task.Wait(ms)`; see [https://www.chilkatsoft.com/nodejs.asp](https://www.chilkatsoft.com/nodejs.asp) ("Async Chilkat Methods in Node.js"). Chilkat `*Async` methods return a Chilkat `Task`, not a JavaScript Promise — they are not `await`-able.

## 8. Common mistakes an AI makes with this binding

1. `await`-ing a Chilkat `*Async` method or treating its return value as a Promise.
2. Writing `new CkHttp()` (C++/Python spelling) or `chilkat.CkHttp` — in Node.js it is `new chilkat.Http()`.
3. Expecting callbacks-style APIs (`http.get(url, cb)`) — Chilkat calls are synchronous or Task-based.
4. Omitting `Global.UnlockBundle` (the program runs in trial mode and stops working after 30 days).
5. Inventing members by analogy with other libraries. If a member is not on the class page, it does not exist — look it up rather than guessing.
6. Using deprecated members that older examples still show. The class page lists each one with its replacement; `deprecated.md` lists them all.
7. Ignoring the failure path. Every Chilkat method reports failure (see each method's note); `LastErrorText` says why, and printing it is the first debugging step.
8. Using one Chilkat object from two threads at the same time. Create one object per thread, or protect it with a lock.

## 9. Instructions block for coding agents

Paste into `CLAUDE.md`, `.cursor/rules`, or Copilot instructions:

```
This project uses Chilkat 11.7.0 from Node.js (npm @chilkat/ck-node<major>-<platform>, loaded with require).
- Reference: https://www.chilkatsoft.com/ai-docs/v/11.7.0/nodejs/ — read guide.md once, then classes/<Class>.md for each class used.
- Call new chilkat.Global().UnlockBundle(...) once at startup.
- Chilkat methods never throw on failure: check the false/null result and print obj.LastErrorText. *Async methods return a Chilkat Task, not a Promise.
- Never use a member that is not on the class page; never use members listed as deprecated.
```

## 10. Classes

[Class index for Node.js](https://www.chilkatsoft.com/ai-docs/v/11.7.0/nodejs/index.md)