npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

html-webpack-template-pug

v1.1.1

Published

A template for html-webpack-plugin made in pug template language

Downloads

56

Readme

HTML Webpack Template Pug

Build Status npm version Commitizen friendly devDependencies peerDependencies license

This is a Pug template for the webpack plugin html-webpack-plugin. Inspired by another template, html-webpack-template.

In addition to the options that should cover most needs of a single-page app, a custom Pug file can be used to extend the provided layout.pug or to completely rewrite the template while utilizing mixins from mixins.pug.

Loading the template requires that pug-loader and consequently pug be available in node_modules.

Installation

Install the template with npm:

npm install html-webpack-template-pug --save-dev

or together with peer dependencies:

npm install pug pug-loader html-webpack-plugin html-webpack-template-pug --save-dev

Basic Usage

Required parameters, to be passed to new HtmlWebpackPlugin(options) as properties on options:

  • inject: false -- Disables resource injection by html-webpack-plugin
  • template: provided layout.pug or a custom *.pug file.

Pug-loader should either be set for all *.pug files:

module: {
  loaders: [
    //...
    {
      test: /\.pug$/,
      loader: 'pug-loader'
    }
  ]
}

or explicitly together with the template:

template: '!!pug-loader!custom_template.pug'

Optional parameters:

  • appMountId: String or [String,...] -- Id or an array of ids for the <div> elements to be included in the <body>, for mounting JavaScript app, etc.
  • mobile: Boolean = false -- Adds a meta tag for viewport size and page scaling on mobile.
  • inline: String or [String,...] -- A chunk name or an array of chunk names to be inlined. A chunk name corresponds to the name of the entry point and can include :css or :js postfix to limit resources to be inlined to CSS or JavaScript respectively.
  • excludeJSWithCSS: Boolean = false -- Excludes JavaScript files from chunks that contain CSS files. Intended for use cases when a JavaScript file (e.g style.js) is created as a byproduct of a CSS-only entry chunk (entry: {style: 'main.css'}).
  • excludeJSChunks: String or [String,...] -- A chunk name or an array of chunk names. Excludes JavaScript files from specific chunks. Intended for use cases when a JavaScript file (e.g style.js) is created as a byproduct of a CSS-only entry chunk (entry: {style: 'main.css'}).
  • injectExtras.head: [tag,...] -- An array of Objects representing tags to be injected in <head>. A tag can be:
    • A String ending with ".css". Then the injected tag becomes <link rel="stylesheet" href=tag>.

    • A String ending with ".js". Then the injected tag becomes <script src=tag></script>.

    • An object with one required property tag that will serve as the tag name. All other properties will be set on the injected tag as its attributes. innerHTML property, if set, will be passed as content to non-self-closing tags.

    • To give an example:

      {
        tag: "meta",
        name: "description",
        content: "A description of the page"
      }

      becomes

      <meta name="description" content="A description of the page">
  • injectExtras.body: [tag,...] -- Same as injectExtras.head but to be injected at the bottom of the <body>.

And other options from html-webpack-plugin#configuration.

Example of basic usage

An example of webpack configuration utilizing the options above:

{
  // ...
  plugins: [
    new HtmlWebpackPlugin({
      // Required
      inject: false,
      template: require('html-webpack-template-pug'),
      // template: '!!pug-loader!node_modules/html-webpack-template-pug/layout.pug'
      
      // Optional
      appMountId: 'app',
      // appMountId: ['app1', 'app2']
      mobile: true,
      injectExtras: {
        head: [
          "https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css",
          {
            tag: 'link',
            rel: 'dns-prefetch',
            href: '//example.com/'
          },
          {
            tag: 'base',
            href: '../assets/page.html'
          },
          {
            tag: 'meta',
            name: 'description',
            content: 'A description of the page'
          }
        ],
        body: [
          'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.0/jquery.min.js',
          'https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js',
          {
            tag: 'noscript',
            innerHTML: "JavaScript is disabled in your browser. <a href='http://www.enable-javascript.com/' target='_blank'>Here</a> is how to enable it."
          }
        ]
      },
      title: 'My App'
      // Other html-webpack-plugin options...
    })
  ]
}

An example of webpack configuration with extracting a CSS-only entry chunk:

