node package manager
Love JavaScript? Your insights can make it even better. Take the 2017 JavaScript Ecosystem Survey »



Gulp plugin for including HTML files into each other. Made for fun and my personal needs, but I'll appreciate if anyone will use it \( ゚ヮ゚)/

I know, there are some long-time solutions like gulp-file-include, but I wanted to create something on my own with html-like syntax.

Supports nested partials and passing parameters as attributes.


  • gulp (>=3.9.1) (guess it'll work with older versions too)
  • Node (>=6.5.0) (not sure 4.x will handle all ES6 stuff)


npm install --save-dev gulp-html-partial


in HTML:

Files are included in src and dist directories.


<div class="container">
    <partial src="_1.html" title="Some title"></partial>


    <div class="title">@@title</div>
    <span>Some span</span>
        Some text
<partial src="_2.html" param="Nested partial" dashed-param="Some-dashed-param"></partial>
<partial src="_3.html" param="I don't exist :("></partial>


<div class="wtf">
    Some text
    <div class="header">@@param</div>
    <div class="block">@@dashed-param</div>
<p>Some text</p>

Results in:

<div class="container">
        <div class="title">Some title</div>
        <span>Some span</span>
        <div>Some text</div>
    <div class="wtf">Some text
        <div class="header">Nested partial</div>
        <div class="block">Some-dashed-param</div>
    <p>Some text</p>

in gulpfile.js:

const gulp = require('gulp');
const htmlPartial = require('gulp-html-partial');
gulp.task('html', function () {
            basePath: 'src/partials/'


const defaults = {
        basePath: '',
        tagName: 'partial',
        variablePrefix: '@@'
  • basePath - base path for your partials, relative to gulpfile.js
  • tagName - name of your partial tag, must have at least src attribute with path to partial file
  • variablePrefix - prefix of variable keys passed as attributes into partials


  • missing partials defaults to empty string
  • errors fire as logs, not as events, to make sure every, not only the first one, missing partial will be described - but I guess there is a way to make that work with events too