A simple, streamlined way to combine, compress, and cache web files

Fork me on GitHub Download cinch 0.8

Cinch is a PHP package manager that allows developers to minify and combine all of their Javascript & CSS files, reducing file sizes and making web pages load faster—automatically.


Good to Developers

Pre-Processor Handling

Automatically converts JS and CSS pre-processor formats such as Sass, SCSS, Less and CoffeeScript. Plus, with the use of Javier Marín's css_optimizer, dealing with pesky CSS annoyances like vendor prefixes are a thing of the past.

Live Reload

Cinch checks the status of your web files and automatically loads new styles and scripts when a change is detected.

Built-In Bower Support

Built-in access to thousands of software libraries and packages such as jQuery, Prototype, Bootstrap and a bunch more, all available automatically. See the entire list at Bower.

Good to Servers

Light-Weight and Fast

Don’t need minification? Only using .less files? Cinch loads only the dependencies you need, keeping server load small and speeding up execution times.

Smart Cacheing

Cinch creates a static version of your combined JS/CSS files anytime changes have been detected in your site’s files, which it will serve to users until new changes are made.

Efficient Headers

If the user already has the latest version of your files, ‘304 Not Modified’ headers are sent to the user instead of sending the site files again.

Good to Users


Cinch combines all of your JS and CSS files into just one file. This reduces the number of HTTP requests your users' browser will need to make, speeding up your site and making scripts run more consistently.


Minifying files gets rid of all unnecessary white space and comments in your files, decreasing the amount of bandwidth and time needed to download them.

GZIP Compression

Cinch uses gzip when available to compress files even further before sending them to your users.

How to Use Cinch

  1. Upload cinch to the root folder of your site
  2. Replace the links in your <script> and <link> tags with a URL that points to your ‘cinch’ folder
<script src="/js/jquery.min.js" type="text/javascript"></script>
<script src="/js/functions.js" type="text/javascript"></script>
<script src="/js/scripts.js" type="text/javascript"></script>

looks like this in cinch:

<script src="/cinch/?files=/js/jquery.min.js,/js/functions.js,/js/scripts.js" type="text/javascript"></script>

More Examples

All settings can be applied to any group of files. Settings can be adjusted by adding them to the query string in a <script> or <link> tag, separated by ampersands (&), as shown below.

<script src="/cinch/?files=[jquery],/js/ajax.js&min=false&debug=false" type="text/javascript"></script>
list of .JS files
include jQuery from an external library
turn off minification
turn off debug output
<link href="/cinch/?files=[normalize],!/css/layout.less,/css/text.scss&force=true" type="text/css">
list of .CSS files
use ‘!’ to disable minification on a specific file
it's ok to mix different file types
force cinch to rebuild cache every time


All settings work for both JS and CSS type files. Values marked in orange are the default value for that setting and will be used if no other value is given.

Also worth noting, default settings can be changed by editing the $defaults variable in cinch/config.php.


files=(comma-separated file list)

A list of JS or CSS files to include.

NOTE: Files should contain relative path from site root to the files being listed (eg. /js/scripts.js).



To disable minification on an individual file, simply add ‘!’ to the beginning of that file’s path.


In this example, ‘scripts.js’ will be minified, but ‘plugin.min.js’ will not.


To include an external package, enclose the name of the package and the version number (optional) in a pair of square brackets, separated by a forward slash(/). If no version is given, the most recent version of the package will be used.

A full list of Bower packages can be found on the Bower website.

src="/cinch/?files=[jquery/1.10.2]" src="/cinch/?files=[normalize]"


Settings can be adjusted by adding them to the query string in a <script> or <link> tag, separated by an ampersand (&).

*Values marked with a star (*) are the default and will be used if no value is given.


Indicates the type of files being sent to cinch. When set to auto, cinch will do it’s best to automatically detect which type of files are being used, based on the extension of the first file in the list.


Forces 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.


Adjusts minification/obfuscation settings on web files.

NOTE: Files marked with an exclamation mark (!) will not be minified regardless of this setting’s value.

NOTE: The 'pack' setting minifies and obfuscates files. This setting applies only to javascript files. Standard minification will be applied to CSS files if this setting is used.


When enabled, debug information (such as filenames and errors) are displayed at the top of the output files. Otherwise, errors are ignored and all extra annotations are hidden.


Automatically checks for changes to your web files and reloads those files if a new version is found.

NOTE: Since this setting is javascript-based, live reloading requires that cinch process at least one link to javascript.

NOTE: This setting can only be enabled on a javascript link, not CSS.

Production Mode

Once development has completed on a site, it is highly recommended that you enable 'Production Mode' within cinch. Production Mode allows developers to disable the creation of new cache files and prevents cinch from clearing old cache files. This has two major effects:

1. Reduces server load (as this mode bypasses most of cinch's code and loads directly from cache)
2. Increases security (by preventing unwanted scripts from being created on the server)

To enable Production Mode, open cinch/config.php and change the the define('PRODUCTION', false); to define('PRODUCTION', true);


  • 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 JS/CSS 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/config.php file if you want to protect your cache folder.

  • How do I link to a package that has both CSS and JS files?

    In cases, like Bootstrap, that have both CSS and javascript components, just include the package in both your CSS and JS links. Cinch will automatically separate the files into the correct types. If cinch isn't properly detecting which file type you are trying to use, add the type=css or type=js properties to your file links.

  • I get an error whenever I try to link to an external package. What can I do?

    Some servers are configured to not allow the downloading of files on remote servers, which is what cinch does to load package files. Fortunately, there is an easy workaround: Just copy the files you need to your server and link to them directly with cinch.
    For example, ?files=[jquery] becomes ?files=/js/jquery.min.js.

  • 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 for you.

Other Notes and Goodies

  • If you want to speed up performance and prevent new cache files from being created on your server, enable Production Mode in cinch. 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 or when refreshing the site in a browser.
  • 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.