{
  entry: {
		app: './app',
		style: './app/main.css'
	},
	output: {
		path: './build',
		filename: '[name].js'
	},
	module: {
		loaders: [
      // ...
			{
				test: /\.css$/,
				loader: ExtractTextPlugin.extract('style', 'css')
			}
		]
	},
  // ...
  plugins: [
    new HtmlWebpackPlugin({
      // Required
      inject: false,
      template: require('html-webpack-template-pug'),
      // template: '!!pug-loader!node_modules/html-webpack-template-pug/layout.pug'
      
      // Optional
      excludeJSChunks: 'style',	// don't include specific chunks in scripts (when .js is a byproduct of an already extracted .css)
			// excludeJSChunks: ['style1', 'style2']
      appMountId: 'app',
      mobile: true,
      title: 'My App'
      // Other html-webpack-plugin options...
    }),
    new ExtractTextPlugin('[name].css')
  ]
}

Intermediate Usage

The layout.pug that is used by default with require('html-webpack-template-pug') amounts to the following:

include ./mixins.pug

doctype html
html(lang='en', manifest=htmlWebpackPlugin.files.manifest)
	head
		meta(charset='utf-8')
		meta(http-equiv='X-UA-Compatible', content='IE=edge')
		
		block defaultHead
			+mobile
			+title
			+favicon
			+injectExtrasHead
			+CSS

		block head

	body

		block content
			+appMount
			
		block defaultBody
			+injectExtrasBody
			+JS
			
		block scripts

And can be extended like any other .pug template:

//- index.pug
//- include/extends ~%PATH% resolves to node_modules/%PATH%
extends ~html-webpack-template-pug/layout.pug

