@buildkitgg/dev-domains 0.0.0-stage → 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/LICENSE +21 -0
- package/README.md +727 -2
- package/dist/cli/command.d.ts +3 -0
- package/dist/cli/command.js +17 -0
- package/dist/cli/commands.d.ts +125 -0
- package/dist/cli/commands.js +99 -0
- package/dist/cli/init.d.ts +6 -0
- package/dist/cli/init.js +148 -0
- package/dist/cli/main.d.ts +2 -0
- package/dist/cli/main.js +13 -0
- package/dist/cli/terminal.d.ts +11 -0
- package/dist/cli/terminal.js +43 -0
- package/dist/config/load.d.ts +36 -0
- package/dist/config/load.js +68 -0
- package/dist/config/read.d.ts +2 -0
- package/dist/config/read.js +19 -0
- package/dist/config/schema.d.ts +73 -0
- package/dist/config/schema.js +71 -0
- package/dist/domains/resolve.d.ts +37 -0
- package/dist/domains/resolve.js +54 -0
- package/dist/node.d.ts +10 -0
- package/dist/node.js +16 -0
- package/dist/playwright.d.ts +13 -0
- package/dist/playwright.js +20 -0
- package/dist/project/detect.d.ts +3 -0
- package/dist/project/detect.js +101 -0
- package/dist/project/discovery.d.ts +6 -0
- package/dist/project/discovery.js +70 -0
- package/dist/project/identity.d.ts +6 -0
- package/dist/project/identity.js +44 -0
- package/dist/project/manifest.d.ts +11 -0
- package/dist/project/manifest.js +22 -0
- package/dist/project/package-manager.d.ts +2 -0
- package/dist/project/package-manager.js +28 -0
- package/dist/runtime/command.d.ts +4 -0
- package/dist/runtime/command.js +77 -0
- package/dist/runtime/port.d.ts +5 -0
- package/dist/runtime/port.js +37 -0
- package/dist/runtime/portless.d.ts +2 -0
- package/dist/runtime/portless.js +65 -0
- package/dist/runtime/process.d.ts +13 -0
- package/dist/runtime/process.js +101 -0
- package/dist/runtime/proxy.d.ts +10 -0
- package/dist/runtime/proxy.js +102 -0
- package/dist/runtime/state.d.ts +3 -0
- package/dist/runtime/state.js +8 -0
- package/dist/webhooks/gateway.d.ts +10 -0
- package/dist/webhooks/gateway.js +99 -0
- package/dist/webhooks/tunnel.d.ts +2 -0
- package/dist/webhooks/tunnel.js +27 -0
- package/package.json +65 -3
package/README.md
CHANGED
|
@@ -1,3 +1,728 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @buildkitgg/dev-domains
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Stable local URLs for your app, Storybook, and end-to-end test servers, across repositories and Git worktrees.
|
|
4
|
+
|
|
5
|
+
`@buildkitgg/dev-domains` gives each server a predictable hostname and runs it through
|
|
6
|
+
[Portless](https://github.com/vercel-labs/portless). You can open `https://shop.localhost` in your primary checkout and
|
|
7
|
+
`https://shop-fix-login.localhost` in a worktree, while Portless assigns the underlying ports. A configuration file lets
|
|
8
|
+
you choose your own names, use a real domain, describe authentication callbacks, and expose selected webhook routes.
|
|
9
|
+
|
|
10
|
+
Requires Node.js 24 or later. Supports Windows, macOS, and Linux.
|
|
11
|
+
|
|
12
|
+
## Table of contents
|
|
13
|
+
|
|
14
|
+
- [Motivation and philosophy](#motivation-and-philosophy)
|
|
15
|
+
- [Installation](#installation)
|
|
16
|
+
- [Quick start](#quick-start)
|
|
17
|
+
- [Guided setup](#guided-setup)
|
|
18
|
+
- [Zero-configuration behavior](#zero-configuration-behavior)
|
|
19
|
+
- [Domain naming](#domain-naming)
|
|
20
|
+
- [Domain normalization and collisions](#domain-normalization-and-collisions)
|
|
21
|
+
- [Configuration files](#configuration-files)
|
|
22
|
+
- [Configuration schema](#configuration-schema)
|
|
23
|
+
- [Templates and environment variables](#templates-and-environment-variables)
|
|
24
|
+
- [Server commands and frameworks](#server-commands-and-frameworks)
|
|
25
|
+
- [Playwright](#playwright)
|
|
26
|
+
- [Node.js tooling](#nodejs-tooling)
|
|
27
|
+
- [Authentication callbacks](#authentication-callbacks)
|
|
28
|
+
- [Webhook tunnels](#webhook-tunnels)
|
|
29
|
+
- [Sharing a proxy across projects](#sharing-a-proxy-across-projects)
|
|
30
|
+
- [CI usage](#ci-usage)
|
|
31
|
+
- [Command reference](#command-reference)
|
|
32
|
+
- [Troubleshooting](#troubleshooting)
|
|
33
|
+
- [Contributing and license](#contributing-and-license)
|
|
34
|
+
|
|
35
|
+
## Motivation and philosophy
|
|
36
|
+
|
|
37
|
+
Running several apps or worktrees often means competing for ports, updating bookmarks, and keeping callback URLs in
|
|
38
|
+
sync. An app might start on port 3000 today and 3001 tomorrow. Storybook and test servers add more addresses to track,
|
|
39
|
+
and several developers or coding agents working on the same machine make those conflicts more frequent.
|
|
40
|
+
|
|
41
|
+
`@buildkitgg/dev-domains` keeps the browser-facing address separate from the server's port. An **endpoint** is one
|
|
42
|
+
server process, such as a web app, API, or Storybook, paired with a hostname and the command that starts it. Multiple
|
|
43
|
+
routes served by the same process share that endpoint.
|
|
44
|
+
|
|
45
|
+
The package follows a few principles:
|
|
46
|
+
|
|
47
|
+
- **Useful defaults, explicit overrides.** Discover conventional setups without a config file, then save a typed
|
|
48
|
+
configuration when your project needs different names or commands.
|
|
49
|
+
- **Readable checkout names.** Identify linked worktrees by their folder names. The primary checkout has no `main`
|
|
50
|
+
label, and hostnames do not acquire random hashes.
|
|
51
|
+
- **Reuse Portless.** Portless owns the proxy, certificates, and shared route registry. This package adds project
|
|
52
|
+
conventions and integrations around it.
|
|
53
|
+
- **Report conflicts.** A running endpoint keeps its hostname. Another process must choose a different name instead of
|
|
54
|
+
taking over the route.
|
|
55
|
+
- **Keep application choices with the application.** Authentication providers, cloud resources, DNS administration, and
|
|
56
|
+
deployment remain under your control. A Buildkit account or hosted service is not required.
|
|
57
|
+
|
|
58
|
+
Separate hostnames and ports do not isolate databases, storage, credentials, or framework build directories. This
|
|
59
|
+
package manages local server addresses and processes; resource isolation remains part of your application setup.
|
|
60
|
+
|
|
61
|
+
## Installation
|
|
62
|
+
|
|
63
|
+
Install the package from npm as a development dependency in your project:
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
npm install --save-dev @buildkitgg/dev-domains
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Install where the configuration and CLI are used. A root `dev-domains.config.ts` must be able to import the package from
|
|
70
|
+
the root; installing it only in `apps/web` may not satisfy that import. A workspace that imports the Playwright helper
|
|
71
|
+
or owns its own typed configuration must also be able to resolve the package. Declare a dependency in that workspace
|
|
72
|
+
when your package manager isolates workspace dependencies.
|
|
73
|
+
|
|
74
|
+
Consumer-facing commands use `npx @buildkitgg/dev-domains`, which runs the locally installed package's CLI. Installing
|
|
75
|
+
and locking the dependency keeps the CLI and configuration helpers on the same version. Portless is included; a separate
|
|
76
|
+
global installation is unnecessary. Your application frameworks and any tunnel executable must already be installed.
|
|
77
|
+
|
|
78
|
+
On Windows, Portless also requires OpenSSL on `PATH`. Initial HTTPS setup can require permission to trust a local
|
|
79
|
+
certificate authority, bind the proxy port, or update the hosts file. Run setup interactively on each development
|
|
80
|
+
machine.
|
|
81
|
+
|
|
82
|
+
## Quick start
|
|
83
|
+
|
|
84
|
+
Start in the project you want to run. These commands inspect the detected servers and URLs, prepare the proxy, and start
|
|
85
|
+
one server:
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
npx @buildkitgg/dev-domains detect
|
|
89
|
+
npx @buildkitgg/dev-domains urls
|
|
90
|
+
npx @buildkitgg/dev-domains setup
|
|
91
|
+
npx @buildkitgg/dev-domains run
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
For a root package named `shop` with a `"dev": "vite"` script, the detected endpoint is `app`, at
|
|
95
|
+
`https://shop.localhost`. Run it directly with:
|
|
96
|
+
|
|
97
|
+
```sh
|
|
98
|
+
npx @buildkitgg/dev-domains run app
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Open the URL printed by the CLI. A linked worktree folder named `fix-login` uses `https://shop-fix-login.localhost`. The
|
|
102
|
+
checked-out branch does not change either name.
|
|
103
|
+
|
|
104
|
+
`detect` and `urls` do not start servers or write configuration. With several endpoints, `run` displays a picker in an
|
|
105
|
+
interactive terminal. In automation, pass the endpoint name explicitly. Each invocation starts one endpoint; use
|
|
106
|
+
separate terminals or your existing task runner for additional servers.
|
|
107
|
+
|
|
108
|
+
Press Ctrl+C to stop the server and remove its owned routes. The shared proxy remains available for other servers.
|
|
109
|
+
|
|
110
|
+
## Guided setup
|
|
111
|
+
|
|
112
|
+
Run the wizard when you want to choose and save your endpoints:
|
|
113
|
+
|
|
114
|
+
```sh
|
|
115
|
+
npx @buildkitgg/dev-domains init
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The wizard detects servers, lets you select them and rename the primary-checkout and worktree templates, and offers
|
|
119
|
+
optional authentication callback paths, a dedicated Playwright server, and webhook tunneling. Detected E2E servers start
|
|
120
|
+
unchecked. Review the resulting domains before saving `dev-domains.json` at the checkout root.
|
|
121
|
+
|
|
122
|
+
Use arrow keys to move, Space to toggle a selection, and Enter to continue. Cancellation writes nothing. Existing
|
|
123
|
+
configuration files are never overwritten, and package scripts are not rewritten.
|
|
124
|
+
|
|
125
|
+
For noninteractive setup:
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
npx @buildkitgg/dev-domains init --yes --dry-run
|
|
129
|
+
npx @buildkitgg/dev-domains init --yes --project shop --domain localhost
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
`--yes` accepts detected ordinary servers and omits optional E2E servers. `--dry-run` prints the proposed configuration
|
|
133
|
+
without saving it. Without `--yes`, a dry run still uses the interactive wizard. `--domain` changes the suffix; custom
|
|
134
|
+
hostname layouts also require the name templates described under [Domain naming](#domain-naming).
|
|
135
|
+
|
|
136
|
+
## Zero-configuration behavior
|
|
137
|
+
|
|
138
|
+
When no configuration file is found, these conventions determine the candidates:
|
|
139
|
+
|
|
140
|
+
| Concern | Behavior |
|
|
141
|
+
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
142
|
+
| Project root | The current Git checkout root; outside Git, the current directory or `--cwd` |
|
|
143
|
+
| Project name | Root `package.json` name, otherwise the root folder name, normalized as described below |
|
|
144
|
+
| Package manager | Root `packageManager`, then `devEngines.packageManager`, then lockfiles, then installation metadata; npm if none is found |
|
|
145
|
+
| Workspace packages | Root plus declared `pnpm-workspace.yaml` packages or `package.json` workspaces; without declarations, packages found recursively below the root |
|
|
146
|
+
| App server | First eligible script in this order: `dev:app`, `dev:raw`, `dev` |
|
|
147
|
+
| Storybook server | A script containing `storybook dev`; otherwise a discovered `.storybook/main.*` config |
|
|
148
|
+
| Playwright candidate | A `playwright.config.*` file, an `@playwright/test` dependency, or a `playwright test` script, together with an app dev script in the same package |
|
|
149
|
+
| Framework | Recognized simple Next.js, Vite, and Storybook commands receive framework-specific flags; other commands are `custom` |
|
|
150
|
+
| Local proxy | HTTPS on port 443, suffix `localhost`, hosts synchronization enabled |
|
|
151
|
+
| Auth and public access | No callback paths or tunnels are inferred |
|
|
152
|
+
|
|
153
|
+
Package-manager detection uses
|
|
154
|
+
[`package-manager-detector`](https://github.com/antfu-collective/package-manager-detector). It stays at the selected
|
|
155
|
+
project root instead of inheriting a manager from an unrelated parent folder. A declaration takes precedence over stale
|
|
156
|
+
lockfiles. Conflicting lockfiles without a declaration require you to choose a manager in `package.json` or an explicit
|
|
157
|
+
dev-domains config.
|
|
158
|
+
|
|
159
|
+
Scripts that invoke `dev-domains`, `portless`, `turbo`, `run-p`, or `concurrently` are excluded from detection. Point
|
|
160
|
+
configuration at the underlying server script when an aggregate or wrapper command is involved. A `playwright test`
|
|
161
|
+
script is never used as the app server.
|
|
162
|
+
|
|
163
|
+
### Storybook and Playwright discovery
|
|
164
|
+
|
|
165
|
+
One read-only directory walk finds both `.storybook/main.*` and `playwright.config.*`. It recognizes `ts`, `mts`, `cts`,
|
|
166
|
+
`js`, `mjs`, `cjs`, `tsx`, and `jsx` filenames. Configs belong to their nearest package, including nested paths such as
|
|
167
|
+
`tests/playwright.config.ts`. Tool configuration files are located without being imported or executed.
|
|
168
|
+
|
|
169
|
+
The walk honors workspace exclusions and skips symlinks, hidden directories other than `.storybook`, `node_modules`,
|
|
170
|
+
`dist`, `build`, `out`, `coverage`, `storybook-static`, `playwright-report`, and `test-results`. It stops with an error
|
|
171
|
+
above 1,000 packages or 10,000 visited directories; use explicit configuration for larger or unusual layouts.
|
|
172
|
+
|
|
173
|
+
For Storybook, a dev script takes precedence over config-file discovery. With one config and no dev script, the
|
|
174
|
+
candidate runs the installed `storybook dev --config-dir <directory>` binary. Nothing is downloaded. Multiple dev
|
|
175
|
+
scripts, or multiple configs without a clear dev script, require explicit configuration. An empty `.storybook` folder or
|
|
176
|
+
a Storybook dependency alone does not establish a runnable server.
|
|
177
|
+
|
|
178
|
+
For Playwright, the candidate starts a separate copy of the app dev server. It is named `app-e2e`, or
|
|
179
|
+
`<package>-app-e2e` in a workspace. Select it explicitly in the wizard or run it by name when using zero configuration.
|
|
180
|
+
`init --yes` omits it. A dependency on the `playwright` browser library alone does not imply an E2E test setup. Separate
|
|
181
|
+
test-only packages and cross-package server relationships need explicit configuration. See [Playwright](#playwright)
|
|
182
|
+
before running an E2E server alongside your app.
|
|
183
|
+
|
|
184
|
+
## Domain naming
|
|
185
|
+
|
|
186
|
+
A hostname consists of the resolved endpoint name followed by `domain`:
|
|
187
|
+
|
|
188
|
+
```text
|
|
189
|
+
<resolved name>.<domain>
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
The origin adds the protocol and, when it is not the protocol's standard port, the proxy port. For example,
|
|
193
|
+
`proxy: { https: false, port: 8080 }` produces `http://shop.localhost:8080`. The dynamically assigned app port does not
|
|
194
|
+
appear in the browser-facing origin.
|
|
195
|
+
|
|
196
|
+
### Default names
|
|
197
|
+
|
|
198
|
+
For a project named `shop`, a workspace package named `web`, and a worktree folder named `fix-login`:
|
|
199
|
+
|
|
200
|
+
| Detected endpoint | Primary checkout | Linked worktree |
|
|
201
|
+
| ---------------------------------- | ---------------------------- | -------------------------------------- |
|
|
202
|
+
| Root app: `app` | `shop.localhost` | `shop-fix-login.localhost` |
|
|
203
|
+
| Root Storybook: `stories` | `shop-stories.localhost` | `shop-fix-login-stories.localhost` |
|
|
204
|
+
| Root E2E: `app-e2e` | `shop-app-e2e.localhost` | `shop-fix-login-app-e2e.localhost` |
|
|
205
|
+
| Workspace app: `web-app` | `shop-web-app.localhost` | `shop-fix-login-web-app.localhost` |
|
|
206
|
+
| Workspace Storybook: `web-stories` | `shop-web-stories.localhost` | `shop-fix-login-web-stories.localhost` |
|
|
207
|
+
| Workspace E2E: `web-app-e2e` | `shop-web-app-e2e.localhost` | `shop-fix-login-web-app-e2e.localhost` |
|
|
208
|
+
|
|
209
|
+
These are discovery conventions. In a manually written config, the schema defaults are
|
|
210
|
+
`primaryName: "{project}-{service}"` and `name: "{project}-{worktree}-{service}"`. Set the templates explicitly when you
|
|
211
|
+
want a shorter root app name, as in the configuration example below.
|
|
212
|
+
|
|
213
|
+
The **primary checkout** is Git's original working checkout. A **linked worktree** is another checkout created with Git
|
|
214
|
+
worktrees. The primary checkout never receives a `main` label, even when its branch is named `main`. A linked worktree
|
|
215
|
+
folder named `main` does receive that label. Outside Git, the project is treated as a primary checkout.
|
|
216
|
+
|
|
217
|
+
### Using your own domain
|
|
218
|
+
|
|
219
|
+
For a domain you control, such as `example.com`, this configuration puts the primary app at `local.example.com` and
|
|
220
|
+
Storybook at `stories.local.example.com`:
|
|
221
|
+
|
|
222
|
+
```ts
|
|
223
|
+
// dev-domains.config.ts
|
|
224
|
+
import { defineConfig } from "@buildkitgg/dev-domains"
|
|
225
|
+
|
|
226
|
+
export default defineConfig({
|
|
227
|
+
project: "shop",
|
|
228
|
+
domain: "example.com",
|
|
229
|
+
packageManager: "pnpm",
|
|
230
|
+
endpoints: {
|
|
231
|
+
app: {
|
|
232
|
+
cwd: "apps/web",
|
|
233
|
+
script: "dev:raw",
|
|
234
|
+
framework: "next",
|
|
235
|
+
primaryName: "local",
|
|
236
|
+
name: "{worktree}.local"
|
|
237
|
+
},
|
|
238
|
+
stories: {
|
|
239
|
+
kind: "storybook",
|
|
240
|
+
cwd: "apps/web",
|
|
241
|
+
script: "storybook",
|
|
242
|
+
framework: "storybook",
|
|
243
|
+
primaryName: "stories.local",
|
|
244
|
+
name: "{worktree}.stories.local"
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
})
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Use `domain: "example.com"` with `primaryName: "local"` to get the bare `local.example.com` address. Setting only
|
|
251
|
+
`domain: "local.example.com"` retains an endpoint-name prefix, such as `shop.local.example.com`.
|
|
252
|
+
|
|
253
|
+
The same convention can cover additional servers you configure:
|
|
254
|
+
|
|
255
|
+
| Server | `primaryName` | `name` for linked worktrees | Primary hostname |
|
|
256
|
+
| ------------- | --------------- | --------------------------- | --------------------------- |
|
|
257
|
+
| Web app | `local` | `{worktree}.local` | `local.example.com` |
|
|
258
|
+
| Separate API | `api.local` | `{worktree}.api.local` | `api.local.example.com` |
|
|
259
|
+
| Storybook | `stories.local` | `{worktree}.stories.local` | `stories.local.example.com` |
|
|
260
|
+
| Dedicated E2E | `e2e.local` | `{worktree}.e2e.local` | `e2e.local.example.com` |
|
|
261
|
+
|
|
262
|
+
A separate API server uses an endpoint key such as `api` with `kind: "app"`; there is no separate `api` kind. When API
|
|
263
|
+
routes, auth callbacks, or webhook handlers live in the web app, they share its origin and use paths such as `/api`,
|
|
264
|
+
`/callback`, or `/api/webhooks/payments`.
|
|
265
|
+
|
|
266
|
+
Use Portless hosts synchronization, or arrange loopback DNS for every generated hostname. If managing DNS yourself,
|
|
267
|
+
cover the base `local.example.com` as well as the worktree and service names, and set `proxy.syncHosts: false`.
|
|
268
|
+
`dev-domains` does not create DNS records or provider registrations. A real domain resolving to loopback still points to
|
|
269
|
+
your machine; public webhook delivery requires a [tunnel](#webhook-tunnels).
|
|
270
|
+
|
|
271
|
+
## Domain normalization and collisions
|
|
272
|
+
|
|
273
|
+
Automatically discovered names are normalized before they enter the templates. Values you write explicitly in a
|
|
274
|
+
configuration file are validated, rather than silently rewritten.
|
|
275
|
+
|
|
276
|
+
| Input | Normalization |
|
|
277
|
+
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
278
|
+
| Discovered project name | Remove the leading npm scope marker, convert the scope separator to a hyphen, lowercase, replace runs of characters other than `a-z`, `0-9`, and `-` with `-`, limit to 32 characters, trim edge hyphens; use `app` if empty |
|
|
279
|
+
| Discovered workspace label | Use the unscoped package name or folder name, then apply the same lowercase, replacement, 32-character limit, and fallback rules |
|
|
280
|
+
| Linked worktree name | Use the folder basename, lowercase, replace unsupported character runs with `-`, and trim edge hyphens; reject empty names or names longer than 63 characters |
|
|
281
|
+
| Explicit project name and endpoint keys | Require lowercase DNS labels of 1–63 characters, beginning and ending with a letter or digit |
|
|
282
|
+
| Resolved name templates | Allow dot-separated lowercase DNS labels; each label must be 1–63 characters |
|
|
283
|
+
| Full hostname | At most 253 characters, including the configured suffix |
|
|
284
|
+
|
|
285
|
+
For example, `@acme/shop` becomes project `acme-shop`, `@acme/web` supplies workspace label `web`, and a worktree folder
|
|
286
|
+
named `Fix_Login!` becomes `fix-login`. No branch name, commit ID, or path hash is added. Moving a linked worktree
|
|
287
|
+
without renaming its folder keeps its name; renaming the folder changes it.
|
|
288
|
+
|
|
289
|
+
Normalization can produce collisions: `fix_login` and `fix-login` become the same label, and long discovered project
|
|
290
|
+
names can share the same first 32 characters. Independent clones with identical names can also collide. Duplicate
|
|
291
|
+
endpoint keys are rejected during discovery. Resolution rejects endpoints that produce the same name, and startup
|
|
292
|
+
reports a hostname already owned by a running server. Choose a distinct project name, worktree folder, or name template.
|
|
293
|
+
Existing routes are never forcibly replaced.
|
|
294
|
+
|
|
295
|
+
Custom layouts can also overlap service and worktree names: a worktree named `stories` would put its app at the same
|
|
296
|
+
address as the primary Storybook in the example above. Choose different names or templates for that layout.
|
|
297
|
+
|
|
298
|
+
## Configuration files
|
|
299
|
+
|
|
300
|
+
Use a saved configuration when you need custom naming, a server the detector cannot identify, or application-specific
|
|
301
|
+
settings. TypeScript configuration uses the exported `defineConfig` helper:
|
|
302
|
+
|
|
303
|
+
```ts
|
|
304
|
+
// dev-domains.config.ts
|
|
305
|
+
import { defineConfig } from "@buildkitgg/dev-domains"
|
|
306
|
+
|
|
307
|
+
export default defineConfig({
|
|
308
|
+
project: "shop",
|
|
309
|
+
packageManager: "pnpm",
|
|
310
|
+
endpoints: {
|
|
311
|
+
app: {
|
|
312
|
+
script: "dev",
|
|
313
|
+
framework: "vite",
|
|
314
|
+
primaryName: "{project}",
|
|
315
|
+
name: "{project}-{worktree}"
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
})
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
`defineConfig` supplies TypeScript checking and runtime validation. A plain JSON config receives the same runtime
|
|
322
|
+
validation. The wizard writes `dev-domains.json`; you can maintain that file or replace it with a typed config.
|
|
323
|
+
|
|
324
|
+
### File discovery and precedence
|
|
325
|
+
|
|
326
|
+
The supported automatically discovered filenames are:
|
|
327
|
+
|
|
328
|
+
- `dev-domains.config.ts`
|
|
329
|
+
- `dev-domains.config.mts`
|
|
330
|
+
- `dev-domains.config.js`
|
|
331
|
+
- `dev-domains.config.mjs`
|
|
332
|
+
- `dev-domains.config.json`
|
|
333
|
+
- `dev-domains.json`
|
|
334
|
+
|
|
335
|
+
Resolution follows this order:
|
|
336
|
+
|
|
337
|
+
1. A file selected with `--config`, relative to `--cwd`.
|
|
338
|
+
2. The nearest supported config, searching from `--cwd` up to the Git checkout boundary. Outside Git, only the selected
|
|
339
|
+
directory is searched.
|
|
340
|
+
3. Detected defaults when no file is found.
|
|
341
|
+
|
|
342
|
+
Multiple supported configs in one directory are an error. The selected file's directory becomes the configuration root;
|
|
343
|
+
endpoint `cwd` paths are relative to it. At startup, endpoint directories must stay within that root, including after
|
|
344
|
+
resolving symlinks.
|
|
345
|
+
|
|
346
|
+
A saved configuration is complete: detected endpoints are not merged into it. In particular, an omitted `packageManager`
|
|
347
|
+
in a saved config defaults to **npm**, while zero-config discovery detects the manager. Specify your manager when
|
|
348
|
+
authoring a config for pnpm, Yarn, or Bun.
|
|
349
|
+
|
|
350
|
+
Configuration loading uses c12 with home configuration, implicit `.env` loading, package.json config, remote extensions,
|
|
351
|
+
and environment-specific merging disabled. Your framework may still load its own environment files. JavaScript and
|
|
352
|
+
TypeScript configs execute as code when loaded; use configs from repositories you trust. The `detect` command always
|
|
353
|
+
inspects project conventions without loading a dev-domains config.
|
|
354
|
+
|
|
355
|
+
### JSON editor support
|
|
356
|
+
|
|
357
|
+
Generate the schema from the installed version:
|
|
358
|
+
|
|
359
|
+
```sh
|
|
360
|
+
npx @buildkitgg/dev-domains schema > dev-domains.schema.json
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
Then reference it from `dev-domains.json` for editor completion and validation:
|
|
364
|
+
|
|
365
|
+
```json
|
|
366
|
+
{
|
|
367
|
+
"$schema": "./dev-domains.schema.json",
|
|
368
|
+
"project": "shop",
|
|
369
|
+
"packageManager": "pnpm",
|
|
370
|
+
"endpoints": {
|
|
371
|
+
"app": {
|
|
372
|
+
"script": "dev",
|
|
373
|
+
"framework": "vite",
|
|
374
|
+
"primaryName": "{project}",
|
|
375
|
+
"name": "{project}-{worktree}"
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
}
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
## Configuration schema
|
|
382
|
+
|
|
383
|
+
Unknown keys are rejected. Defaults below describe a saved configuration; discovery may generate more specific values.
|
|
384
|
+
Names, paths, and templates are validated when the config is loaded or resolved.
|
|
385
|
+
|
|
386
|
+
### Root fields
|
|
387
|
+
|
|
388
|
+
| Field | Type | Default or requirement | Description |
|
|
389
|
+
| ---------------- | --------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
|
|
390
|
+
| `$schema` | `string` | Optional | JSON editor schema reference |
|
|
391
|
+
| `project` | `string` | Required | Lowercase DNS label identifying the project |
|
|
392
|
+
| `domain` | `string` | `"localhost"` | Hostname suffix without protocol, path, or port; lowercase DNS labels, up to 190 characters |
|
|
393
|
+
| `packageManager` | `"npm"`, `"pnpm"`, `"yarn"`, or `"bun"` | `"npm"` | Manager used to run endpoint scripts |
|
|
394
|
+
| `proxy` | Object | Defaults below | Shared Portless proxy settings |
|
|
395
|
+
| `endpoints` | Record of endpoint objects | Required, at least one entry | Keys are lowercase DNS labels used in CLI commands and the `{service}` template |
|
|
396
|
+
|
|
397
|
+
### Proxy fields
|
|
398
|
+
|
|
399
|
+
| Field | Type | Default | Description |
|
|
400
|
+
| ----------------- | --------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
401
|
+
| `proxy.port` | Integer, 1–65535 | `443` | Browser-facing proxy port, not an app's upstream port |
|
|
402
|
+
| `proxy.https` | `boolean` | `true` | Serve local origins over HTTPS |
|
|
403
|
+
| `proxy.syncHosts` | `boolean` | `true` | Allow Portless to synchronize local hosts entries |
|
|
404
|
+
| `proxy.domains` | Nonempty string array | `[domain]` when omitted | Explicit aliases for this project; must include its `domain`; each suffix follows the same rules as `domain` |
|
|
405
|
+
|
|
406
|
+
### Endpoint fields
|
|
407
|
+
|
|
408
|
+
Each entry in `endpoints` has these fields. Set **exactly one** of `script` or `command`.
|
|
409
|
+
|
|
410
|
+
| Field | Type | Default or requirement | Description |
|
|
411
|
+
| ------------- | ------------------------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
412
|
+
| `kind` | `"app"`, `"storybook"`, or `"e2e"` | `"app"` | Endpoint purpose; the Playwright helper requires `"e2e"` |
|
|
413
|
+
| `cwd` | `string` | `"."` | Server working directory, relative to the configuration root |
|
|
414
|
+
| `primaryName` | `string` | `"{project}-{service}"` | Name template used in the primary checkout |
|
|
415
|
+
| `name` | `string` | `"{project}-{worktree}-{service}"` | Name template used in a linked worktree |
|
|
416
|
+
| `script` | Nonempty string | Required unless `command` is set | Script from `cwd`'s `package.json`; the script must exist |
|
|
417
|
+
| `command` | Nonempty string array | Required unless `script` is set | Executable followed by arguments; each element must be nonempty and contain no NUL character |
|
|
418
|
+
| `framework` | `"next"`, `"vite"`, `"storybook"`, or `"custom"` | `"custom"` | Selects host and port flag adaptation; it is independent of `kind` |
|
|
419
|
+
| `env` | Record of string values | `{}` | Additional child-process environment variables; supports templates |
|
|
420
|
+
| `auth` | String array | `[]` | Callback paths included in the `urls` output |
|
|
421
|
+
| `tunnel` | Object | Omitted | Optional public webhook tunnel settings below |
|
|
422
|
+
|
|
423
|
+
Environment keys must start with a letter or underscore and contain only letters, digits, and underscores. `PORT`,
|
|
424
|
+
`HOST`, keys starting with `PORTLESS`, and keys starting with `BUILDKIT_` are reserved. Keep secrets in your environment
|
|
425
|
+
or your application's secret-loading mechanism rather than committing them to this file.
|
|
426
|
+
|
|
427
|
+
### Tunnel fields
|
|
428
|
+
|
|
429
|
+
These fields apply only when an endpoint has a `tunnel` object:
|
|
430
|
+
|
|
431
|
+
| Field | Type | Default or requirement | Description |
|
|
432
|
+
| ------------------ | --------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
433
|
+
| `tunnel.command` | Nonempty string array | Required | Tunnel executable and arguments; must contain `{url}` to target the restricted local gateway |
|
|
434
|
+
| `tunnel.paths` | Nonempty string array | Required | Exact allowed POST paths |
|
|
435
|
+
| `tunnel.publicUrl` | HTTPS origin string | Optional | An existing stable public origin, used for display and `urls` output; it does not provision a tunnel |
|
|
436
|
+
|
|
437
|
+
`auth` and `tunnel.paths` values must begin with one `/`. They cannot include query strings, fragments, backslashes,
|
|
438
|
+
percent encoding, or `.` / `..` path segments. Tunnel paths are exact matches, not wildcard patterns. `tunnel.publicUrl`
|
|
439
|
+
cannot include credentials, a query, a fragment, or a path other than `/`.
|
|
440
|
+
|
|
441
|
+
## Templates and environment variables
|
|
442
|
+
|
|
443
|
+
Templates expand in name fields, command arguments, and environment values. Unknown template variables cause an error.
|
|
444
|
+
`script` and `cwd` are literal values; callback and allowed webhook paths are also literal.
|
|
445
|
+
|
|
446
|
+
| Variable | Meaning | Where it can be used |
|
|
447
|
+
| ------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
448
|
+
| `{project}` | Configured project name | Name templates, server command/env, tunnel command |
|
|
449
|
+
| `{worktree}` | Normalized linked-worktree folder name; empty for the primary checkout | Name templates, server command/env, tunnel command |
|
|
450
|
+
| `{service}` | Endpoint key, such as `app` or `stories` | Name templates, server command/env, tunnel command |
|
|
451
|
+
| `{root}` | Absolute configuration or detected project root | Name templates, server command/env, tunnel command; filesystem separators usually make it unsuitable for DNS names |
|
|
452
|
+
| `{hostname}` | Resolved hostname without protocol or port | Server command/env and tunnel command |
|
|
453
|
+
| `{origin}` | Resolved browser-facing origin, including a nonstandard proxy port | Server command/env and tunnel command |
|
|
454
|
+
| `{port}` | Dynamically assigned app-server port | Server command and env only |
|
|
455
|
+
| `{url}` | Restricted webhook gateway's loopback URL | Tunnel command only |
|
|
456
|
+
|
|
457
|
+
Every server receives these environment variables:
|
|
458
|
+
|
|
459
|
+
| Variable | Value |
|
|
460
|
+
| ---------------------- | ----------------------------------------------------------------- |
|
|
461
|
+
| `PORT` | Assigned app-server port |
|
|
462
|
+
| `HOST` | `127.0.0.1` |
|
|
463
|
+
| `DEV_DOMAINS_ORIGIN` | Resolved browser-facing origin |
|
|
464
|
+
| `DEV_DOMAINS_HOSTNAME` | Resolved hostname |
|
|
465
|
+
| `DEV_DOMAINS_WORKTREE` | Normalized worktree folder name, or empty in the primary checkout |
|
|
466
|
+
|
|
467
|
+
For example, an endpoint can set `env: { APP_URL: "{origin}", AUTH_REDIRECT_URI: "{origin}/callback" }`. Standard
|
|
468
|
+
process environment variables are inherited. The runtime values listed above take precedence over same-named values
|
|
469
|
+
inherited from the shell or supplied through `env`.
|
|
470
|
+
|
|
471
|
+
## Server commands and frameworks
|
|
472
|
+
|
|
473
|
+
Use `script` to run an existing package script, or `command` for an executable and argument array. Arguments remain
|
|
474
|
+
separate, so a file path containing spaces stays one argument. Command arrays are not interpreted as shell expressions.
|
|
475
|
+
|
|
476
|
+
For a custom server that accepts a port flag:
|
|
477
|
+
|
|
478
|
+
```ts
|
|
479
|
+
api: {
|
|
480
|
+
kind: "app",
|
|
481
|
+
cwd: "apps/api",
|
|
482
|
+
command: ["node", "server.js", "--port", "{port}"],
|
|
483
|
+
framework: "custom"
|
|
484
|
+
}
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
For a custom server that reads `PORT` and `HOST` directly, `command: ["node", "server.js"]` is sufficient. Package-local
|
|
488
|
+
binaries are available on the server's `PATH`.
|
|
489
|
+
|
|
490
|
+
| Framework | Flags appended to the server invocation |
|
|
491
|
+
| ----------- | -------------------------------------------------------------------------- |
|
|
492
|
+
| `next` | `--hostname 127.0.0.1 --port <assigned port>` |
|
|
493
|
+
| `vite` | `--host 127.0.0.1 --port <assigned port> --strictPort` |
|
|
494
|
+
| `storybook` | `--host 127.0.0.1 --port <assigned port> --exact-port --no-open --ci` |
|
|
495
|
+
| `custom` | None; the server must honor `PORT` / `HOST` or explicit `{port}` arguments |
|
|
496
|
+
|
|
497
|
+
Use `framework: "custom"` for compound shell scripts or commands that cannot accept appended flags. Detection does this
|
|
498
|
+
automatically for compound scripts. In a saved config, choose the appropriate framework yourself. `kind` does not select
|
|
499
|
+
it for you.
|
|
500
|
+
|
|
501
|
+
Keep the underlying server script free of another `dev-domains` or Portless invocation. For example, a package can use
|
|
502
|
+
`"dev": "npx @buildkitgg/dev-domains run app"` together with `"dev:raw": "vite"`, while the endpoint references
|
|
503
|
+
`script: "dev:raw"`. Configuring `script: "dev"` in that example would recurse and is rejected.
|
|
504
|
+
|
|
505
|
+
Your framework still controls allowed hosts, development origins, and output directories. Add your generated hostnames
|
|
506
|
+
to its configuration where required. When a server exits, its exit code is propagated. Custom servers must fail on a
|
|
507
|
+
port conflict rather than silently switching ports.
|
|
508
|
+
|
|
509
|
+
## Playwright
|
|
510
|
+
|
|
511
|
+
You can test an already running app by setting Playwright's `use.baseURL` to its origin. To let Playwright manage a
|
|
512
|
+
separate server, configure a dedicated endpoint:
|
|
513
|
+
|
|
514
|
+
```ts
|
|
515
|
+
// Add under endpoints in dev-domains.config.ts.
|
|
516
|
+
"app-e2e": {
|
|
517
|
+
kind: "e2e",
|
|
518
|
+
cwd: "apps/web",
|
|
519
|
+
script: "dev:raw",
|
|
520
|
+
framework: "next",
|
|
521
|
+
env: { DEV_DOMAINS_OUTPUT_DIR: ".dev-domains/app-e2e" }
|
|
522
|
+
}
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
Then use the helper in `playwright.config.ts`:
|
|
526
|
+
|
|
527
|
+
```ts
|
|
528
|
+
import { defineConfig } from "@playwright/test"
|
|
529
|
+
import { playwrightServer } from "@buildkitgg/dev-domains/playwright"
|
|
530
|
+
|
|
531
|
+
export default defineConfig({
|
|
532
|
+
...(await playwrightServer("app-e2e")),
|
|
533
|
+
testDir: "./tests"
|
|
534
|
+
})
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
`playwrightServer(endpoint, cwd?)` loads the project from `cwd` or `process.cwd()`. It returns `use.baseURL` and a
|
|
538
|
+
`webServer` configuration that runs the endpoint, waits up to 120 seconds, and sets `reuseExistingServer: false`. If you
|
|
539
|
+
add other Playwright `use` or `webServer` options, merge those nested objects so you preserve the helper's values. In a
|
|
540
|
+
monorepo, use the exact configured endpoint key, such as `web-app-e2e`, and a working directory from which the intended
|
|
541
|
+
dev-domains config can be found.
|
|
542
|
+
|
|
543
|
+
The endpoint's script must start a server, not run `playwright test`. The helper does not install Playwright or edit its
|
|
544
|
+
configuration. Run `npx @buildkitgg/dev-domains setup` before the test run on a development machine.
|
|
545
|
+
|
|
546
|
+
A dedicated endpoint gets a separate hostname and port, but you must also isolate build output when the framework
|
|
547
|
+
requires it. Detection and the wizard set `DEV_DOMAINS_OUTPUT_DIR` for E2E candidates. The framework must consume that
|
|
548
|
+
variable; for example, a Next.js config can set `distDir: process.env.DEV_DOMAINS_OUTPUT_DIR || ".next"`. Databases,
|
|
549
|
+
storage, and credentials are still shared unless you configure them separately.
|
|
550
|
+
|
|
551
|
+
## Node.js tooling
|
|
552
|
+
|
|
553
|
+
Build scripts and local workers can read an endpoint without starting a server:
|
|
554
|
+
|
|
555
|
+
```ts
|
|
556
|
+
import { getEndpoint } from "@buildkitgg/dev-domains/node"
|
|
557
|
+
|
|
558
|
+
const app = await getEndpoint("app")
|
|
559
|
+
process.env.APP_URL = app.origin
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
`getEndpoint(service, cwd?)` returns a promise containing `service`, `hostname`, `origin`, `callbacks` (resolved auth
|
|
563
|
+
URLs), and `cwd` (the server's absolute working directory). It uses the CLI's configuration discovery and worktree
|
|
564
|
+
naming rules; `cwd` defaults to `process.cwd()`. An unknown endpoint throws. The exported `EndpointInfo` type describes
|
|
565
|
+
the result. This Node.js-only helper can execute trusted local configuration files, just like the CLI. It does not
|
|
566
|
+
allocate a port, start the proxy, or register a route.
|
|
567
|
+
|
|
568
|
+
## Authentication callbacks
|
|
569
|
+
|
|
570
|
+
Auth callbacks are paths on the server that handles authentication. Add paths to `auth` to include their full URLs in
|
|
571
|
+
`npx @buildkitgg/dev-domains urls` output:
|
|
572
|
+
|
|
573
|
+
```ts
|
|
574
|
+
// Add to the endpoint that serves these routes.
|
|
575
|
+
auth: ["/callback", "/api/auth/callback/github"],
|
|
576
|
+
env: { AUTH_REDIRECT_URI: "{origin}/callback" }
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
Register the resulting URLs with your authentication or OAuth provider and connect the environment variables to your
|
|
580
|
+
application's auth configuration. `auth` is descriptive: it does not create routes, update provider dashboards, or
|
|
581
|
+
configure an SDK. The environment variable names in these examples are application choices.
|
|
582
|
+
|
|
583
|
+
When a provider requires a real domain, use the custom-domain layout above. Keep primary and worktree origins in the
|
|
584
|
+
appropriate redirect, allowed-origin, or API-key restriction settings. Accepted wildcard patterns differ by service; use
|
|
585
|
+
the exact `urls` output where required. A separate auth subdomain is only useful if you actually run a separate auth
|
|
586
|
+
server.
|
|
587
|
+
|
|
588
|
+
## Webhook tunnels
|
|
589
|
+
|
|
590
|
+
A remote service cannot deliver a webhook to a loopback-only address. An optional tunnel makes selected POST routes
|
|
591
|
+
reachable through a public URL while the rest of the app remains behind the local proxy.
|
|
592
|
+
|
|
593
|
+
Add a tunnel to the endpoint that already serves the webhook handler. For example, with `cloudflared` installed:
|
|
594
|
+
|
|
595
|
+
```ts
|
|
596
|
+
// Add to the app or API endpoint.
|
|
597
|
+
tunnel: {
|
|
598
|
+
command: ["cloudflared", "tunnel", "--url", "{url}"],
|
|
599
|
+
paths: ["/api/webhooks/payments"]
|
|
600
|
+
}
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
Start the app first, then open the tunnel in another terminal:
|
|
604
|
+
|
|
605
|
+
```sh
|
|
606
|
+
npx @buildkitgg/dev-domains run app
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
```sh
|
|
610
|
+
npx @buildkitgg/dev-domains tunnel app
|
|
611
|
+
```
|
|
612
|
+
|
|
613
|
+
The tunnel provider prints its public URL. Register that origin plus `/api/webhooks/payments` with the sending service.
|
|
614
|
+
No separate webhook subdomain is required. A quick tunnel URL may change after restart. For persistent registrations,
|
|
615
|
+
configure a stable tunnel with your provider and optionally record its HTTPS origin in `tunnel.publicUrl`. That property
|
|
616
|
+
reports an existing address; it does not reserve a domain or configure the tunnel command.
|
|
617
|
+
|
|
618
|
+
The tunnel targets a restricted gateway that holds an OS-assigned loopback port open. It forwards only POST requests
|
|
619
|
+
whose paths exactly match `tunnel.paths`. Query strings, raw request bytes, and signature headers are preserved;
|
|
620
|
+
hop-by-hop headers and the inbound `Forwarded`, `X-Forwarded-For`, and `X-Forwarded-Host` headers are stripped. Request
|
|
621
|
+
bodies are limited to 1 MiB, upstream requests time out after 15 seconds, and payloads are not logged or stored. Your
|
|
622
|
+
application must validate provider signatures. Providers that require a GET verification challenge need a different
|
|
623
|
+
ingress arrangement; this gateway is POST-only.
|
|
624
|
+
|
|
625
|
+
Install and authenticate the tunnel executable separately. It runs from the configuration root and inherits the shell
|
|
626
|
+
environment, rather than the endpoint's server `env` overrides. Keep credentials in the provider's login store or
|
|
627
|
+
environment. Closing the tunnel command stops its process tree and gateway while leaving the app and shared proxy
|
|
628
|
+
running. A hosted receiver, durable delivery, and replay are not included.
|
|
629
|
+
|
|
630
|
+
## Sharing a proxy across projects
|
|
631
|
+
|
|
632
|
+
One machine can run many endpoints through one Portless proxy, with a separate domain for each project. Keep the proxy
|
|
633
|
+
port and TLS mode aligned. To give one project's endpoints additional aliases, configure an explicit list:
|
|
634
|
+
|
|
635
|
+
```ts
|
|
636
|
+
// Root configuration fields, alongside project and endpoints.
|
|
637
|
+
domain: "example.com",
|
|
638
|
+
proxy: {
|
|
639
|
+
domains: ["localhost", "example.com"],
|
|
640
|
+
port: 443,
|
|
641
|
+
https: true,
|
|
642
|
+
syncHosts: true
|
|
643
|
+
}
|
|
644
|
+
```
|
|
645
|
+
|
|
646
|
+
Each project registers complete hostnames in Portless's shared route registry. Projects can use different domains
|
|
647
|
+
without coordinating a suffix list: `local.copacker.ai` and `local.spawnkit.cloud` can run together on the same proxy.
|
|
648
|
+
Leave `proxy.domains` unset unless this project's endpoints should have additional aliases. An explicit list registers
|
|
649
|
+
each endpoint under those suffixes only; `domain` selects its canonical origin. This preserves existing alias configs. A
|
|
650
|
+
collision means the **complete hostname** is occupied, not just the endpoint name.
|
|
651
|
+
|
|
652
|
+
Projects sharing one proxy must agree on its port and TLS settings. Buildkit reuses a compatible proxy without changing
|
|
653
|
+
its startup suffixes or restarting it. DNS must resolve every custom hostname to loopback; either use Portless's hosts
|
|
654
|
+
synchronization or configure DNS yourself. If the existing proxy was started with hosts synchronization disabled,
|
|
655
|
+
`syncHosts: true` cannot change that running process. Coordinate proxy configuration or configure DNS separately.
|
|
656
|
+
`npx @buildkitgg/dev-domains doctor` helps diagnose the current state.
|
|
657
|
+
|
|
658
|
+
Buildkit holds an OS-assigned loopback port while registering the route, then releases the socket immediately before
|
|
659
|
+
starting the server. Other Buildkit launchers avoid ports in the shared registry, including servers still starting. Most
|
|
660
|
+
framework CLIs cannot inherit the reserved socket, so unrelated programs can still race that final handoff. Buildkit
|
|
661
|
+
makes at most three attempts, retrying only an explicit `EADDRINUSE` or address-in-use failure. Make startup safe to
|
|
662
|
+
repeat. A hostname collision never triggers a forced route takeover.
|
|
663
|
+
|
|
664
|
+
## CI usage
|
|
665
|
+
|
|
666
|
+
Commit a configuration and use explicit endpoint names in noninteractive jobs. The Playwright helper can start a
|
|
667
|
+
dedicated test server, or you can keep your existing loopback-based Playwright setup.
|
|
668
|
+
|
|
669
|
+
For jobs that use Portless, set a job-specific `PORTLESS_STATE_DIR` and choose an unprivileged proxy port. For example,
|
|
670
|
+
a CI config can use `proxy: { https: false, port: 8080, syncHosts: false }`. Ensure generated hostnames resolve to
|
|
671
|
+
loopback in the runner when hosts synchronization is disabled. HTTP avoids a certificate-trust step; HTTPS requires the
|
|
672
|
+
runner to trust the local certificate authority. Select a complete CI config through the normal file-loading rules or
|
|
673
|
+
`--config` for CLI commands; there is no implicit environment-specific config merge.
|
|
674
|
+
|
|
675
|
+
The Playwright helper uses normal config discovery from its `cwd`; it does not accept the CLI's `--config` option. Place
|
|
676
|
+
a CI config where that lookup finds it if you use the helper. Concurrent jobs sharing a machine also need compatible
|
|
677
|
+
shared proxy settings or distinct proxy ports; a separate state directory alone does not free a bound port.
|
|
678
|
+
|
|
679
|
+
## Command reference
|
|
680
|
+
|
|
681
|
+
These are complete consumer-facing commands. They use the locally installed package; follow the installation steps above
|
|
682
|
+
first.
|
|
683
|
+
|
|
684
|
+
| Command | Purpose | Supported project options |
|
|
685
|
+
| ----------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------ |
|
|
686
|
+
| `npx @buildkitgg/dev-domains` | Run the default command; select an endpoint if several exist | `--cwd`, `--config` |
|
|
687
|
+
| `npx @buildkitgg/dev-domains run [endpoint]` | Start one detected or configured endpoint | `--cwd`, `--config` |
|
|
688
|
+
| `npx @buildkitgg/dev-domains init` | Run the setup wizard and save `dev-domains.json` | `--cwd`, `--yes`, `--dry-run`, `--project`, `--domain` |
|
|
689
|
+
| `npx @buildkitgg/dev-domains detect` | Print detected candidates as JSON, ignoring saved dev-domains config | `--cwd` |
|
|
690
|
+
| `npx @buildkitgg/dev-domains urls` | Print endpoint origins, callback URLs, and configured webhook origins as JSON | `--cwd`, `--config` |
|
|
691
|
+
| `npx @buildkitgg/dev-domains setup` | Start the Portless proxy with project settings | `--cwd`, `--config` |
|
|
692
|
+
| `npx @buildkitgg/dev-domains status` | List active Portless routes | `--cwd`, `--config` |
|
|
693
|
+
| `npx @buildkitgg/dev-domains doctor` | Check proxy, DNS, and certificate trust | `--cwd`, `--config` |
|
|
694
|
+
| `npx @buildkitgg/dev-domains tunnel [endpoint]` | Expose an endpoint's configured webhook POST paths | `--cwd`, `--config` |
|
|
695
|
+
| `npx @buildkitgg/dev-domains schema` | Print the configuration JSON Schema | None |
|
|
696
|
+
|
|
697
|
+
`--cwd` defaults to the current directory. `--config` is a file path relative to `--cwd`. Use `--help` on a command for
|
|
698
|
+
its options. `run` and `tunnel` require an endpoint name in noninteractive sessions when more than one candidate exists.
|
|
699
|
+
|
|
700
|
+
The CLI never rewrites package scripts. It propagates server exit codes and cleans up its own routes when the server
|
|
701
|
+
stops. The shared proxy is left running. After a hard crash, Portless handles stale routes during subsequent operation.
|
|
702
|
+
`PORTLESS_STATE_DIR` can select a separate state directory; most consumers should keep the default shared state.
|
|
703
|
+
|
|
704
|
+
## Troubleshooting
|
|
705
|
+
|
|
706
|
+
| Symptom | What to check |
|
|
707
|
+
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
708
|
+
| No endpoints were detected | Run `detect`; check the app script conventions or add an explicit `command` / `script` endpoint |
|
|
709
|
+
| A wrapped script is rejected | Reference the underlying server script, such as `dev:raw`, instead of a script invoking dev-domains or Portless |
|
|
710
|
+
| An endpoint name is ambiguous | Use `urls` for configured names or `detect` for discovered names, then pass one to `run` |
|
|
711
|
+
| Multiple configs or Storybook candidates were found | Keep one dev-domains config per directory; select the intended Storybook script or config directory explicitly |
|
|
712
|
+
| The wrong package manager is used | In a saved config, set `packageManager`; during discovery, check the root declaration and conflicting lockfiles |
|
|
713
|
+
| A hostname is already in use | Check `status`, then choose a distinct name or stop the server you own; do not take over another process's route |
|
|
714
|
+
| The proxy has different settings | Align port and TLS settings with the existing shared proxy before restarting your endpoint |
|
|
715
|
+
| The hostname does not resolve or HTTPS is untrusted | Run `doctor`; check loopback DNS or hosts synchronization and complete Portless certificate setup |
|
|
716
|
+
| The framework rejects the hostname | Configure its allowed hosts or development origins for your generated domains |
|
|
717
|
+
| App and E2E servers conflict despite different ports | Configure separate framework build/output directories; verify the app consumes `DEV_DOMAINS_OUTPUT_DIR` |
|
|
718
|
+
| A webhook returns 404 | Confirm it is a POST request to an exact allowed path; GET verification challenges are not supported by this gateway |
|
|
719
|
+
| A webhook cannot reach the app | Start the target endpoint first, verify the provider's current public URL, and check the tunnel process |
|
|
720
|
+
|
|
721
|
+
## Contributing and license
|
|
722
|
+
|
|
723
|
+
See the
|
|
724
|
+
[architecture and testing guide](https://github.com/AndrewCraswell/buildkit/blob/main/packages/dev-domains/docs/README.md)
|
|
725
|
+
and [contributor guide](https://github.com/AndrewCraswell/buildkit/blob/main/CONTRIBUTING.md) for development details.
|
|
726
|
+
|
|
727
|
+
[MIT licensed](https://github.com/AndrewCraswell/buildkit/blob/main/LICENSE). Part of Buildkit, whose domain is
|
|
728
|
+
[buildkit.gg](https://buildkit.gg). No Buildkit hosted service is required to use this package.
|