Manage modules as npm packages - EugeneN/cafe GitHub Wiki

Cafe provides possibility to include npm packages in recipe, and work with them as with the other modules. To do this you only need to specify npm prefix in module path in modules declaration.

Including npm module

1. Let's create empty project cafe init
2. Let's assume that we want to use jqueryify module in our project. Open cs/recipe.yaml file and add a new module:

abstract: 
    api_version: 5

modules:
    - jquery:                   # <-- Step1 registering new module. 
        path: npm://jqueryify   # signature - "npm://<npm module name>[@version]"


bundles:
    default_bundle:
        modules:
            - jquery           # <-- Step2 adding jquery to bundle

3. Run cafe menu build and thats it, cafe will do the rest of work for you. After build you will be able to require 'jqueryify' from your application files. For now you can open init.html file in browser and test require in console.

You may declare jquery module in more pretty and compact way:

modules:
    - jquery: npm://jqueryify

How it works

When cafe meet's path with npm prefix it installs it, resolves all modules dependencies by require calls inside the npm package. For now there is only one requirement for normal processing of npm module - package.json must have the main file section. This is an entry point for cafe for analyzing and resolving files from package. Cafe doesn't include all files in npm package, because except of source files there may be some fixtures, tests, extension files e.t.c. But cafe allows you to specify files inside of some package to be included anyway.

Include unresolved files

Npm package may have some files that may not be resolved by cafe, because actually they are not required inside package. Let's look at example:

1. Let's assume we want to use spine framework in our project, so let's add it to the recipe from the previous example:

abstract: 
    api_version: 5


modules:
    - jquery: npm://jqueryify
    - spine: npm://spine      # <--- Step1 adding new module with reference to the npm package.


bundles:
    default_bundle:
        modules:
            - jquery
            - spine           # <--- Step2 adding module to bundle 

2. Run cafe menu build and now we have spine framework included in our page script.But not all files from spine lib were included(to see what modules were registered you may check bootstrapper.modules varriable in browser console), because there is some additional library files that are not required inside spine, and aren't necessary for spine to get worked.
3. So for now, to include routing extension - we must add some meta to spine module in recipe file:

abstract: 
    api_version: 5


modules:
    - jquery: npm://jqueryify
    - spine: 
        path: npm://spine
        include: [lib/route.js]   # <-- Adding include section, with paths relative to spine module root.


bundles:
    default_bundle:
        modules:
            - jquery
            - spine

After that you can run cafe menu build and check require('spine/lib/route') in your browser. Routing extension must be activated in spine.