Publishing Packages

How to Share a Package

All Kanso modules are shareable packages.

Make sure your kanso.json file includes a name, version, and description. If your module has any dependencies, include those too.

// kanso.json
{
  "name": "couchtypes-widgets-multicheck",
  "version": "0.0.1",
  "description": "A widget for selecting more than one checkbox in a form",
  "modules": "couchtypes",
  "dependencies": {
    "couchtypes": null,
    "modules": null
  }
}

Create an account at kan.so. You'll use these credentials when you publish.

Run kanso publish from your terminal. It will prompt you for your username and password. Once you're authenticated, your package is compressed and uploaded.

You'll see your newly published package on the packages page.

Useful Notes

• You can find a minimal example of a shared package here.
• When you're testing a module before you share it, you'll probably kanso install its dependencies. Make sure you remove the packages directory before you publish. The entire contents of your module directory will be published, and the packages folder is unnecessary. When your module is required in a project its dependencies will be dowloaded when kanso install is run.

Naming Conventions

• Dashes are preferred over spaces, dots, and underscores in module names. For example couchtypes-duality instead of couchtypes duality, couchtypes.duality, or couchtypes_duality
• If you are extending a module, your package name should begin with the name of the module you are extending. For example couchtypes-duality is an extention of couchtypes.

READMEs

It's highly recommended you add a README for your package. This works a bit like READMEs on GitHub. Simply add a README file to your package directory before publishing. The text in this file will be displayed on your package page.

You can add formatting to your README by using markdown. You must name the file README.md when using markdown, and embedded HTML is forbidden. Avoid using a H1 since the main title is your package name and already rendered on the page.

Upstream Dependencies

If your Kanso package is using an existing library you can make it clear what upstream package you are including by defining the kanso.json version like so:

{
    "name": "less-precompiler",
    "version": "1.2.1-kanso.1",
    "url": "http://github.com/kanso/less-precompiler",
    "categories": ["build-tools"],
    "description": "Precompiles .less CSS templates when building a package and attaches a compiled .css file to reduce parsing time in the browser",
    "preprocessors": {
        "compile": "build/compile",
        "remove_attachments": "build/remove_attachments"
    }
}

See the less-precompiler for a complete example.

Something to be aware of is that 1.2.1 would currently rank higher than 1.2.1-kanso.1 when installing the latest version, so you have to be consistent with adding the suffix. I'm not sure if this is intended behaviour for semantic versioning (http://semver.org/) or not. Also, the '.' between the -kanso and the number are important to help the semver parser to sort '-kanso.1', '-kanso.2' and '-kanso.10' properly.