thedod edited this page Sep 4, 2012 · 10 revisions
Clone this wiki locally

Kanso's "getting started" - the next generation :)

Kanso is a tool for building couchapps. A bit like the couchapp command line tool, but instead of treating the content of the project folder as data to be transformed into json+attachments and pushed to the server, it treats the folder as a javascript project that builds the couchapp to be pushed. This enables the build process to include pre/post processing steps like minify/uglify, less compilation, etc.

Does it mean you have to write additional code in order to create a couchapp? Quite the opposite: a Kanso project can include packages that both provide the "payload" to be pushed to the couchdb server and the code that prepares it to be pushes according to the package's needs:

When you include the db package in the packages/ folder, you can use require('db') in server side code, and when you include bootstrap, your less files get compiled into css, and get pushed as file attachments your browser side code can use.

It gets even better: you don't even need to include the packages/ folder in your project's repository (although some people believe you should). It's enough to declare a package as a dependency, and the kanso install command will fetch the package automatically. So theoretically - you can have packages in your .gitignore file and keep a really small repository.

For example, if your kanso.json is

    "attachments": ["index.html","static"],
    "dependencies": {
        "attachments": null,

then kanso install will create or update [if needed] the folder packages/attachments/ because of the "attachments": null (the null means latest version). During kanso push, this package would find the "attachments": ["index.html","static"] parameter and push the file and folder to the couchdb.

###Getting started

Documentation is still in the making, so many times it's "use the source - luke" (packages without a README file are quite common), so here's the way I recommend to do it:

###Getting stopped

At this point, you already have a simple app, but IMHO it's a bit too simple. In order to continue and play with users, permissions, types, etc. you need a couchapp that has a view, a show, and a list.

###Getting around this

I've decided to take the "getting started" example a step further and bring it to a stage where it "does something". I'll continue updating it as I go along, install new packages, etc. but I'll try to do it in small tutorial-like steps.

The master branch doesn't even have a template engine or rewrite rules. It does have bootstrap, though. It was so easy I couldn't resist it :)

Next, there's the dust branch (demo) that uses the dust template engine. IMHO, dust is the best choice, but feel free to fork from master and try this example with some other engine. At least you have a project to start from.

This is where I got so far. I'll continue adding packages and features to this app, but each small step will be a new branch, so that:

  • At each step I (or you) can fork and experiment with alternative options

  • All this can hopefully become a step by step tutorial later on