Introduction

This page provides specific details about using CodeKit. It's aimed at people familiar with the app and is very much a work in progress. If you're new to CodeKit and need to learn the basics, Watch the videos. I've made them very simple and beginner-friendly. If you email me for help about something that's covered in the videos, I will send angry midgets to throw darts at you in your sleep.

The $@#!ing App Won't Start!

Did you unzip it using a third-party unarchiver such as an app downloaded from the Mac App Store? OS X automatically quarantines all items that are unzipped without using OS X's built-in archive utility. This means CodeKit cannot launch all the tools it needs to work, such as the compilers for Less, Sass and so on.

You can resolve this two ways. First, delete the app, re-download it, and then unzip it using OS X's built-in archiver app. Alternately, you can follow the instructions found in this GitHub thread. If you'd like more information about the archive/quarantine issue, see this Apple Discussions Thread. (Long story short: it's one more bug in Apple's poorly-implemented and oft-delayed sandboxing initiative.)

If the above situation doesn't apply to you, quit CodeKit and launch it while holding down the shift key. This will clear all existing data from the app and should get you up and running again.

The Kit Language

CodeKit 1.4 offers a new language that allows you add imports and variables to HTML. It's great for folks that want to build static sites. You can master this language in five minutes flat because it's just HTML with special comments.. See here for all the details.

Using Project Settings

When you add a project to CodeKit, the app checks the preferences window to decide what the settings should be for each file in that project. (Do you want Sass indented or compressed? etc.) CodeKit also looks at the preferences window when you process a file with JSHint, JSLint or Uglify.js — that's where it gets the settings to use for each tool. Project Settings are essentially a "preferences window" that applies to only one project.

Getting Started With Project Settings

Select a project, right-click on it and choose "Project Settings > Enable Project Settings". When you do, CodeKit will copy your app-wide preferences and apply them as "project defaults". Then, it will show you an interface for changing those defaults. Any changes you make will apply only to the selected project. Note: CodeKit will NOT use the defaults from the preferences window when dealing with a project that has project-level defaults defined. (The project defaults "replace" the options from the preferences window.) You can easily tell which projects these are: look for an "S" in the folder icon next to the project's name.

Exporting Project Settings

Once you've got your project configured just the way you want, you can choose "Project Settings > Export Project Configuration File". This creates a file called codekit-config.json in your project's root folder. This file contains all the information necessary to recreate the project exactly as it appeared in CodeKit at the moment you exported the configuration file. It stores not only the project defaults you configured above, it also stores each project file's current configuration. So if you drag one javascript file into another to establish an import link, that information is captured in the configuration file. If you change the output path on "someFile.less" to be different than the default output path for LESS files in that project, that information is captured, too. It's all there.

The codekit-config.json file is created when you initially enable project-level settings for a particular project. After that, CodeKit will keep that config file updated with any changes by rewriting it every time your project is refreshed. If you do not want this automatic updating, you can disable it in the "general" pane of the Project Settings drawer.

Syncing Projects With Teams

When you add a project to CodeKit, the app will look for a file named codekit-config.json" in the project's root folder. If it exists, CodeKit will automatically set up the project to match the configuration file. First, it will apply the project defaults from the file. Then, it will change each file's settings to match those recorded for that file. (If it encounters a file that is not described, it will use the project defaults to set initial options for that file.) This makes it dead simple to work on projects in teams. One developer simply sets the project up, then exports a config file. The next developer gets a copy of the project (which contains the config file) and adds it to CodeKit.

It's important to note that CodeKit updates the config file only when your project is refreshed (unless you have explicitly disabled this auto-updating as described above). Therefore, any time you make changes to your project, you'll want to ensure that you refresh it before sharing the project with others so that the config file is updated to reflect those changes.

Applying Defaults From Config Files

If you select "Project Settings > Apply Project Defaults From File", CodeKit will change your project defaults to match those in the codekit-config.json file that you specify. It will NOT, however, make any changes to the individual files in your project. This feature is intended to "transfer" the project defaults from one project to another. When you finish one client website, you might want to use the same defaults for JSHint, JSLint, and languages on the next client's website. This second project has completely different files than the first one, so all you want is the project defaults. This option allows you to apply just those.

Clearing Project Settings

If you select "Project Settings > Clear Project Settings", CodeKit will remove the project-level defaults and go back to using app-wide preferences instead. This command will NOT change any settings on individual files within the project. It simply clears the project defaults.

New Functionality in Upgrades

As CodeKit evolves, it brings new functionality. For example, a future version might introduce a new option for JSHint that does not exist currently. When this happens, the codekit-config.json file for your project won't contain information about how that new JSHint option should be set (because it didn't exist when the config file was created!) In this case, CodeKit will copy the app-wide preference for the new option and apply that as the project-level default.

