A simple, streamlined way to combine, compress, and cache web files.
Cinch allows developers to automatically handle JS/CSS compression and concatenization (combining multiple files into one), reducing file sizes and page load times. There's virtually no installation process; simply change your JS/CSS links to point to Cinch with a list of the files you want to load and it will do the rest.
Furthermore, it's perfect for both development and production environments. Cinch will look for new changes to your JS/CSS files, and if it finds any it will quickly build a static cache file to send to your users.
- Automatic minification of JS/CSS, which removes unnecessary spaces and comments
- Converts common pre-processor formats (LESS, SCSS, SASS, and CoffeeScript) into standard CSS/JS automatically
- Combines multiple files into one file to reduce HTTP connections between the server and your users
- Caches files on server if no new changes have been detected to the source files
- Built-in access to tons of common libraries, frameworks and software packages, such as jQuery, Angular, Bootstrap, and more available through the Bower package manager.
- Live Reload refreshes styles and scripts in your browser automatically when changes are detected to your web files
- Serves '304 Not Mofidified' headers to users if the user already has the latest code in the browser's cache
- Uses gzip to further compress output files when available
- Adds CSS vendor prefixes automatically, along with a bunch of CSS enhancements
- Bourbon mixins included and automatically added to any Sass files
Just upload the 'cinch' folder to the root folder of your site, and replace all of your
<link> tags in your HTML with just one tag that links to all of your JS/CSS files.
looks like this in cinch:
The next example will load up three CSS files (css/reset.css, css/layout.css, css/text.css), disable minification for reset.css (by adding the '!' to the file path for that file), and will force Cinch to create a new cache file on the server every time the page is reloaded.
<link type="text/css" media="all" href="/cinch/?files=!/css/reset.css,/css/layout.css,/css/text.css&force=true">
In order to use any of the setting below, just add them to the query string in the
<link> tag, separated by the '&' character. All settings work for both JS and CSS type files.
- files=(comma separated list of files) - List of JS or CSS files to include
NOTE: Files should contain relative path from site root to the files being listed (eg.
!(/path/to/filename) - To disable minification on individual files, simply add '!' to the beginning of that file's path in the comma separated list.
[bower-package-name(/version)] - To include an external library from the list below, enclose the name of the library and the version number(optional) in a pair of square brackets, separated by a forward slash (/). If no version is given, the latest version of the libary will be used.
A full list of Bower packages can be found on the Bower website.
Values marked with a star are the default and will be used if no value is given.
type=( js | css | auto )* - Indicate which type of files are being sent to Cinch
- css: Process files as CSS
- auto*: Cinch will do it's best to automatically detect which type of files are being used. This is based on the extension of the first file in the list.
force=( true | false )* - Force Cinch to rebuild the cache and update the user's browser with the newest code on every page load, even if no changes have been detected.
min=( true | false | pack )* - Enable/disable minification on files.
- NOTE: Files marked with a '!' in order to avoid minification will no be minified regardless of this setting's value.
debug=( true | false )* - When enabled, output files display errors. Otherwise, errors are ignored.
reload=( true | false ) - Automatically checks for changes to your web files and reloads those files if a new version is found.
- PHP 5+ - Core functionality (minification and concatenization)
- PHP 5.1? - Sass/SCSS Compiler (Just a guess as to which version is necessary)
- PHP 5.1+ - LESS Compiler
- PHP 5.3+ - CoffeeScript Compiler
Cinch isn't working. Why is that? There could be a lot of things causing cinch not to run properly on your site: invalid links to cinch or your web files, errors in your code, etc. If you're getting a 404 error on your cinch links, then make sure cinch is properly loaded on your server and your links are correct. If your site is loading cinch, then you can check the top of the output files to see if cinch ran into any bugs or errors. Debug output in cinch is enabled by default.
How do I upgrade to a newer version of cinch? Just overwrite the cinch folder with the new version! All of your dependencies will be automatically re-downloaded and all of your cache files will be rebuilt the next time you visit your page. After you've rebuilt your cache files, don't forget to set the 'PRODUCTION' constant at the top of the cinch/cinch.php file if you want to protect your cache folder.
I have so many cache files! Don't worry! This happens a lot as part of the development process. You can delete all of the files in your /cinch/cache folder and cinch will rebuild all of your cache files automatically. Or just wait a month and cinch's automatic clean-up scripts will delete old cache files.
Other Notes and Goodies
- If you want to speed up performance and prevent new cache files from being created on your server, simply set the PRODUCTION constant in cinch/cinch.php to TRUE. Production mode bypasses most of cinch's code to serve up the cached web files as quickly as possible. NOTE: New changes to any of the raw web files will not be reflected in the cache files.
- The Bourbon mixins library has been packaged with cinch, and will automatically be imported into your Sass files on execution. If you don't need them, no problem; the only extra bulk it will add to your stylesheets will be based on which mixins you use.
- CSS vendor prefixes are added automatically, along with smart CSS minification, color conversions, and more, thanks to Javier Marín's css_optimizer. No need to write 5 lines of CSS to accommodate each browser anymore.
- A separate cache file is created for each combination of JS/CSS files that you use, so that different pages with different requirements can still run as quickly as possible. In order to prevent this folder from being overloaded on a busy development server, the cache is automatically cleared about once a month.
Cinch is made with the help of: