Setting Up a Dev Environment

Set up a checkout to work on ipa-hub's CLI, library, App Manager, or website. Follow the steps below, then read the pull request guidelines before submitting your changes.

Prerequisites

  • Git and a GitHub account to create a fork.
  • Node.js 24 or later, with npm.
  • macOS and Xcode for device discovery, signing, and installation. Follow Prepare your Mac to configure your Apple account and pair a test device.

You can work on the website and run the portable tests on other operating systems, but real device workflows require a Mac. The repository installs Bun as a development dependency for the WebRTC build; you do not need a separate global Bun installation for setup.

Set up the repository

Fork ipa-hub on GitHub, then clone your fork. Replace YOUR_USERNAME with your GitHub username:

git clone https://github.com/YOUR_USERNAME/ipa-hub.git
cd ipa-hub
npm install
npm run dev:setup

npm run dev:setup currently runs npm run setup:vendor. It bundles the installed WebRTC dependency and its types into src/vendor/webrtc/webrtc.ts. This directory is generated and Git-ignored. Run setup again after updating dependencies; change the build script or dependency version rather than editing its output.

The setup script uses the repository's pinned Bun build tool, including its declaration-generation API. If setup reports missing output or an unsupported build API, reinstall the dependencies and rerun npm run dev:setup.

Build and run the CLI

Build the library, CLI, and packaged App Manager assets:

npm run build
node ./dist/cli/cli.js --help

The build writes the library and CLI to dist/ and the webapp to dist-webapp/. On your Mac, check device discovery using the CLI from your checkout:

node ./dist/cli/cli.js --data-dir ~/.ipa-hub-dev device ls

For portable CLI work on Linux or Windows, explicitly enable the development platform override. For example, in a POSIX shell:

IPA_HUB_DEV_ALLOW_NON_MACOS=1 node ./dist/cli/cli.js --help

Set the variable to exactly 1 before running the CLI or calling getIpaHub(). It bypasses the platform restriction without emulating Apple’s tools; signing and device access still require a Mac or test mocks. Without it, the CLI exits with code 1, while the library warns and returns an inactive instance with empty lists. Website development and builds do not require this override.

Use a separate data directory for development so your test installations and saved settings stay separate from your usual ipa-hub setup. To test the local installer with an IPA you have built, bypass delegation to an existing server:

node ./dist/cli/cli.js --data-dir ~/.ipa-hub-dev install ./App.ipa --bypass-server

For repeated TypeScript changes, keep the compiler running in another terminal:

npm run watch

Run the compiled CLI again after a change has compiled. Restart a development server to load its rebuilt code. watch prepares the WebRTC bundle and webapp before watching the library; it does not watch the webapp's source files.

Work on the website and docs

npm run dev:website

Open http://127.0.0.1:5174. The website uses React, TypeScript, and Vite, with its components and CSS in website/src/.

Write guides in docs/. Add new guide pages to scripts/docs/buildDocumentation.ts, which defines their titles and sidebar groups. The CLI reference comes from command definitions in src/cli/; the API reference comes from the public library exports through TypeDoc. Edit those sources rather than generated reference pages.

Website startup generates documentation once. After changing Markdown, command definitions, or public API documentation while the dev server is running, regenerate it and reload the page:

npm run docs:generate

Validate the production website with:

npm run build:website

This generates the HTML pages, search index, Markdown exports, llms.txt files, sitemap, and social images in dist-website/. Generated documentation lives in website/generated/; neither directory is committed. For an Awesome List contribution, follow Contribute an app.

Work on App Manager

npm run dev:webapp

The webapp runs at http://localhost:5173/app/. To connect it to your local server, switch webappURL in src/config.ts to the commented development URL, then rebuild and start the server on your Mac:

npm run build:library
node ./dist/cli/cli.js --data-dir ~/.ipa-hub-dev serve --port 19465

Open the server address it prints to get the manager URL with the connection information. Keep Vite running in a separate terminal. Restore the hosted webapp URL before submitting your change.

When testing App Manager on an iPhone, iPad, or Vision Pro, serve the development webapp over HTTPS with a certificate trusted by that device, and set webappURL to that HTTPS address. Plain HTTP on a .local hostname or LAN IP cannot use Web Crypto or service workers; adding the page to the Home Screen does not change that. The http://localhost exception only works on the machine running the browser. The ipa-hub server on port 19465 can still use HTTP: the HTTPS webapp connects to it through authenticated WebRTC.

For testing on a physical device, configure an HTTPS development webapp address that the device can reach. localhost on the device refers to the device itself. Keep the webapp under /app/, which also limits its service worker's scope.

Run checks

npm test
npm run build
npm pack --dry-run

npm test runs the TypeScript checks, ESLint, and Vitest. Most tests use fixtures or mocked Apple tools; changes to signing or device operations also need a real-device check on macOS. Describe which devices and OS versions you tested in your pull request.

Use the configured ESLint rules to format code:

npm run format

For a focused test run:

npm run test:vitest -- test/website.test.ts

The runtime also supports Bun 1.4.2 or later. If you have Bun installed, check changes that affect runtime behavior with bun run --bun test:vitest as well.

Browser checks

Browser checks use Chromium. Set the IPA_HUB_TEST_CHROMIUM environment variable to its executable when it is not at /usr/bin/chromium. For example, with Chromium installed on macOS:

npm run build:webapp
IPA_HUB_TEST_CHROMIUM='/Applications/Chromium.app/Contents/MacOS/Chromium' npm run test:website

The website checks cover navigation, command selection, clipboard behavior, responsive layouts, and generated pages. App Manager changes can also be checked with npm run test:webapp:offline and npm run test:webapp:installation, using the same Chromium environment variable.

See environment variables for build and test configuration, and the pull request guidelines for preparing your contribution.

Edit this page