@import Statements

CodeKit automatically scans all project files to determine which ones import others. Although it's not required, you should always include a file extension in import statements. You may import more than one file per line using commas. Example: @codekit-prepend "jquery.js", "kill6.js";

CodeKit supports the Sass convention of omitting underscores in @import statements. For example, if you write @import "someFile" in a Sass or Scss file, CodeKit will look for "someFile.sass" and "someFile.scss" in the specified location (starting with the extension that matches the base file's extension). If neither file exists, it will then look for "_someFile.sass" and "_someFile.scss". If those also don't exist, it will go check all Framework folders for all four variations of the filename, in the same order. Note: if you have two files with identical names but different extensions (e.g. "_base.sass" and "_base.scss") and the @import statement does not specify an extension, CodeKit will link to the one that matches the extension of the base file.

Javascript & CoffeeScript Imports

CodeKit allows you to combine Javascript files and CoffeeScript files. For example, you can include jQuery at the beginning of your custom script instead of placing a separate script tag in your page's HEAD element. This reduces http requests and speeds up site load times.

CodeKit allows you to prepend and append script files. That is, you can add one file to the beginning or end of another (and you can keep doing that to create chains of files). The app will then take all the files in the chain and write them, in order, to an output file that you can include in your page's HEAD element. CodeKit does NOT allow you to simply import a script file anywhere in the middle of another script file. Doing so would create spaghetti code and lead to things like variable collisions and other nasty bugs.

Drag & Drop

You can combine script files in two ways. The first of these is via drag-and-drop. Select a JS or CS file in CodeKit then, simply drag another JS or CS file into the "imports" table that appears in the black pane on the right side of the window. You can drag to rearrange the order of the files and choose whether they go at the end or the beginning of the base file.

@codekit Statements

You can also create links between files by using these two statements in the files themselves: @codekit-prepend "someFile.js" and @codekit-append "someFile.js". The path you provide can be relative (e.g. "../../someFile.js"). Note: you MUST comment out these lines because they are not valid Javascript. Don't worry, CodeKit will still detect them just fine.

Suppressing Errors

Suppose you have a file called myScript.js which relies on jQuery. You use CodeKit to prepend jQuery to this script, which produces an output file called myScript-ck.js. CodeKit checks this output file with JSHint and discovers about 1,900 issues in it — all from jQuery.js. Clearly you're not interested in those. You want to see errors for only the parts of the combined file that you wrote! To do that, simply find "myScript.js" in CodeKit and select it. In the right-most pane, look at the "imports" table. You'll see jQuery.js listed there. Right next to it is a checkbox marked "show errors". Uncheck that box and the problem is solved.

Things To Be Aware Of

When you're combining Javascript & CoffeeScript files, keep a close eye on variable scope and name collisions. If you define a global variable "X" in one script, then combine that script with another that also has a variable named "X", you might be in for trouble. To avoid issues like this, make sure each script is wrapped in a function or closure and that your variables are scoped appropriately. Write your scripts knowing that they'll all be in one big file.

You should NEVER re-minify scripts that have already been minified once. So when you use jQuery, download the UN-minified version of that script and prepend it to your own. Then let CodeKit minify the combined file; do NOT prepend the minified version of jQuery unless you don't plan to use CodeKit's minifier.

Live Browser-Reloading

CodeKit can reload just the CSS of a page without reloading the entire page itself whenever you save changes to a relevant file. This is called "injection" and it applies only to stylesheet files. If you change a script or a page itself, CodeKit will reload the entire page to capture those changes. By default, CodeKit reloads the active tab of every Safari and Chrome window that's open. You can change that behavior in the preferences window. Note: CodeKit will not refresh browsers more often than once every two seconds. Do not save a file more frequently than that.

Browser-reloading is currently limited to Safari, Chrome, WebKit Nightlies and Chrome Canary. Firefox and Opera are not supported because they lack scripting interfaces. I am investigating some workarounds. If you want auto-reloads in the iPhone simulator, for now I recommend using Live.js.

Fixing Problems

THE leading cause of problems with live reloads are browser extensions. Not all of them deal well with the CSS-injection that CodeKit performs — especially extensions that modify the DOM. If you see slowdowns in your browser, crashes, hangs, or other nonsense, start by disabling extensions until you find the one that's causing the problem.

If that doesn't fix the problem, examine the scripts that you're including in the page. If there are any that manipulate the contents of the HEAD element (such as scripts that dynamically load other CSS files into the page), they might be conflicting with the way CodeKit injects changes. Try removing any such scripts and see if that solves the problem.

Compass

CodeKit will automatically detect Compass projects if a Compass configuration file is included in one of the standard locations within the project's folder. You can also manually enable Compass by right-clicking on the project and choosing "Compass > Use Compass on this project." Note: your Compass project must have a configuration file in order to work with CodeKit. Finally, you may create a completely new Compass project by using the command in the File menu or by clicking the gear icon in the lower left corner of the window.

When you use Compass for a project, you may also use CodeKit Frameworks. This is new in version 1.3+ of CodeKit. However, you must control all options for compiling Sass/Scss files by editing your Compass config.rb file rather than using the Inspector in CodeKit.

Compass Frameworks & Extensions

If you install Compass extensions by adding a load/require statement to the beginning of your project's config.rb file, you must switch CodeKit to use an external Compass compiler in order for that extension to work correctly. Do this by installing Compass at the command line as normal (if you're using RVM, make SURE you switch it to the standard system location first!) and then go to the Languages pane of CodeKit's preferences window, select "Compass" and see the "Advanced Compiler Settings" area.

