Safely declare namespaces and set their properties


declare plugin for gulp 3

First, install gulp-declare as a development dependency:

npm install --save-dev gulp-declare

Then, add it to your gulpfile.js:

var declare = require('gulp-declare');
var concat = require('gulp-concat');
gulp.task('models', function() {
  // Define each model as a property of a namespace according to its filename 
      namespace: 'MyApp.models',
      noRedeclare: true // Avoid duplicate declarations 
    .pipe(concat('models.js')) // Combine into a single file 

Type: String
Default: "this"

The namespace in which the file contents will be assigned. Use dot notation (e.g. MyApp.templates) for nested namespaces.

For example, if the namespace is MyApp.templates and a file is named App.Header.js, the following declaration will be added:

this["MyApp"] = this["MyApp"] || {};
this["MyApp"]["templates"] = this["MyApp"]["templates"] || {};
this["MyApp"]["templates"]["App"] = this["MyApp"]["templates"]["App"] || {};
this["MyApp"]["templates"]["App"]["Header"] = /* File contents from App.Header.js */;

If the default value of "this" is provided, namespace declaration will be determined soley by the filename and output of options.processName. That is, a file names MyApp.templates.App.Header.js will result in the same declaration as above.

Type: Function
Default: Strip file extension

This option accepts a function which takes one argument (the path to the file) and returns a string which will be used as the key for object. By default, the filename minus the extension is used.

This function should return a namespace path in dot notation, such as Prop.sub.item, which is then combined with options.namespace. See options.namespace above for an example.

See declare.processNameByPath to generate namespace paths based on directory structure.

Type: String
Default: \n

The separator to use between declarations.

Type: Boolean
Default: false

If true, parts of the namespace that were declared as a result of previous files in the stream will not be redeclared. For instance, if the stream contains the following files:

  • Main.Content.js
  • Main.Header.js
  • Main.Footer.js

And if declare is invoked with { namespace: 'MyApp', noRedeclare: true }, the contents of the streamed files will look like this:


this["MyApp"] = this["MyApp"] || {};
this["MyApp"]["Main"] = this["MyApp"]["Main"] || {};
this["MyApp"]["Main"]["Content"] = /* File contents from Main.Content.js */;


this["MyApp"]["Main"]["Header"] = /* File contents from Main.Header.js */;


this["MyApp"]["Main"]["Footer"] = /* File contents from Main.Footer.js */;

This option makes the most sense when you're concatenating files later and want to minimize duplicate declarations. Regardless of this option, gulp-declare will never clobber existing namespaces or their properties.

Type: String
Default: this

The root object to declare the namespace within. Defaults to this (which is equal to window in the browser).

This option is prepended to the assignment statement, so special characters or operators such as - should be avoided as they will result in an invalid left-hand assignment error.

When using Node or Browserify, you can specify root: 'module.exports' with no namespace if you would like to assign as properties of an exported module:

    root: 'module.exports', // Declare as properties of module.exports 
    noRedeclare: true // Avoid duplicate declarations 

Which results in the following templates.js:

module.exports["App"] = module.exports["App"] || {};
module.exports["App"]["Main"] = /* File contents from App.Main.js */;
module.exports["App"]["Header"] = /* File contents from App.Header.js */;
module.exports["App"]["Footer"] = /* File contents from App.Footer.js */;

Pass this method as options.processName so the path within the namespace matches the path in the filesystem combined with dot notation from the filename:

  .pipe(domly()) // Compile HTML to document fragment builder functions 
    namespace: 'NS', // Use NS as the base namespace 
    noRedeclare: true, // Avoid duplicate declarations 
    processName: declare.processNameByPath // Include the path as part of the sub-namespace 

The above configuration will result in the following mapping:

File pathNamespace path

Note: In the above example, NS.templates.App.header is a function that is stored as a property of the NS.templates.App function. As everything in JavaScript is an object, even functions, this is perfectly valid and works in all environments. If this hurts your brain, store templates/App.hbs as templates/App/main.hbs and access it as NS.templates.App.main.

If you want to remove or change part of the path, you can define your own options.processName and use declare.processNameByPath() within it. The following example results in the same namespace paths as above with a different directory structure:

  .pipe(domly()) // Compile HTML to document fragment builder functions 
    namespace: 'NS.templates', // Declare within NS.templates 
    noRedeclare: true, // Avoid duplicate declarations 
    processNamefunction(filePath) {
      // Drop the client/templates/ folder from the namespace path 
      return declare.processNameByPath(filePath.replace('client/templates/', ''));