Nocturnal Practitioners of Magic

    ack-pug-bundler

    1.4.8 • Public • Published

    ack-pug-bundler

    Watch and bundle pug/jade files into .js files for importing into Javascript web-apps

    This package converts .pug and .jade files into .pug.js or .jade.js files and also comes with file watching functionality to compile template files, when changes occur to them.

    Table of Contents

    The intended use of this package, is to be used during front-end aka client-side code development where the bundling process is performed in NodeJs.

    Pre-Compiled Approach to Including Templates

    This package is built on the principle, that templates should be pre-compiled BEFORE any javascript bundling processes.

    Have you heard or used any of the following?

    • pug-loader or jade-loader
    • plugin-pug or plugin-jade

    The above mentioned packages, all compile pug/jade files DURING the js build process. This approach isn't always ideal and sometimes it is better to just have templates compiled into importable .js files BEFORE any script building process.

    TIP: ack-pug-bundler watch/build processes should run synchronous(before) any other watch/build processes that require the produced pug/jade .js compiled files.

    Recommended Installation

    This package is only needed during the development of another package, install for development use only

    $ npm install ack-pug-bundler --save-dev

    Functionality Overview

    Not examples, more like documentation on what does what

    var ackPug = require('ack-pug-bundler')
     
    //compile and write just one file
    ackPug.writeFile(pugFilePath[, (outputPath||options), options])
     
    //compile and write multiple files
    ackPug.crawlPath(pugFilePath[, (outputPath||options), options])
     
    //compile and write multiple files on file change events
    ackPug.watchPath(pugFilePath[, (outputPath||options), options])
    • @pugFilePath: read path source
    • @outputPath: file path to write to. default=pugFilePath
    • @options:
    {
      asJsonFile,//controls output as being just one json file (this should deprecate into outType=json)
      asOneFile,//controls output style and file name of single bundling mode. In most cases, asJsonFile, is the best way to go.
      outType:'ecma6',//string, common or ecma6
      outFileExt:'js',
      pretty:false//useful true when outType=string
    }

    CLI

    The following command will recursivily compile all .pug|.jade files into one templates.js

    ack-pug-bundler src/ src/templates.js

    Supported Commands

    • watch
      • specifies to watch files for changes and rerender at that time
    • outFileExt
      • default = js
      • override output file extension
      • not applicable when --oneHtmlFile or --oneFile
    • outType
      • determine flat html string OR import/export OR module.exports syntax
      • ecma6 || common || string || ts
        • ts mode will export const string
    • pretty
      • resulting html strings can maintain readability
    • oneToOne
      • when argument is present, in file names will be used to output file names
    • oneFile
      • a convenience option to simply output one pug to one output file
      • An .html file is converted to a string
      • An .md file is converted to html and then to a string
    • skipRender
      • indicates that file(s) being read are already compiled
    • oneHtmlFile
      • a convenience option to simply output one pug to one html file
    • includeHtmls
      • An option to bundle HTML files to js/ts file(s)
    • includeMarkdowns
      • An option to bundle Markdown files to js/ts file(s)

    Command Examples

    Open a command prompt terminal and execute the following commands

    Compile Htmls to Typescript files

    ack-pug-bundler src/htmls/ src/templates/ --oneToOne --includeHtmls --outType ts

    Extended Example

    ack-pug-bundler pugs/ templates/ --outType ts --oneToOne

    The above example will cast ./pugs/template.pug to ./templates/template.pug.ts

    ./templates/template.pug.ts : export const string = "..."

    File Ext Example

    ack-pug-bundler pugs/ templates/ --outFileExt .ts --outType ts --oneToOne

    The above example will cast ./pugs/template.pug to ./templates/template.ts

    ./templates/template.ts : export const string = "..."

    CLI Script Conveniences

    Recommended to include the following in your package.json scripts for your convenience

    "scripts":{
      "build:index": "ack-pug-bundler src/index.pug www/index.html --oneHtmlFile",
      "build:pug": "ack-pug-bundler src/pugs/ src/templates/",
      "watch:pug": "ack-pug-bundler src/pugs/ src/templates/ --watch --pretty",
      "build:pug:for-nodejs": "ack-pug-bundler src/pugs/ src/templates/ --outType common"
      "build:htmls": "ack-pug-bundler src/htmls src/templates --oneToOne --includeHtmls --outType ts"
    }

    Script Descriptions

    • build:index
      • Converts a single pug file into one html file
    • build:pug
      • Converts multiple pug files into one .js file with import/export ecma6 like syntax
    • watch:pug
      • Watches multiple pug files to convert into one .js file with import/export ecma6 like syntax
    • build:pug:for-nodejs
      • Converts multiple pug files into one .js file with module.exports commonjs like syntax

    Examples

    Example Single File

    A great place to start. We will compile a .pug file to a .js file.

    Create a pug template file named: main.pug

    div Hello World

    Create file: write-pug.js

    var ackPug = require("ack-pug-bundler")
    var filePath = require("path").join(__dirname,"main.pug")
     
    //main.pug.js file is written with ecma6 export syntax
    ackPug.writeFile(writeFile)

    Now, in a command terminal, run the following

    node write-pug.js

    The result of the above command, created the file main.pug.js

    Below is the file main.pug.js

    export default "<div>Hello World</div>"

    Example Multi File

    A more robust use case. Let's take two files and write three.

    Create a pug/jade template file named: main.pug

    div Hello World

    Create another pug/jade template file named: other-main.pug

    div Hello Other World

    Create file: write-pugs.js

    var ackPug = require("ack-pug-bundler")
    var filePath = __dirname
     
    //main.pug.js and other-main.pug.js file is written with ecma6 export syntax
    ackPug.crawlPath(filePath, {outType:'common'})

    Now, in a command terminal, run the following

    node write-pugs.js

    The result of the above command, created several files

    Below is the file main.pug.js

    module.exports= "<div>Hello World</div>"

    Below is the file other-main.pug.js

    module.exports = "<div>Hello Other World</div>"

    Example asJsonFile

    Produce one JSON file that has all your template files

    TIP: If you are using JSPM to bundle web architectures, you will most likely want to use the attribute "asOneFile" because JSPM does not natively import JSON files.

    Create file: write-pugs.js

    var ackPug = require("ack-pug-bundler")
     
    //templates.js file is written with ecma6 export syntax
    ackPug.crawlPath(__dirname, {asJsonFile:'templates.js'})

    Now, in a command terminal, run the following

    node write-pugs.js

    The result of the above command, created templates.json

    Below is the file templates.json

    {
      "timestamp": 1470005320783,
      "./main" : "<div>Hello World</div>",
      "./other-main" : "<div>Hello Other World</div>"
    }

    Example asOneFile

    Bundles all templates into just one file. Also includes handy get(templateName) function in output file.

    TIP: If you are using JSPM to bundle web architectures, you will most likely want to use the attribute "asOneFile" because JSPM does not natively import JSON files.

    Create file: write-pugs.js

    var ackPug = require("ack-pug-bundler")
     
    //templates.js file is written with ecma6 export syntax
    ackPug.crawlPath(__dirname, {asOneFile:'templates.js'})

    Now, in a command terminal, run the following

    node write-pugs.js

    The result of the above command, created templates.js

    Below is the file templates.js

    export default {
      "timestamp": 1470005320783,
      "./main" : "<div>Hello World</div>",
      "./other-main" : "<div>Hello Other World</div>",
      get:function(templateName){...gets template or throws error..}
    }

    Example Watch

    Use this example to watch pug/jade files for changes and then write the compile results elsewhere

    Create file: watch-pug.js

    var ackPug = require("ack-pug-bundler")
    var path = require("path")
    var folderPath = path.join(__dirname,"src")
    var outPath0 = path.join(__dirname,"result-js-files","ecma6")
    var outPath1 = path.join(__dirname,"result-js-files","commonJs")
     
    //pug files written with ecma6 export syntax
    ackPug.watchPath(folderPath, outPath0)
     
    //pug files written with module.exports syntax
    ackPug.watchPath(folderPath, outPath1, {outType:'common'})
     
    //pug files written as one file with module.exports syntax
    ackPug.watchPath(folderPath, outPath1, {outType:'common', asOneFile:'templates.js'})
     
    console.log('[ack-pug-bundler]:watching', folderPath)

    Example Build All

    Use this example to compile all pug/jade files and then write the compile results elsewhere

    Create file: build-pug.js

    var ackPug = require("ack-pug-bundler")
    var path = require("path")
    var folderPath = path.join(__dirname,"src")
    var outPath0 = path.join(__dirname,"result-js-files","ecma6")
    var outPath1 = path.join(__dirname,"result-js-files","commonJs")
     
    console.log('[ack-pug-bundler]:building', folderPath)
     
    //pug files compled and written with ecma6 export syntax
    ackPug.crawlPath(folderPath, outPath0)
    .then(function(){
      console.log('[ack-pug-bundler]:ecma6 completed', folderPath)
    })
    .catch(console.log.bind(console))
     
    //pug files compiled written with module.exports syntax
    ackPug.crawlPath(folderPath, outPath1, {outType:'common'})
    .then(function(){
      console.log('[ack-pug-bundler]:commonJs completed', folderPath)
    })
    .catch(console.log.bind(console))
     
    //pug files compiled into one file and written with module.exports syntax
    ackPug.crawlPath(folderPath, outPath1, {outType:'common', asOneFile:'templates.js'})
    .then(function(){
      console.log('[ack-pug-bundler]:commonJs single-file completed', folderPath)
    })
    .catch(console.log.bind(console))

    Example NPM Script

    Based on example usages above, you can create a quick command script

    Edit package.json and save

    {
      "scripts": {
        "watch:pug": "node watch-pug",
        "build:pug": "node build-pug"
      }
    }

    Now you can watch pug files for changes and output js file versions

    $ npm run watch:pug

    Now you can vuild pug files and output js file versions for application use

    $ npm run build:pug

    Install

    npm i ack-pug-bundler

    DownloadsWeekly Downloads

    2

    Version

    1.4.8

    License

    MIT

    Unpacked Size

    73 kB

    Total Files

    23

    Last publish

    Collaborators

    • ackerapple