Debugging local websites on a real mobile device, using Safari

Safari actually provides a robust set of tools for debugging your locally-running websites on a real mobile device. These steps may work on platforms other than MacOS and iOS, but I haven’t tested them!

Requirements:

• Connect your iPhone to your Mac via USB
• Ensure your website can be accessed via your Network (i.e. usually you can expose it via ngrok or your own internal tooling; With astrojs you can listen to LAN addresses using the --host CLI option)

1. Go to your website

Using whatever address / method you used to expose your local dev server, navigate to the website.

2. Find your phone in Safari, open the Inspector

Go to the Develop menu in Safari and you should see your phone listed if you connected via USB. Hover over the device, and select <Your Device> > <Your Website>

Yes, my phone is called “I am Focused”, I need mental reminders sometimes, OKAY?

3. Use all the regular developer tools you’re used to using on desktop, but now on mobile!

This powerful method allows you to leverage all the goodies you’d normally have access to on your desktop website while developing.

Bonus: CORS

If you run into CORS issues while doing this, you may need to utilize a secret mobile menu to disable Cross-Origin Restrictions. You’ll know if you’re having CORS issues if your console has messages like:

Origin <your origin> is not allowed by Access-Control-Allow-Origin. Status code: 403
# ... or
Fetch API cannot load <some route> due to access control checks.
# ... or
Failed to load resource: Origin <your origin> is not allowed by Access-Control-Allow-Origin. Status code: 403

Essentially these messages mean that you’re making requests from some origin that does not match whoever the receiving origin is.

i.e. Your local 192.111.0.0:8080/api/dosomething is trying to send a message to a server at https://example.com

This is a security feature to ensure that websites cannot use your authenticated cookies to make requests to do things on your behalf. https://example.com has no idea that you’re developing your website locally when it sees 192.111.0.0; for all it knows you’re an attacker trying to do something malicious.

Safari goes one step further and disallows the client (front-end) from even attempting to make a fetch request from a domain other than the current client domain (i.e. in this case 192.111.0.0) To fix this for local development, you can disable cross-origin restrictions for your mobile testing like so:

Keep in mind you should put this protection back in place when you’re done! Most servers should still have CORS protection in-place, but this is just another line of defense to keep you safe while browsing.

Hint: If you’re developing a front-end that talks to a remote server (instead of developing with a local development server), then you may run into this issue and you will not solve it on the client side using the method above. You’ll need to modify the test server to allow requests from certain domains or IP addresses. For example, on a project I was working on, we opened up the test server so that requests from localhost were not restricted via CORS. While I was testing this method, however, I was using the exposed local-network address that astro gave me (i.e. 192.111.0.0:8080), which meant the test server did not recognize my calls and would not respond to them. However, for the production server it was restricted to only the trusted production domains.