Getting started

phun-ky edited this page Jan 25, 2013 · 11 revisions

Patsy is a staging and build environment for web developers. Why patsy?

Table of Contents

  1. Requirements
  2. Installation
  3. How to use
  4. How patsy works
  5. Preparing a patsy project
  6. package.json
  7. The patsy project configuration file
  8. Further reading


patsy requires Nodejs >= 0.8.0 and is built with these plugins:

  • Gruntjs
  • UglifyJS
  • Commander
  • etc.. ( Read full list in the package.json file under "dependencies" )

All of the dependencies are installed automatically when you install patsy.

⬆ Go to the TOC


If you have installed patsy globally in the past, you will need to remove it with npm uninstall -g patsy first.

In order to get started, you have to install the required version of NodeJS and then install patsy globally. You may need to use sudo (for OSX, *nix, BSD etc) or run your command shell as Administrator (for Windows) to do this.

npm install -g patsy

This will put the patsy command in your system path, allowing it to be run from any directory.

Preferably, if you use a package.json file for your project, you can type:

npm install -g patsy --save-dev

This will include patsy as a development dependency for your project. Read more about the package.json-file below

If you get the error "warn cannot run in wd" from npm, try to run it again with sudo npm install patsy --unsafe-perm

⬆ Go to the TOC

How to use

Go to the folder of where you have your web project, type patsy and enjoy! For more options and advanced usage, check out the Advanced usage page.

Note: You can list all available CLI commands with the command patsy -h.

Note2: If something fails, try to run patsy with patsy -v for detailed messages.

How patsy works

Each time patsy is run, it looks for a patsy configuration file called patsy.json in the folder you started patsy.

If a configuration file is found, patsy will run with that configuration. If not found, patsy will ask you a few questions to create a custom or default patsy configuration file for your project. If you hit enter ( Default action is marked in brackets as DEFAULT ), a default configuration file is saved.

[King Arthur]: Come Patsy, my trusty servant!! <sound of two half coconuts banging together> ..
[Patsy]: I'm very sorry my Liege, I can't find any configuration here.. Let's go to Camelot instead!
[King Arthur]: No! It's a silly, silly place! Stop that!
[Patsy]: Sire, do you want to create your own configuration script? Listen to the Allmighty God:
[God]: Well, do you? [y/n/DEFAULT] (enter for default config):

As depicted in the code above, answering y or yes will generated a patsy configuration file for your project after you have answered a few questions. Default values are presented in brackets:

[God]: Well, do you? [y/n/DEFAULT] (enter for default config): y
[God]: What is the projects name? [my_project]: MyProject
[God]: Where do you keep your JavaScript source files? [js/src/]:
[God]: Where do you want to save your minified files? [js/min/]:
[God]: Where do you want to save your documentation files? [js/docs/]:
[God]: Where do you keep your .less and .css files? [css/src/]:
[God]: Where do you want to save your compiled css files? [css/dist/]:
[God]: Where do you want to save your baked files? [js/dist/]:
[God]: I can currently offer you mustache compiling of templates, where is your *.mustache files? [js/mustache/]:
[God]: I will now create a scripture you can follow
[God]: Arthur, You may now continue with your quest!

When the questions are answered, patsy will start with that config. The config is saved in the directory you started patsy in.

⬆ Go to the TOC

Preparing a patsy project

A typical setup will involve adding one file to your project: patsy.json.

Further, if you want to publish your project, we recommend you to add a package.json file to your project for project information and dependency control. Read more about package.json here.

package.json: This file is used by [npm] to store metadata for projects published as npm modules. You will list patsy as [devDependencies] in this file.

The patsy project configuration file: This file is named patsy.json and is used by patsy to setup how patsy will run with your project.

⬆ Go to the TOC


The package.json file belongs in the root directory of your project, next to the patsy project configuration file, and should be committed with your project source. Running npm install in the same folder as a package.json file will install the correct version of each dependency listed within.

Example package.json setup

  • The [npm init] command will create a basic package.json file for you.
  • Start with the example below, and expand as needed, following this specification.
  "name": "my-project-name",
  "version": "0.1.0",
  "devDependencies": {
    "patsy": "~0.4.2"

⬆ Go to the TOC

The patsy project configuration file

The patsy.json-file is a valid JavaScript Object Notation file, placed in the root directory of your project—next to the package.json file—and should be committed with your project source. In the past, this file was named stage.JSON, and patsy will ignore this file. Be sure to delete it if you have it in your project folder.

The patsy configuration file is basically a file with JSON structure with key->value options. Read more about Configuration.

⬆ Go to the TOC

Further Reading

  • The Installing patsy guide has detailed information about installing specific, production or in-development, versions of patsy.

⬆ Go to the TOC