block head
	link(rel="stylesheet", href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css")

block content
	header
		h2 Header
	
	main
		+appMount
	
	footer
		h2 Footer

block scripts
	script(src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.0/jquery.min.js")
	script(src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js")

Example of intermediate usage

An example of webpack configuration with a custom template extending the default:

{
  // ...
  plugins: [
    new HtmlWebpackPlugin({
      // Required
      inject: false,
      template: '!!pug-loader!index.pug',      
      // Optional
      appMountId: 'app',
      mobile: true,
      title: 'My App'
      // Other options...
    })
  ]
}

Advanced usage

For more flexibility it is possible to directly include mixins.pug and then construct a custom template.

Available mixins are:

  • title

    Adds title, to be used in <head>.

  • favicon

    Adds favicon, to be used in <head>.

  • mobile

    Adds mobile meta tag, to be used in <head>.

  • appMount(ids)

    Adds a div tag for each supplied id
    @ids can be an Array or a single id, if none supplied uses appMountId;
    also accepts attributes to be added to div tags, +appMount("id")(class="mount-point").

  • injectExtrasHead

    Injects extra resources passed in injectExtras.head of htmlWebpackPlugin.options.

  • injectExtrasBody

    Injects extra resources passed in injectExtras.body of htmlWebpackPlugin.options.

  • inline(filename, tag, searchWithin)

    Inlines a resource in a tag @filename is a string or a RegExp to be compared against files passed in HtmlWebpackPlugin (htmlWebpackPlugin.files);
    @tag if not provided is deduced from file extension
    @searchWithin -- array of filenames to match against RegExp @filename,
    equals to [...css, ...js] from htmlWebpackPlugin.files by default;
    also accepts attributes to be added to style/script tags, +inline(...)(attributes).

  • inject(filename, tag, searchWithin)

    Injects a resource in a tag @filename is a string or a RegExp to be compared against htmlWebpackPlugin.files;
    @tag if not provided is deduced from file extension
    @searchWithin -- array of filenames to match against RegExp @filename,
    equals to [...css, ...js] from htmlWebpackPlugin.files by default;
    also accepts attributes to be added to link/script tags, +inject(...)(attributes).

  • inlineCSS(cssList)

    Inlines css resources from htmlWebpackPlugin.files, except for already inlined or injected resources;
    @cssList can be a single filename string, RegExp or an array of them,
    cssList strings starting with "!" are skipped;
    by default cssList -- all css files that are supposed to be inlined according to htmlWebpackPlugin.options; also accepts attributes to be added to style tags, +inlineCSS(...)(attributes).

  • injectCSS(cssList)

    Injects css resources from htmlWebpackPlugin.files, except for already inlined or injected resources;
    @cssList can be a single filename string, RegExp or an array of them,
    cssList strings starting with "!" are skipped;
    by default cssList -- all css files that are supposed to be injected according to htmlWebpackPlugin.options; also accepts attributes to be added to link tags, +injectCSS(...)(attributes).

  • inlineJS(jsList)

    Inlines js resources from htmlWebpackPlugin.files, except for already inlined or injected resources;
    @jsList can be a single filename string, RegExp or an array of them,
    jsList strings starting with "!" are skipped;
    by default jsList -- all js files that are supposed to be inlined according to htmlWebpackPlugin.options; also accepts attributes to be added to script tags, +inlineJS(...)(attributes).

  • injectJS(jsList)

    Injects js resources from htmlWebpackPlugin.files, except for already inlined or injected resources;
    @jsList can be a single filename string, RegExp or an array of them,
    jsList strings starting with "!" are skipped;
    by default jsList -- all js files that are supposed to be injected according to htmlWebpackPlugin.options; also accepts attributes to be added to script tags, +injectJS(...)(attributes).

  • inlineChunk(chunkNames, type)

    Inlines files of type @type from chunk with @chunkName name;
    @chunkName - a valid chunk name from htmlWebpackPlugin.files.chunks or an array of names,
    @type - can be "css" or "js", which inlines css or js files respectively, otherwise inlines both types; also accepts attributes to be added to style/script tags, +inlineChunk(...)(attributes).

  • injectChunk(chunkNames, type)

    Injects files of type @type from chunk with @chunkName name;
    @chunkName - a valid chunk name from htmlWebpackPlugin.files.chunks or an array of names,
    @type - can be "css" or "js", which injects css or js files respectively, otherwise injects both types; also accepts attributes to be added to link/script tags, +injectChunk(...)(attributes).

  • CSS

    Inlines css resources from chunks passed in htmlWebpackPlugin.options.inline
    and injects the rest, in the order they appear htmlWebpackPlugin.files; also accepts attributes to be added to link/style tags, +CSS(...)(attributes).

  • JS

    Inlines js resources from chunks passed in htmlWebpackPlugin.options.inline
    and injects the rest, in the order they appear htmlWebpackPlugin.files; also accepts attributes to be added to script tags, +JS(...)(attributes).

inline*, inject*, CSS and JS mixins keep track of inlined and injected files, so no one file will appear twice. This allows for:

+inlineCSS("style.css")
//- style.css

//- ...

//- the rest
+CSS

However, inline and inject mixins allow duplicates.

To clarify usage of different parameters in inlineCSS, injectCSS, inlineJS and injectJS:

+inlineCSS
//- inlines all css resources passed in HtmlWebpackPlugin (htmlWebpackPlugin.files.css)

+inlineCSS("style.css")
//- inlines style.css

+inlineCSS(/\.css$/)
//- inlines all /\.css$/ matches in htmlWebpackPlugin.files.css

+inlineCSS("!style.css")
//- inlines all resources from htmlWebpackPlugin.files.css except for style.css

+inlineCSS(["style1.css", "style2.css"])
//- inlines style1.css and style2.css

+inlineCSS([/\.css$/, "!style2.css"])
//- inlines all /\.css$/ matches except for style2.css

+inlineCSS(["!style1.css", "!style2.css"])
//- inlines all resources from htmlWebpackPlugin.files.css except for style1.css and style2.css

A custom template can then look like this:

//- index.pug
//- include/extends ~%PATH% resolves to node_modules/%PATH%
include ~html-webpack-template-pug/mixins.pug

doctype html
html(lang='en')
	head
		meta(charset='utf-8')
		meta(http-equiv='X-UA-Compatible', content='IE=edge')
		base(href="../assets/page.html")
		
		+mobile
		+title
		//- injects all .css files
		+inject(/\.css$/)


	body
	
		+appMount
			
		//- injects all .js files
		+inject(/\.js$/)

Example of advanced usage

An example of webpack configuration with a custom template including the default mixins:

{
  // ...
  plugins: [
    new HtmlWebpackPlugin({
      // Required
      inject: false,
      template: '!!pug-loader!index.pug',      
      // Optional
      appMountId: 'app',
      mobile: true,
      title: 'My App'
      // Other options...
    })
  ]
}

License

This software is licensed under MIT.