Development

Prerequisites

• macOS 14 or later. The app is AppKit and runs nowhere else.
• Xcode, or just the Command Line Tools, with Swift 6 or later. The app is a Swift package built by scripts; there is no Xcode project.
• Node.js 24 or later, for the server and this website.
• nginx and mkcert from Homebrew, to run the real server.

Setup

git clone https://github.com/iambriansreed/dev.local.git && cd dev.local && npm install

The repository holds three subprojects: the Swift app in app/, the server behind it in server/, and this website in web/. One package.json at the root holds the tools for all of them. Every command below runs from the repository root.

Running it

npm run dev

Starts the menu bar app, which runs the server as an installed one does, and this website. The menu and the Settings window show your real apps: the server manages nginx and your dev servers through ~/.dev.localhost, and its log is followed in the terminal. A change under app/ or to the server's code rebuilds and restarts the app (and the server with it), and this site reloads on save.

app/scripts/demo.sh

The app against a stand-in server (app/scripts/fake-server.mjs) with the sample apps in .scripts/dev.proxies.json, for screenshots. It never touches nginx, sudo or your own apps.

Testing

npm run test:server && npm run test:scripts && npm run typecheck && app/scripts/test.sh

The server's pure logic, the release tooling and its types, and the app's testable core (DevLocalCore: the menu, the form's rules, the parsers).

Building

app/scripts/bundle.sh release && app/scripts/make-dmg.sh

A universal, ad-hoc signed app/build/dev.localhost.app carrying the server, then app/build/dev.localhost-<version>.dmg. app/scripts/make-icons.sh regenerates the icons.

Commits and releasing

Commits follow Conventional Commits; enable the check once per clone with git config core.hooksPath .scripts/hooks. A push to main tests, lets the commits since the last tag pick the version, builds the .dmg, publishes the GitHub release, and deploys this site.

How it works

The menu bar app starts the Node server as a child process, or attaches to one a terminal already started, and talks to it over HTTP and a WebSocket on a Unix socket, ~/.dev.localhost/server.sock, which only you can open: no port, so no web page can reach the API. The server writes nginx's config, runs nginx as you, starts dev servers and keeps their output in ~/.dev.localhost/logs/apps/, which is what Log opens. Settings is a native window on the same API. Only writes to /etc/hosts need root. The server never runs sudo: it stages the new file, and the app opens a Terminal script that shows the change and asks for your Mac password.