[Bug]: `cap run` ignores server config

[aolsenjazz]

Capacitor Version: 8.0.0

Thanks Ionic team for the work you do! The root issue that I'm calling out with this issue is that cap run -l ignores server config, but there are a few related issues imo worth solving here. I'm hoping that this issue can be a suitable place to discuss them at a high level before creating small-scope issues.

If preferred, I'm happy to break these out into small-scope tickets now, just lmk.

Current Behavior

cap run -l ignores capacitor.config.{ts|json|etc} server config. Instead, what happens is as follows:

• If --host cli arg is used, use that value
  • If not, resolve to a reasonable external network interface || localhost
• If --port cli arg is used, use that value
  • Otherwise, use port 3000
• Concatenate values to form connection string http://{host}:{port}

Pain points, use cases, solutions

Hardcoded http protocol

Paint point 1: My company's auth provider refuses to work on non-localhost && non-encrypted (http://) connections. I.e. http://localhost is fine, but http://192.168.x.x fails. This of course creates problems for running locally on hardware devices.

Pain point 2: I would like to add tunneling to my app via a --tunnel flag. A standard tunneling setup might use ngrok, and would therefore use a connection string like https://some-endpoint.ngrok.com. In order to do this, I would need to pass that endpoint to cap run -l at runtime. Using just --host and --port this is impossible; I need to be able to control the protocol.

Solutions: Add support for a --https/--protocol/ssl flag to cap run -l.

Bad values imputed when no host/port

Pain point 1: cap run -l auto selects a reasonable network interface to try to load the app from. Oftentimes, a non-peer-accessible network is selected. I regularly experience this behavior:

• I'm at a coffee shop/on a mobile hotspot which blocks peer traffic on e.g. the 10.x.x.x address space
  • 169.254.x.x address space is peer-accessible

Pain point 2: cap run -l uses port 3000 when a --port cli arg isn't passed. We cannot reasonably make the assumption that we should use port 3000, especially when one of the dominant bundlers uses 5173 by default.

Solutions: Three distinct behaviors here would constitute a solution:

• If --host and --port are unset, use server.url
  • If server.url is unset, use reasonable default according to existing strategy
• If --host is unset, use server.hostname for host
• Add port to server config
  • if --port is unset, use server.port
  • If server.port is unset, use reasonable default according to existing strategy

Remaining server fields are ignored

I haven't experienced pain points with fields iosScheme, androidScheme, errorPath, appStartPath, clearText. I have however with allowNavigation.

Pain point: As mentioned in the section on http protocol hardcoding, I would like to set up tunneling. In order to do this, I need to add ngrok endpoints to allowNavigation. This is impossible with cap run -l because these config fields get nuked.

Docs Mismatch

I believe that the fixes I've articulated here would make this experience in line with what users expect; it works this way when running via Xcode, why wouldn't it work this way via cap run -l? In addition, the docs for Capacitor configuration and cap run make no mention of these limitations.

Action Items

I'm happy to open PRs to address each fix individually in the proposed order:

1. When --host and --port are unset, use capacitor.config.* server config values. Add port support to server config object here too. If all values unset, use existing strategy for reasonable defaults
2. Preserve server config items when using cap run -l
3. Add --https support to `cap run

Would Ionic welcome PRs to address any of these problems? If so, I will happy open PRs to address whatever work is welcome. In my experience, they would go a long way in reconciling observed behavior with documented behavior, and bettering the DX.

Thanks again for the work you do.

Other API Details

Platforms Affected

• iOS
• Android
• Web

Current Behavior

cap run -l ignores capacitor.config.{ts|json|etc} server config. Instead, what happens is as follows:

• If --host cli arg is used, use that value
  • If not, resolve to a reasonable external network interface || localhost
• If --port cli arg is used, use that value
  • Otherwise, use port 3000
• Concatenate values to form connection string http://{host}:{port}

Expected Behavior

cap run -l respects server config object in capacitor.config.*

Project Reproduction

https://github.com/aolsenjazz/fresh-cap-repo

Additional Information

File references:

• server config nuke in livereload.ts
• Default value selection for host/port cli args

[OS-pedrogustavobilro]

Hey @aolsenjazz, thanks for the posting this comprehensive issue.

There have been a couple of PRs merged that address some of your proposed action items:

2. Preserve server config items when using cap run -l

• fix(cli): Don't overwrite config.server section with --live-reload #7528

3. Add --https support to `cap run

