Sass is what CSS should be. It adds variables, nesting, mixins and more to regular CSS.
CodeKit compiles Sass files into CSS files.
First, make sure you've read Setting Language Options.
To set options for all Sass files in a project simultaneously, open Project Settings > Sass. To change options for just one file, select it and use the inspector pane shown above.
CodeKit supports two Sass compilers: Dart Sass and Libsass. Dart Sass is the official compiler and supports new features first. Libsass is slightly faster, but takes longer to adopt new features.
Why two? The official Sass compiler used to be written in Ruby, which was godawful slow. Libsass rewrote the compiler in C++ to solve that. Years later, the Sass folks dropped Ruby and moved to Dart, which is pretty quick. For backwards-compatibility, CodeKit makes both compilers available.
Choose Compressed for the smallest CSS files. The other options produce pretty-printed CSS, but you won't need that if you use source maps.
Note: Dart Sass supports only "compressed" and "expanded". If you choose one of the other styles and use Dart Sass, the closest match is used automatically.
If your compiled CSS contains non-ASCII text (characters that don't fit into one byte), this option will add a @charset declaration to the beginning of the CSS file to help browsers decode them correctly. It defaults to ON.
Note: this setting has no effect if you're using Libsass.
Autoprefixer & Bless
For details, read Autoprefixer and Bless.
Purge Unused CSS
This reduces the size of your CSS files by removing unused rules. You can set this tool to run always or only in a specific Build Environment. For details, see PurgeCSS.
Minify With CSSO
CSSO restructures and optimizes CSS to reduce file size. You can set this tool to run always or only in a specific Build Environment. For details, see CSSO.
This places a *.map file next to the compiled CSS. Browsers use this file to show you the original Sass code in the web inspector instead of the compiled CSS.
Output Path & Action
These options apply to files of all types. They are explained in Setting Output Paths & Actions.
Sass files can import other files. To see these relationships, click the Linked Files tab:
At the top, this pane shows all files that your selected Sass file imports. Below that are all the files that import the one you have selected. If you see [FW] after the filename, that file is part of a CodeKit Framework
The _Partial Convention
If a filename starts with an underscore, CodeKit automatically sets the Output Action for that file to Ignore. These files are known as "partials"; they are meant to be imported into other files rather than compiled on their own.
Sass has a new module system that replaces @import with a new @use directive. CodeKit fully supports Sass modules when you use the Dart Sass compiler.
If you're migrating from @import statements, there are a few changes:
- Each @use directive can target exactly one file. Comma-separated lists are no longer supported.
- The filename in the @use directive must be wrapped in quotes, even when using the indented syntax (*.sass).
- Although @import will eventually be removed in a future version of Sass, you can currently mix-and-match that directive with the new @use.
Note: This feature is available only when using the Libsass compiler.
CodeKit supports Sass "import globbing". If you write @import 'someFolder/*', all Sass files in someFolder will be imported in alphabetical order. You can also use multi-level globbing such as folder/**/*, which imports all Sass files in 'folder' and in any subfolders thereof.
For the time being, globbing is NOT suppported for @use or @forward statements, or when using the Dart Sass compiler.
Warning: Variables in Import Statements
Sass allows you to use variables in @import statements. However, doing so makes it impossible for CodeKit to determine links between your files. The variable is not resolved until the file is actually compiled and CodeKit does not compile while scanning for @import statements because that would be slow.
If you use variables in import statements, your file will still compile just fine. But "dependent" files won't. Normally, if File 1 imports File 2, when you save File 2, CodeKit will go compile File 1 because an imported file has changed. When you use variables in import statements, CodeKit won't be aware of the link between these files.
Ambiguous Import Resolution Order
Sass allows you to import files without specifying the exact filename on disk. Suppose you have this Sass file:
// "file.scss" on disk at /folder @use 'foo';
To find the file that matches foo, CodeKit tries these paths, in order:
If no matching file is found, the app then checks each CodeKit Framework folder you have added, following the same ten steps. Note that the base file's extension (*.sass or *.scss) is always tried first.
As of April 2020, there are slight edge-case differences between Dart Sass and Libsass when resolving imports. You should not run into them, however.