Guide · Open source

How to use JSPatch: install, run JavaScript and patch iOS methods

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

JSPatch is an open-source engine for iOS apps that connects Objective-C and JavaScript through the Objective-C runtime. This guide shows how to add it to an Xcode project, run JavaScript from Objective-C, and replace existing methods from a script. It is aimed at iOS developers who maintain older apps and want to understand what the engine does before using it.

JSPatchbang590/JSPatch · ★ 11.3k · MIT Install options & downloads

Quick start

1Check your target. Confirm you have Xcode and an iOS 7+ target, since the README lists that as the environment.
2Add the pod. Add pod 'JSPatch' to your Podfile, or copy JSEngine.m, JSEngine.h and JSPatch.js into the project if you do not use CocoaPods.
3Run pod install. Run pod install in the project folder to fetch the library.
4Start the engine. Import JPEngine.h and call [JPEngine startEngine] early in application:didFinishLaunchingWithOptions:.
5Evaluate a script. Load a local .js file from the bundle and pass its contents to [JPEngine evaluateScript:].
6Override a method. Use defineClass in your script and call self.ORIG plus the method name when you want the original behaviour.

What JSPatch does and what it is for

JSPatch lets JavaScript call any Objective-C class and method once a small engine is included. The README says it is mainly used to fix bugs in a shipped iOS app by adding modules or replacing Objective-C code dynamically, without a full App Store update.

The project is still in development according to its README. Its own notice also asks developers not to integrate it directly and instead to use the JSPatch platform, which links an FAQ about Apple policy.

Language: Objective-C, targeting iOS
Licence: MIT
Mechanism: the Objective-C runtime bridges calls to JavaScript
Environment: iOS 7+ with forward compatibility with iOS 6, uses JavaScriptCore.framework, supports armv7, armv7s and arm64

Install JSPatch with CocoaPods or by copying files

The README's recommended route is CocoaPods. Add the pod to your Podfile, then run pod install. The example Podfile in the README sets the platform to iOS 6.0.

If you do not use CocoaPods, the README says to copy the files JSEngine.m, JSEngine.h and JSPatch.js from the JSPatch/ folder into your project.

Prerequisites: Xcode, CocoaPods (or manual file copy), and an iOS 7+ target

platform :ios, '6.0'
pod 'JSPatch'

Start the engine and run JavaScript from Objective-C

Import JPEngine.h, call [JPEngine startEngine], then run JavaScript with [JPEngine evaluateScript:]. The README example does this in application:didFinishLaunchingWithOptions: and loads a demo.js file from the app bundle.

The README also shows running a script inline, loading a file from the network and loading a local file. Loading code from the network is a choice you make in your own app and carries the policy concerns noted above.

Import JPEngine.h
Call [JPEngine startEngine]
Run code with [JPEngine evaluateScript:@""]

[JPEngine startEngine];
NSString *sourcePath = [[NSBundle mainBundle] pathForResource:@"demo" ofType:@"js"];
NSString *script = [NSString stringWithContentsOfFile:sourcePath encoding:NSUTF8StringEncoding error:nil];
[JPEngine evaluateScript:script];

Call Objective-C classes and methods from JavaScript

Use require() to load class names, then call class methods and instance methods with dot syntax. Multi-parameter methods replace colons with underscores, so the README's example uses indexPathForRow_inSection. Use .toJS() to convert NSArray, NSString or NSDictionary to JavaScript types.

Struct values such as CGRect are represented as hashes, for example {x:20, y:20, width:100, height:100}.

Method names containing an underscore use double underscores in JavaScript
Wrap blocks passed from JavaScript to Objective-C with block("NSString *, BOOL", function(ctn, succ) { ... })
GCD helpers shown in the README include dispatch_after and dispatch_async_main

require('UIView, UIColor, UISlider, NSIndexPath')
var redColor = UIColor.redColor();
var view = UIView.alloc().init();
view.setBackgroundColor(redColor);
var indexPath = NSIndexPath.indexPathForRow_inSection(0, 1);

Replace an existing method with defineClass

defineClass lets you redefine an existing class and override its methods. Inside the override, self.ORIG plus the method name calls the original implementation, which the README uses to keep existing behaviour and add a change.

The README's table view example shows a bounds check added to a method that could crash on an out-of-range index.

Prefix the original method name with ORIG to call it, for example self.ORIGgenView()
Instance method names use underscores for their colons

defineClass('AppDelegate', {
  genView: function() {
    var view = self.ORIGgenView();
    view.setBackgroundColor(UIColor.greenColor());
    return view;
  }
});

Add extensions for custom structs and C functions

Extensions add support for custom struct types, C methods and other features. The README says to call +addExtensions: after starting the engine, or to add them from JavaScript with require('JPEngine').addExtensions(). It names JPInclude and JPCGTransform as examples, giving include() and CGAffineTransform support.

The README points to the wiki for writing your own extension.

Native call: [JPEngine addExtensions:@[@"JPInclude", @"JPCGTransform"]]
The README says adding extensions from JavaScript is recommended

require('JPEngine').addExtensions(['JPInclude', 'JPCGTransform'])

What people use it for

Adding a bounds check to a table view method in a shipped iOS app
Changing a view's appearance by replacing one Objective-C method
Studying how Objective-C runtime bridging to JavaScript works
Maintaining an older iOS codebase that already uses CocoaPods or manual integration

Frequently asked questions

Is JSPatch free to use?

JSPatch is released under the MIT licence, according to the repository. Check the LICENSE file in the repository before using it in a commercial product.

What are the requirements for JSPatch?

The README lists Xcode, CocoaPods or a manual file copy, and an iOS 7+ target. It also says the engine uses JavaScriptCore.framework and supports armv7, armv7s and arm64.

How do I install JSPatch?

Add pod 'JSPatch' to your Podfile and run pod install. If you do not use CocoaPods, copy JSEngine.m, JSEngine.h and JSPatch.js from the JSPatch/ folder into your project.

Can I use JSPatch on the latest iOS versions?

The README lists support only up to iOS 7+ and does not confirm support for newer platform releases. Test thoroughly on your target iOS version before relying on it.

Is JSPatch allowed by Apple for hotfixes?

The README asks developers not to integrate JSPatch directly and to use the JSPatch platform instead, and links an FAQ about Apple policy. Read that FAQ and Apple's current guidelines before shipping a hotfix this way.

What are alternatives to JSPatch?

Comparable projects named in the source include Apple's JavaScriptCore used directly, React Native and Expo Updates. JSPatch is specifically an Objective-C runtime bridge for iOS, while the others are different approaches to updating app code.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

JSPatch suits iOS developers who maintain older Objective-C apps and want to patch live code without resubmitting, or who want to study runtime bridging. Teams targeting current iOS releases, needing App Store-compliant hotfixes, or working outside iOS should choose another approach such as JavaScriptCore directly, React Native or Expo Updates.

Install options & downloads