• feat(cli): Add --https option for --live-reload #8194

As for your other action item

When --host and --port are unset, use capacitor.config.* server config values. Add port support to server config object here too. If all values unset, use existing strategy for reasonable defaults

I opened a PR to address it #8370, although not exactly as you proposed. We didn't add port support to server config object, because this should be all configurable in url property, would feel more redundant than helpful.

It's also worth noting that when using the new --https flag, we no longer add a default port, and regarding one of your pain points (which still is true when not using --https flag)

Pain point 2: cap run -l uses port 3000 when a --port cli arg isn't passed. We cannot reasonably make the assumption that we should use port 3000, especially when one of the dominant bundlers uses 5173 by default.

Yes, maybe port 3000 made sense once upon a time, but no so much anymore. Making this change now would be a breaking change, but we may include this in a future Capacitor major.

With the merge of #8370, this should close your issue, but feel free to leave your feedback. Thank you!

[aolsenjazz]

This is great - thanks @OS-pedrogustavobilro! The changes you've made in those PRs make sense and so does the breaking change w.r.t. port selection. It looks like the remaining outstanding PR solves for the remainder of the pain points - looking forward to removing my Cap patch!

[OS-pedrogustavobilro]

Hey @aolsenjazz, apologies, part of my last comment was incorrect.

I closed #8370 in preference of #8373.

I think both you and I (and maybe other people) were confused on the purpose of --live-reload config flag. Per the original issue #6388, the proposed (and implemented) solution was

A way to set a server.url when running capacitor commands. This should override the value in capacitor.config.ts

In other words, the --live-reload flag overrides server.url by design. The thing that I think caused more confusion is the description of --live-reload option

Enable Live Reload

But in reality what it does is just allow configuring a live reload server via the CLI instead of via capacitor.config.ts. That description makes it sound like you need --live-reload to have a live-reload server with npx cap run, but you do not. It's just to override the server.url from capacitor config that is bundled into the native app. If you have are using a server.url in capacitor config already for development purposes, live reload should work fine with a regular cap run (no --live-reload)

The PR #8373 improves the descriptions of the live-reload parameters, and hopefully decreases these type of situations from happening again. I think with that said we have everything to close the issue, but would like to get your feedback first, whenever you can, thanks!

[aolsenjazz]

@OS-pedrogustavobilro really appreciate the work being done and you following up here. I've gotten lost in some of the same confusion - please confirm if this list correctly illustrates behavior:

1. -l enables consumption of --https, --host, and/or --port. Otherwise, --https, --host, and/or --port are _ignored

1.5 Implicit in the inclusion of --https, --host, and/or --port is that -l should be set

2. Omission of -l means that --https, --host, --port have no effect

3. Not-specifying --host or --port means that default values will be imputed, and you're considering different values (e.g. 5173) on the next major upgrade

Does that check out?

PS - as a consumer of Cap (y'all rock for maintaining it btw), this feels like a lot of undue complexity given that this all get transformed into a server.url value. Would be great in a future major release to be able to provide --dev-server-url or something similar.

[OS-pedrogustavobilro]

Yes, your points are correct. Just clarifying one of them

3. Not-specifying --host or --port means that default values will be imputed, and you're considering different values (e.g. 5173) on the next major upgrade

When -l is supplied Default values will be imputed for --host, and for port currently depends on -https being supplied or not. We don't supply a default port with --https, but didn't change it for non-https atm since that's a breaking change. Have a PR for that targeted for the next major, removing the default value entirely (#8376)

Would be great in a future major release to be able to provide --dev-server-url or something similar.

I do bring that up in the other PR, I am inclined to open a separate PR to do that (also for next major) and then we can decide on which one is better.