objc-js

objc-js is an Objective-C bridge for Node.js. This is a fork of nobjc by Noah Gregory.

Installation

Prerequisites

• Node.js / Bun
• Xcode Command Line Tools (Run xcode-select --install to install)
• pkg-config from Homebrew (Run brew install pkgconf to install)

Note

Why are these prerequisites required?

These are required to rebuild the native code for your system.

Install using npm

npm install objc-js

Install using bun

bun add objc-js
# and `bun pm trust -a` to run the rebuild if needed

Documentation

The documentation is organized into several guides:

• Basic Usage - Getting started with loading frameworks and calling methods
• C Functions - Calling C functions like NSLog, NSHomeDirectory, NSStringFromClass
• Structs - Passing and receiving C structs (CGRect, NSRange, etc.)
• Subclassing Objective-C Classes - Creating and subclassing Objective-C classes from JavaScript
• Blocks - Passing JavaScript functions as Objective-C blocks (closures)
• Run Loop - Pumping the CFRunLoop for async callback delivery (completion handlers, etc.)
• Protocol Implementation - Creating delegate objects that implement protocols
• API Reference - Complete API documentation for all classes and functions

Quick Start

import { NobjcLibrary } from "objc-js";

// Load a framework
const foundation = new NobjcLibrary("/System/Library/Frameworks/Foundation.framework/Foundation");

// Get a class and call methods
const NSString = foundation["NSString"];
const str = NSString.stringWithUTF8String$("Hello, World!");
console.log(str.toString());

For more examples and detailed guides, see the documentation.

Companion Packages

objc-js has two companion packages for TypeScript types and pure-C framework bindings:

objcjs-types

Auto-generated TypeScript type definitions for macOS Objective-C frameworks. Provides IntelliSense and type checking for classes, protocols, enums, and methods across all major Apple frameworks.

npm install objcjs-types

import type { NSWindow, NSApplicationDelegate } from "objcjs-types/AppKit";
import type { CGPoint, CGSize, CGRect } from "objcjs-types/structs";

objcjs-extra

Hand-written FFI bindings for macOS pure-C frameworks that have no Objective-C metadata (so they can't be auto-generated by objcjs-types). Works with both Bun (bun:ffi) and Node.js (koffi).

npm install objcjs-extra koffi    # Node.js
bun add objcjs-extra              # Bun

Provides bindings for CoreFoundation, CoreGraphics, ApplicationServices (Accessibility), Security, CoreServices (FSEvents, Launch Services), IOKit, CoreText, ImageIO, CoreAudio, Network, CoreMedia, and Accelerate.

import { AXUIElementCreateApplication, AXIsProcessTrusted } from "objcjs-extra/ApplicationServices";
import { CGEventCreateKeyboardEvent, CGEventPost } from "objcjs-extra/CoreGraphics";
import { getDefaultOutputDevice, setDeviceVolume } from "objcjs-extra/CoreAudio";
import { preventSleep } from "objcjs-extra/IOKit";

When to use which package

Need	Package
Call Objective-C methods (NSWindow, NSString, etc.)	objc-js
TypeScript types for Objective-C APIs	objcjs-types
Pure-C frameworks (CoreFoundation, CoreGraphics, Accessibility, etc.)	objcjs-extra