Anatomy of a project

• Directories and files
• Grunt configuration
• Extensions to package.json
  • Naming and defaults
  • Dependencies to native modules

Directories and files

A titaniumified project has at least the following files:

my-awesome-thing
├── Gruntfile.js
├── package.json
└── index.js

Grunt configuration

Titaniumifier doesn’t actually require a task runner to be used, you can in fact use the titaniumifier CLI. Nonetheless you’re highly encouraged to use Grunt, at least place a build.sh file somewhere so contributors know how to build the thing! 😄

Please have a look at Grunt’s documentation to understand how to use it.

Simply put, the Gruntfile.js you’ll have in your project root defines the tasks and the order they need to be run to accomplish a specific goal, such as building your titaniumified package or running your test Titanium application.

The part relevant to us is this:

grunt.initConfig({
  // here starts our configuration
  "titaniumifier": {
    // this is an arbitrary name
      "module": {
        // The package is in "." and the zipfile will be written in "./dist"       
        src: ".",
        dest: "./dist"      
      }    
  }
});
grunt.loadNpmTasks('grunt-titaniumifier');

There’s not a lot to be configured because most of the work is done by the package.json file.

Extensions to package.json

The package.json is the location for all the required metadata of the package. Titaniumifier extends the original fields set. The following is an example that uses all the available fields that are relevant to titaniumifier. Execute npm help package.json to have a better explanation of the standard fields.

(friendly reminder: JSON does not support comments!)

{

  // Meta
  // ----

  // name when distributed through npm or required by node (required)
  "name": "my-awesome-thing",
  // semver-compliant (required)
  "version": "1.0.0",
  // description for both npm and gitTio (recommended)
  "description": "Blah blah blah",
  // the main entry point
  // (optional, defaults to "./index.js")
  "main": "./path/to/index.js",
  // titanium-related information
  "titaniumManifest": {
    // a ‘title’ to be used e.g. in gitTio
    // (optional, defaults to `package.json#name`)
    "name": "My Awesome Thing",
    // name when required in Titanium or distributed through gitTio
    // (optional, defaults to `package.json#name`)
    "moduleid": "it.smc.myawesomething",
    // a unique id, titaniumifier can propose one for you (required)
    "guid": "xxxx-xxxx-xxxxxx-xxxxx-xxxx"
  },

  // Dependencies found on gitTio
  // ----------------------------

  // I need ... on Titanium side in order to work (optional)
  "nativeDependencies": { },

  // Dependencies found on npm
  // -------------------------

  // I need ... in order to work (optional)
  "dependencies": { },
  // I work with ... (optional)
  "peerDependencies": { },
  // I need ... to be built/tested (optional)
  "devDependencies": { },

  // “Re-wired” Dependencies
  // -----------------------

  // In the browser and Titanium SDK env instead of ... use ... (optional)
  "browser": { },
  // Only in the Titanium SDK env instead of ... use ... (optional)
  "titanium": { }
}

Naming and defaults

• Both titaniumManifest.name and titaniumManifest.moduleid defaults to name.

• The moduleid will be used in the name of the resulting zipfile. The previous example would generate a zipfile named it.smc.myawesomething-commonjs-1.0.0.zip.

  When requiring the module in Node.js or in a titaniumified package you’d need to do this:

  var myAwesomeThing = require('my-awesome-thing');

  but in Titanium SDK you’d need:

  var myAwesomeThing = require('it.smc.myawesomething');

• titaniumManifest.guid is required, but you can just write it in the root level for legibility when you don’t need titaniumManifest.name nor titaniumManifest.moduleid.

  The following is in fact a valid package.json:

  {
    "name": "my-awesome-thing",
    "version": "1.0.0",
    "guid": "xxxx-xxxx-xxxxxx-xxxxx-xxxx"
  }

Dependencies to native modules

The field nativeDependencies can be used exactly like the other *Dependencies fields, with the form { "module name": "version range" } but works with Titanium SDK modules.

You can for example declare a dependency over @mpociot’s TiCircularProgress like this:

{
  // ...
  "nativeDependencies": {
    "de.marcelpociot.circularprogress": "1.0.0" // specific version
  }
}

When your module will be installed through gitTio all dependencies present will be installed too.