pugjs-brunch

Adds Pug v2.x (aka Jade) support to Brunch

This plugin compiles templates into any of three types:

• Dynamic: Parameterized function that creates HTML at runtime based on the received parameters.
• Precompiled: Returns raw HTML string with minimum overhead at runtime.
• Static: Plain HTML files from pug templates in the assets directory.

See the changes for this version in the CHANGELOG.

Install

npm install pugjs-brunch --save-dev
# or 
yarn add pugjs-brunch -D

or through devDependencies in package.json:

  "pugjs-brunch": "^2.11.2",

To compile pug into static, plain HTML, just place your files into the assets directory (usually app/assets).

The runtime

For modules, unless the inlineRuntimeFunctions option is set to true (not recommended), it is neccesary the Pug runtime, a small set of functions that lives in the global variable pug.

If required, the plugin loads a runtime from its own directory, so you don't have to worry about this.

NOTE:

Under certain circumstances the loading of the runtime may fail. If this happens to you, move pug_runtime.js from node_modules/pugjs-brunch/vendor to your vendor folder and load it in the global scope. Example:

  // In your brunch config
  plugins: {
    pug: { pugRuntime: false }
  }

  <!-- in your index.html file -->
  <script>
    require('pug_runtime')
    $(document).ready(function() {
      require('app')
    })
  </script> 

Options

The plugin uses the plugins.pug section of your brunch-config and defines this properties:

Name	Type	Default	Notes
locals	any		Plain JavaScript object passed to Pug for static compilation.
staticBasedir	string	(brunch)	Brunch convention.assets folder as string. This is the root of static templates.
staticPretty	boolean	true	Pug's pretty option for files in staticBasedir, see NOTE (v2.8.5).
preCompilePattern	RegExp	/.html.pug$/	pre-compile the templates matching this regex (v2.8.6).
pugRuntime	boolean	true	Set to false if you want to load another runtime.
sourceMap	boolean	true	Defaults to brunch sourceMaps (with 's') value, false disables it (v2.8.4).

Note

From v2.11.1 staticPretty is set to false for production builds. Thanks to @stawberri

You can use any Pug options as well, pugjs-brunch set this:

{
  doctype: 'html',
  basedir: 'app',      // or wherever Brunch config says
  compileDebug: true,  // false if brunch `optimize` mode is 'production'
}

TIP:

Use preCompilePattern: /\S/ to evaluate all the templates at build time.

About staticBasedir

This option is only meaningful if you changed the default value of conventions.assets in the Brunch config and you are using absolute paths in includes or extends. This value will be pass to Pug as basedir when compiling static assets as html (see the pug options).

NOTE:

The options pretty and compileDebug are forced to false in production mode.

Examples

Dynamic templates

  // brunch-config.js
  ...
  plugins: {
    pug: {}
  },

  //- app/views/tmpl.pug
  p= name

  // in the js code
  ...
  const tmplFn = require('views/tmpl.pug')
  $('#elem').html(tmplFn({ name: 'John Doe' }))
  // now #elem contains <p>John Doe</p>

Precompilation

  // brunch-config.js
  ...
  plugins: {
    pug: {
      locals: { name: 'John Doe' },
      preCompilePattern: /\.html\.pug$/
    }
  },

  //- app/views/tmpl.html.pug
  p= name

  // in the js code
  ...
  const htmlStr = require('views/tmpl.html.pug')
  $('#elem').html(htmlStr)
  // now #elem contains <p>John Doe</p>

Static files

  // brunch-config.js
  ...
  plugins: {
    pug: {
      locals: { name: 'John Doe' }
    }
  },

  //- app/assets/user.pug
  doctype html
  html
    head
      meta(charset="utf-8")
    body
      p= name

will create the file ./public/user.html

Using with jscc-brunch

  ...
  plugins: {
    jscc: {
      values: {
        _APP: 'My App'  // $_APP can do static replacement
      },
      pattern: /\.(?:js|pug)$/,
      sourceMapFor: /\.(?:js|pug)$/,
      sourceMap: true
    },
    pug: {
      globals: ['$_APP']
    }
  }
  ...

Support my Work

I'm a full-stack developer with more than 20 year of experience and I try to share most of my work for free and help others, but this takes a significant amount of time and effort so, if you like my work, please consider...

Of course, feedback, PRs, and stars are also welcome 🙃

Thanks for your support!

License

The MIT License (MIT)

© 2016-2018 Alberto Martínez