Bourbon

CodeKit will automatically mark a project as using Bourbon if it finds an @import statement that contains the word "bourbon" as its last parameter. (E.g. @import "someFolder/bourbon";). You can disable this automatic detection in the Languages tab of the preferences window.

There is no need to install Bourbon's files into your project. CodeKit will just magically make Bourbon work. However, if you would like the Bourbon files in your project you can install them by right-clicking the project and then choosing "Bourbon > Install/Update Bourbon Files In This Project".

Git & Subversion Compatibility

You can safely commit changes while your project is in CodeKit. However, before you switch branches, merge or perform other actions you must uncheck the box next to the project in the CodeKit window. This will tell CodeKit to ignore all changes to all files in that project. Once you're done with source control actions, simply re-check the box and continue working. CodeKit will instantly rescan the project so that it's up to date.

Why Is This Necessary?

When you switch branches, Git deletes, renames and changes files as required — exactly as if you had made some changes and then saved the file in your text editor. There is no way to tell that a certain change came from Git and not from you pressing "save" in TextMate. It all looks the same to the operating system (and thus CodeKit). This can cause problems if your Git action changes many files at once. CodeKit sees all those changes, tries to process things appropriately and then discovers that certain files it expected to exist are missing or, worse, change in the middle of processing. This can, in the worst cases, cause a crash. Therefore, it's important to uncheck the project before running source control commands that change your project's files.

File Encodings

CodeKit requires files to be encoded in UTF-8 format. Line separators must be either LF, CR or CRLF. If you're using Unicode newline separators, vertical tabs, or other non-traditional newline characters, things will go poorly. If this sounds like Greek to you, fear not: virtually everything on the planet uses LF (OS X), CR (DOS, OS 9), or CRLF (Windows).

MacVim Compatibility

If your editor is MacVim, you might find that CodeKit is not automatically compiling your files when you save them. To solve this issue, you must disable swap and backup files in .vimrc. Use set nobackup, set nowritebackup, and set noswapfile.

Java-Based Editors

If you use an editor that is written in Java, you may encounter problems. This is because Java apps do not modify files in the same way that native OS X apps do and CodeKit relies on the native behavior to detect changes correctly. Apple has officially deprecated Java support on OS X, so I don't worry about Java-based tools. There's nothing I can do to resolve the issues you may encounter and I highly recommend that you switch to fully-native OS X tools. Cross-platform apps usually suck anyway.

Using CodeKit on Remote Servers

Normally, CodeKit only works on local filesystems. This is because the app relies on low-level notifications from the OS X kernel to detect when files in your project change. If those files are on a remote server, the OS X kernel isn't responsible for them and won't tell CodeKit when they change. HOWEVER, you can use Fuse For OS X to "mount" a remote filesystem (such as an FTP server) in a way that WILL trigger CodeKit. I haven't tried this myself, but if you're adventurous and want to write up a tutorial for other folks to use, I'd be happy to hear from you!

How CodeKit Detects Changes

There are two ways to determine when files change in OS X. The first is polling: you simply look at the modification date of the file every so often (perhaps once per second) and, if it's different, you know the file changed. This is how lots of other tools out there work. But when you start polling lots of files, you quickly chew up lots of CPU cycles. End result: a slower Mac. That's why CodeKit does absolutely zero polling. Instead, the app uses a very low-level feature of the OS X kernel, which among other things, handles file reads and writes. The app essentially tells the kernel, "Hey, anytime you do something to this file, let me know." This allows CodeKit to monitor changes without using a single extra CPU cycle. I have open-sourced the engine that CodeKit uses to watch files. You can find it here: VDKQueue