# 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](https://ipa-hub.giladgd.com/docs/guide/contributing.md) before submitting your changes.

## Prerequisites

- [Git](https://git-scm.com/downloads) and a GitHub account to create a fork.
- [Node.js 24 or later](https://nodejs.org/en/download), with npm.
- macOS and [Xcode](https://apps.apple.com/app/xcode/id497799835) for device discovery, signing, and installation. Follow [Prepare your Mac](https://ipa-hub.giladgd.com/docs/guide/getting-started.md#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](https://github.com/giladgd/ipa-hub/fork), then clone your fork. Replace `YOUR_USERNAME` with your GitHub username:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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

```sh
npm run dev:website
```

Open [http://127.0.0.1:5174](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:

```sh
npm run docs:generate
```

Validate the production website with:

```sh
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](https://ipa-hub.giladgd.com/docs/guide/contributing-apps.md).

## Work on App Manager

```sh
npm run dev:webapp
```

The webapp runs at [http://localhost:5173/app/](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:

```sh
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

```sh
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:

```sh
npm run format
```

For a focused test run:

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

The runtime also supports [Bun 1.4.2 or later](https://bun.com/). 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:

```sh
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](https://ipa-hub.giladgd.com/docs/guide/environment-variables.md#building-and-testing-the-repository) for build and test configuration, and the [pull request guidelines](https://ipa-hub.giladgd.com/docs/guide/contributing.md) for preparing your contribution.