Skip to main content
  1. All Posts/


Tools Open Source PHP WordPress

The Mozaik WordPress Theme Boilerplate

This is a WordPress theme starter-kit meant to offer a first-class developer experience.


Full Feature List

  • Separate development theme and auto-generated clutter-free production (built) theme
  • Easy enough to port already existing themes over to it
  • gulp build process

    • Dev Mode

      • Auto browser refresh/injection on save (even for php files!) powered by BrowserSync
      • JavaScript module bundling, chunking and sourcemaps powered by Webpack
      • JavaScript ES6+ support via Babel
      • JavaScript linting via eslint
      • SCSS/SASS compilation and sourcemaps powered by libsass
      • SCSS linting via scss-lint (waiting for first stable release of scss-lint)
      • CSS prefixing via autoprefixer
      • SVG sprite generation via svg-sprite
    •   <li class="task-list-item">
          Production Mode</p> <ul class="contains-task-list">
            <li class="task-list-item">
              Minified CSS via cssmin
            <li class="task-list-item">
              Uglify, dedupe JS via Webpack
            <li class="task-list-item">
              Theme image optimization via imagemin
            <li class="task-list-item">
              SVG optimization via svgmin
        <li class="task-list-item">
          Build process easily extendable
    • NPM and Bower workflows supported
    • Theme Helpers Library (For more details check out the library’s README)

      • Responsive images specification implementation

        • Helper function to print WordPress media by attachment id using responsive background images,
          the picture element or img-srcset-sizes
        • Responsive images polyfill via picturefill
        • Builtin lazyload helper supported by aFarkas/lazysizes
      •   <li class="task-list-item">
            BEM Style simplified customizable/extendable nav-menu-walker
          <li class="task-list-item">
            BEM Style simplified customizable/extendable pagination renderer that easily supports custom queries
          <li class="task-list-item">
            BEM Style simplified customizable/extendable breadcrumbs renderer that is based on a given menu
          <li class="task-list-item">
            Utility classes to make it easier working with SVGs and SVG Sprites
      • Battle tested. Used in a multitude of small and large scale projects!

      Important Prerequisites

      Dev Environment

      1. Have node and npm installed on your system (node@5.0.0)
      2. Have gulp globally installed (gulp@^3.9.0)
      • You can use nvm to manage the node versions installed on your computer
      • You can use npm-check-updates to update the node modules in your theme (Note that updating may break things, so be careful)


      On Windows you may need to do some of the following if you run into trouble when running npm install in this project:

      • Install Python – Install version 2.7 of Python and add it to your path or/and create a PYTHONPATH environment variable.
      • Install Visual Studio (Express Edition is fine) – We will need this for some of modules that are compiled when installing Theme Starter. Download VS Express, get one of the versions that has C++ – Express 2013 for Windows Desktop for example.
      • Set Visual Studio Version Flags – We need to tell node-gyp (something that is used for compiling addons) what version of Visual Studio we want to compile with. You can do this either through an environment variable GYP_MSVS_VERSION. If you are using Express, you have to say GYP_MSVS_VERSION=2013e.

      Thanks to Ryanlanciaux


      1. Read the WordPress theme development guidelines
      2. Understand the WordPress template hierarchy
      3. Understand the WordPress Loop
      4. Understand how WordPress helps with Data Validation/Sanitization
      5. Read up on the following WordPress core APIs:
      6. Understand when you should use a Custom Functionality Plugin instead of implementing functionality within a theme


      1. This project uses webpack to provide support for modular JS, read up on the functionality & tools it provides


      1. The boilerplate assumes you are using SCSS to write your styles and compiles to CSS using Libsass
      2. Autoprefixer is used for adding the correct vendor prefixes to the final generated CSS

      Development Guidelines

      • Avoid committing the built theme to the project repository
      • Avoid committing the wp-uploads directory to the project repository
      • Avoid making changes directly to the built theme — Always use the build process
      • In production avoid uploading the theme development directory to a public server
      • It is good practice to enable WP_DEBUG in your wp-config.php file, but only during development

      Standard Theme Development Process


      1. Install WordPress and clear it of unnecessary default themes & plugins
      2. Clone/Download the contents of this repository into a directory in your WordPress wp-content/themes directory (eg: “my-theme_dev”) this will be your “dev theme”
      3. Open the terminal and navigate to the dev theme, eg: cd wp-content/themes/<my-theme>_dev
      4. (Note: The next steps require nodejs @5.0.0 and gulpjs @^3.9.0)
      5. Run npm install to install all dev dependencies
      6. Change the project.config.js file with your new theme’s…