How It Works
CodeKit has a built-in server that always hosts the active project. The app automatically refreshes every browser that's connected to this server.
Just Click Preview
Click the Preview Button in the top right corner of the window. Copy the address to your other devices and be sure each is connected to the same WiFi network as your Mac. For static sites, that's it.
Sites With Dynamic Content
If your site uses server-side processing (like PHP) or you're doing something advanced:
- Configure an external server (like MAMP) to host your project
- Open Project Settings and choose the Browser Refreshing category
- Flip the External Server Required switch ON
- Enter the address of your external server
What Address Do I Enter In The Textfield?
The address of the server you set up in step one. If you're using MAMP and have not changed any defaults, it's usually http://localhost:8888 or it might be a custom virtual host you configured, like http://mysite.dev
Which Address Do I Load In My Browser?
ALWAYS go to CodeKit's internal server address (the one that opens when you click the "Preview" button). That's the only one CodeKit will auto-refresh. When you use an external server, CodeKit becomes a reverse-proxy; it talks to your external server to load content.
Injection vs. Full Reload
When you save a stylesheet, CodeKit refreshes the browser by injecting changes without reloading the entire page. When you save a page or script, however, the whole site reloads to capture those changes.
The Server Popover
Click the Server Button at the top of CodeKit's window. The popover that appears shows three addresses.
Bonjour Address
This will always have the form http://[your computer name]:5757. If your computer's name is long, you can shorten it in the Sharing Pane of macOS's System Preferences.
Non-Bonjour Address
The non-Bonjour address is for devices like Android or Windows, which don't support Bonjour networking. It will always be: http://[your Mac's local IP address]:5757
This Mac Only
The final address is always just localhost:5757. Use this if your Mac is not connected to any network.
WARNING: On some networks, the Bonjour address may not behave correctly. In those cases, use the Non-Bonjour address.
TLS Support
CodeKit supports TLS (formerly called SSL) on the Preview Server. To enable it, simply click the checkbox in the Server Popover. CodeKit's server will restart and you'll see https:// addresses.
NOTE: When TLS is enabled, if you forget to type https:// instead of http://, the page will hang and fail to load. You MUST use https when TLS is on.
Why Am I Asked For My Password?
CodeKit automatically generates the certificate required to run a secure server. You must tell your Mac to trust that certificate, which is why you're prompted for your password. This needs to be done only once.
It Doesn't Work In Firefox!
Firefox is a bad citizen of macOS. Instead of using the system-wide Keychain, Mozilla insists on having their own. Because of this, to use TLS in Firefox you must first enable enterprise certificates in Firefox and then install CodeKit's certificate in Firefox. This article will help. Using a different, better browser will also help.
Sharing Certificates To Devices
Before remote devices can connect to the secure Preview Server, you must install and trust CodeKit's TLS certificate on those devices.
Watch the screencast above to see a walkthrough, or follow these steps for each device:
iOS
- Open the Server Popover, click Share TLS Certificate, and then choose a way to send the certificate to your device (I recommend email).
- Tap the *.PEM file attached to the email, then tap Install, enter your passcode, and tap Install twice more to confirm.
- Go to Settings > General > About > Certificate Trust Settings and slide ON the switch next to "CodeKit Certificate Authority".
Another Mac
- Double-click the *.PEM file. This opens the app Keychain Access and adds the certificate to your keychain.
- In Keychain Access, double-click the "CodeKit Certificate Authority" item.
- At the top of the window, expand the "Trust" section, then choose "Always Trust" for the "When using this certificate" option.
- Close the window and enter your password when prompted.
Android
- Google how to add and trust a root CA certificate to your version of Android.
TLS Security
The certificate CodeKit generates is unique; you are the only person who has it. Because you have told your Mac and devices to trust anything signed with that certificate, it's important that you keep it private. If a malicious third party gets it, they can use it to fool your browsers into thinking fraudulent websites are legitimate.
If your certificate goes public, remove it from your Mac using the app Keychain Access. On iOS, remove it by opening Settings and scrolling down to "Configuration Profiles".
Finally, click Generate New Certificate in the Server Popover. You'll need to re-share that new certificate to all your devices.
It's Not Working!
See the Troubleshooting page for things to check.
Technical Details
CodeKit adds JavaScript to the <head> element of each page. This script links the page to CodeKit so it can be refreshed. For sites that use an External Server, CodeKit becomes a reverse-proxy server. It forwards each HTTP request to the External Server, listens for a response, injects the reload script if needed, and sends the result back to the browser. If your project uses an External Server, here's a few really technical things to be aware of:
Set-Cookie Headers
CodeKit strips all domain= values from each Set-cookie: header returned by your External Server. This causes the browser to store the cookie for the current document's domain, which is exactly what we want. The domain returned by your External Server will not match the domain of CodeKit's built-in server, so the browser would normally not store the cookie as instructed. Simply removing the domain value is more reliable than trying to modify it.
GZIP & Deflate
If your External Server returns gzipped or deflate-ed content, CodeKit will uncompress that data before sending it to the browser. This allows the app to inspect the page content and inject its reload script, if needed.
File Uploads
If your site accepts large uploads (such as videos or photos submitted through a form), you should not test those features while previewing the site through CodeKit's server. The upload will likely time out.