rollup-plugin-pug

    1.1.1 • Public • Published

    rollup-plugin-pug

    License npm Version Linux build Status Windows build status

    Rollup plugin that transforms Pug v2 templates to ES6 modules.

    • Dynamic generation of HTML. Static HTML is optional and configurable.
    • Automatic import of the pug-runtime in your bundle, if required.
    • Automatic import of template extends and includes.
    • Source map support.
    • Support for ES6 import statements (moved out of the template).
    • Typescript v3.x definitions.

    IMPORTANT

    v1.1 requires Rollup 0.61 and node.js 6 or later, for previous versions use rollup-plugin-pug 0.1.6

    Installation

    npm install rollup-plugin-pug --save-dev

    Usage

    Create the template

    //- template.pug
    p= message

    and import it as any other function:

    import templateFn from './template.pug';
     
    const context = { message: 'Hello World' };
     
    console.log(templateFn(context));  // <p>Hello World</p>

    or rename it for static compilation and import it as string:

    import htmlString from './template.static.pug';
     
    console.log(htmlString);  // <p>Hello World</p>

    Build with something like...

    import { rollup } from 'rollup';
    import pug from 'rollup-plugin-pug';
     
    rollup({
      entry: 'src/main.js',
      plugins: [
        pug({
          locals: { message: 'Hello World' }
        })
      ]
    }).then(...)

    That's it.

    Options

    In addition to the regular pug options, the plugin defines these:

    • staticPattern - Regex for files to compile and evaluate at build time to export plain HTML.
    • locals - Plain JavaScript object with values passed to the compiler for static compilation (Deprecated).
    • include - minimatch or array of minimatch with files that should be included by default.
    • exclude - minimatch or array of minimatch with files that should be excluded by default.
    • extensions - Array of extensions to process (don't use wildcards here).
    • pugRuntime - Custom Pug runtime filename (See note).
    • sourceMap - Enabled by default.

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

    Be carefull

    The parameter passed to the static templates is a shallow copy of the plugin options. Do not change it unless you know what you doing.

    When a template matches the staticPattern regex, the template is executed at complie-time and you load the resulting string through import at runtime, so it will not have access to runtime variables or methods. Instead, the plugin passes its options to the template at compile-time.

    Default Options

    The plugin has preset the following options:

    {
      doctype: 'html',
      basedir: absolute(input),       // absolute path of the rollup `input` option
      compileDebug: false,            // `true` is recommended for development
      sourceMap: true,                // with or without compileDebug option
      inlineRuntimeFunctions: false,  // use the pug runtime
      extensions: ['.pug', '.jade'],
      staticPattern: /\.static\.(?:pug|jade)$/
    }

    See the full list and explanation in the API Documentation of the pug site.

    Note: The default of staticPattern was defined to be compatibile with the old Jade plugin and so it has remained, but I prefer /\.html\.pug$/.

    Custom runtime

    The pugRuntime option can be set to false to avoid importing the runtime, but you must provide an equivalent pug object accessible to the template:

    Disable the predefined runtime in rollup.config.js

      ...
      plugins: [
        pug({ pugRuntime: false })
      ]

    and import the yours in your .pug files

    - import pug from 'my-runtime'
    p= name
    //- ...etc

    but the recommended option is name it in the config:

      // in rollup.config.js
       ...
       plugins: [
         pug({ pugRuntime: 'my-runtime' })
       ]

    Search for "pugRuntime" in the test/run.js file to see examples.

    What's New

    v1.1.1

    • #14: fix (this.warn is not a function) - thanks to @leptonix

    See the CHANGELOG for more changes.

    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!

    Install

    npm i rollup-plugin-pug

    DownloadsWeekly Downloads

    955

    Version

    1.1.1

    License

    MIT

    Unpacked Size

    56.2 kB

    Total Files

    62

    Last publish

    Collaborators

    • avatar