iOS WebKit Debug Kit

A streamlined and unified toolkit for running the WebKit Inspector UI side-by-side with ios_webkit_debug_proxy for debugging Safari WebKit pages running on iOS devices. Technically, most browsers in iOS including Safari are based on WebKit engine.

2025-07-21.02-30-00.mp4

---

Background

egrep 'src=|href=' WebKit/Source/WebInspectorUI/UserInterface/Main.html | wc -l
928

The copy of WebInspectorUI provided by WebKit's official repository references around 928 JS/CSS resources from the Main.html page alone — all of which must be served locally for the interface to load properly. This process is slow and error-prone.

To address this, the source code is patched on the fly to maintain the dependency chain and is then bundled into a minimal set of optimized, minified files using esbuild.

Additionally, fixes and optimizations from past projects — such as ios-safari-remote-debug and ios-safari-remote-debug-kit which may have worked in the past but no longer function flawlessly today — have been adopted for a smoother, snappier debugging experience.

---

Features

• Build and bundle the WebKit Inspector UI from the latest stable release or a specific tag (one-time task).
• Serve the UI using a multi-threaded Node.js web server for to your iOS version.
• Run ios_webkit_debug_proxy within the same server CLI, with multiplexed IO.
• Optionally launch a browser pointing to the device index listing your devices and inspectable pages.
• And yes — it actually works, no excuses. 😉

---

Prerequisites

1. Git for Windows
2. Node.js
3. An iPhone paired with iTunes or Apple Devices (Windows App). WiFi pairing optional.
4. ios_webkit_debug_proxy installed and available in your system PATH or under ./node_modules/.bin/ for convenience.

---

Usage Guide

1. Ensure git, npm, and node are installed and working correctly in your shell.

2. Clone this repository and open a terminal (e.g. PowerShell) inside the cloned folder.

3. Install dependencies:

   npm install

4. Run the bootstrap script:

   .\bootstrap.ps1 -Tag wpewebkit-2.49.3

   (Performs a sparse checkout of the WebKit repository and initializes submodules)

5. Build the optimized Inspector UI from WebKit sources:

   node build.js

   Example output:

   ✓ In-memory JS entry with 661 imports
   ✓ In-memory CSS entry with 246 imports
   ✓ Final JS written to Main.min.js
   ✓ Injected 103 image variable(s) into in-memory CSS
   ✓ Final CSS written to Main.min.css
   ✓ Rewrote HTML: Main.min.html
   ✓ All builds complete
   

6. Start the web server and launch ios_webkit_debug_proxy:

   node serve.js -v 18.4 -b cromite

   Example output:

   Primary 21184 is running
   Listing devices on :9221
   Worker (http) 17812 started on port 9920
   ...
   Worker (http) 8844 started on port 9920
   ▷ WebKit Frontend: http://localhost:9920/Main.html
   ▷ iOS Debug Proxy: http://localhost:9221 ◁ Start Here
   Launching browser: C:\Users\ItsYou!\AppData\Local\Scoop\shims\cromite.EXE
   Connected :9222 to Your iPhone (xxxxx-yyyyyyyy)
   

7. For all available options, see the help command:

   node serve.js --help

   Usage: serve.js [-v 18.4] [-p 9220] [-t 4]
   
   Options:
       --version   Show version number                          [boolean]
   -v, --proto     iOS protocol version
         [choices: "18.4", "18.2", ..., "13.0"]                 [default: "18.4"]
   -p, --port      Port number to serve frontend on             [default: 9920]
   -t, --threads   Number of worker threads                     [default: 4]
   -x, --proxy     Full path to ios_webkit_debug_proxy
   -b, --browser   Browser executable to launch automatically
       --help      Show help                                    [boolean]
   

8. Connect your iOS device via USB or WiFi and visit http://localhost:9221/ where each of your connected devices shall be listed. If you cannot find your device here, then fix your connectivity (USB or WiFi) first and verify with running ios_webkit_debug_proxy alone.

   

   Debug UI should be up and running if all steps were followed right.

9. Don’t forget to ⭐ Star the repository, share it with your peers, and leave feedback or improvement suggestions in the Issues section.

---

License

This project makes use of source code from WebKit, ios_webkit_debug_proxy, and ios-safari-remote-debug, each under their respective licenses.