Modular-Starter

Application starter with RequireJS. Performs the following:

• Clean Target directory
• Copy source directory
• Copy node_modules listed as 'dependencies' into Target directory
• Creates main.js if one isn't present (basic app startup)
• Generates RequireJS configuration from config in package.json
• Provides functionality to Optimize with RequireJS and Uglify
• Provides easy setup of gulp tasks from package.json
• Provides modularization for your gulptasks into a tasks folder

Usage

1. Pull in Modular-Starter via package.json devDependencies
2. Include the Modular-Starter gulpfile into yours: require('node_modules/modular-starter/gulpfile.js');
3. Ensure correct project folder structure
4. Enjoy (see Tasks)

See Example folder for basic example project.

Expected directory structure

???{project}/
   ??? package.json
   ??? node_modules/
   ?   ??? modular-starter/
   ??? src/
       ??? vendor
       ??? App.js (if using provided main.js)

Output will be as follows

???{project}/
   ??? target/
       ??? vendor/
       ??? main.js
       ??? App.js (if using provided main.js)

Tasks

provided

Task	Description
default	Runs the first configured build task from config (see next table)
watch	Watches all files in the source directory and runs 'default' on changes
clean	Cleans the target directory
copy	Grouping task for all 'copy:' tasks below
copy:node_modules	Copies all modules found in package.json --> dependencies into the target directory with other vendor files
copy:source	Copies the entire source directory to the target directory
copy:main	If no main.js was found, this will copy a basic implementation in
requireJS-config	Generates the configuration for RequireJS at runtime
requireJS-build	Optimization using r.js to minify all modules together
uglify	Uglifies all files found in the target directory, excluding the vendor folder

User Defined

In package.json, define a "build-tasks" entry object. The key will be the task name and the value should be an object of configuration you wish to send in. The basic implementation looks for minify and uglify to add those tasks to the base sequence.

Base sequence is ['clean', 'copy', 'requireJS-config']

Examples in this package.json are:

// Dev build - no minification or uglification
"dev" : {},

// Test platform - minify for performance but still easily debuggable
"test" : {
  "minify" : true
},

// Integration platform - build like production to ensure no issues with minified and uglified code
"integration" : {
  "minify" : true,
  "uglify" : true
},

// Production - full performance build - minify and uglify
"prod" : {
  "minify" : true,
  "uglify" : true
}

Minify and Uglify in this case add tasks onto the end of the base sequence. In the case of needing to run your own tasks, you can provide more options:

"myBuildTask" : {
    "seq" : ["clean", "myInternalTask", "copy", "requireJS-config", "reconCheck", "cleanup"],
    "myConfig" : true,
    "myOtherConfig" : "Value here"
}

In this example, 'myBuildTask' will be available and run it's own custom sequence of tasks. This one mixes in modular-starter tasks with custom defined tasks. Also any attributes added into the build task entry can be retrieved within tasks by the global 'CONFIG' object. In this case console.log(CONFIG.myConfig); // true

Configuration - package.json

The package.json of this library provides the base example. Copy requireJS-config, requireJS-build, and config to your package.json if you need to make modifications.

requireJS-config

This defines the runtime configuration of requireJS, used in the task with the matching name. Note that paths should be set up relative to 'vendor' directory. Example:

"requireJS-config" : {
    "baseUrl" : ".",
    "paths"   : {
        // All of these will point to {target}/{vendor}/...
        "jquery"      : "jquery/dist/jquery",
        "underscore"  : "underscore/underscore",
        "someLibrary" : "libraryFolder/someLibraryModule"
    },
    "shims" : {}
}

requireJS-build

Defines the optimizer configurations.

"requireJS-build" : {
    // Don't clear target due to other files being built into there
    "keepBuildDir"          : true,   
    
    // Turn off semi-uglification - let uglify do this, making minification legible
    "optimize"              : "none", 
    
    // Since this operates purely in the target directory, allow it to overwrite files
    "allowSourceOverwrites" : true,   
    "baseUrl"               : ".",
    
    // Look for source files in target, due to some files being dynamically created
    "appDir"                : "./target", 
    "dir"                   : "./target",
    "modules"               : [
        // Add modules to be compiled together
        // main module should always be here - optionally you can include other modules into it or exclude some
        {
            "name"    : "main",
            "include" : ["App"]
        }
    ]
}

config

Currently only used to specify directories so this can be customized for your project naming conventions.

"config" : {
    "dirs" : {
        // {project}/{tasks}/*.js for modularization of your tasks
        "tasks"   : "tasks",   
        
        // {project}/{source}/**/* for all your source code
        "source"  : "src",     
        
        // {project}/{source}/{plugins}/*.js for all your third party library plugin extensions
        "plugins" : "plugins", 
        
        // {project}/{target} output of the build process
        "target"  : "target",
        
        // {project/{source|taget}/{vendor} for all third party libraries
        // node_modules listed as 'dependencies' will be copied and merged with {source}/{vendor} folders into {target}
        "vendor"  : "vendor"
    }
}