DEV Community

Cover image for Gulp + Nunjucks Automation: Modern Frontend Build Workflow
bekdev
bekdev

Posted on

Gulp + Nunjucks Automation: Modern Frontend Build Workflow

#gulp #nunjucks #automation #frontend

I’ve always loved clean, maintainable workflows — the kind where everything just works.

But after years of trying modern bundlers, frameworks, and endless plugins, I kept coming back to Gulp — simple, flexible, and surprisingly future-proof. Especially for smaller vanilla javascript projects.

So I decided to build my own starter:

A fully automated frontend workflow using Gulp 5 , Nunjucks , and SCSS , designed for developers who want control and clarity — not a black box.

To install and use, go to repo.

You can find the full documentation here.

🚀 Why I Built This

Modern frontend tools can feel heavy and fragile.

You install 50 dependencies, and suddenly your build breaks because one library changed its syntax.

I wanted something lightweight , modular , and predictable — a workflow you can understand at a glance and maintain for years.

That’s what this setup gives you:

  • Simple folder structure
  • Task-based build pipeline
  • Clear file injection logic
  • And no mysterious magic — just code you can actually read.

✨ Features at a Glance

  • ✅ Gulp 5 task runner (modernized & async-ready)
  • ✅ Nunjucks templating with partials and data files
  • ✅ SCSS + PostCSS for clean, autoprefixed CSS
  • ✅ Babel to transpile modern JavaScript
  • ✅ BrowserSync for instant live reload
  • ✅ SVG to icon font generator — no manual Unicode naming
  • ✅ Readable, modular task files — perfect for learning Gulp

Tested on Node.js 22.20.0 — use this version (via .nvmrc) for maximum compatibility.

📁 Folder Structure

Here’s a quick overview of how everything is organized:

src/
┣ data/
┣ icons/
┣ js/
┣ scss/
┃ ┣ base/
┃ ┣ components/
┃ ┣ pages/
┃ ┣ vendors/
┃ ┗ main.scss
┣ tasks/
┗ templates/
  ┣ includes/
  ┃ ┣ components/
  ┃ ┗ layout/
  ┗ pages/
    ┗ index.njk

dist/
┣ assets/
┃ ┣ css/
┃ ┣ fonts/
┃ ┃ ┗ icons/
┃ ┣ images/
┃ ┗ js/
┗ index.html
Enter fullscreen mode Exit fullscreen mode

🖼️ Important:

You’ll need to manually add your images and fonts into dist/assets/images and dist/assets/fonts.

🧩 Getting Started

  1. Clone the repository: 
git clone https://github.com/serhatbek/gulp-nunjucks-template.git ./my-project
cd my-project
Enter fullscreen mode Exit fullscreen mode
  1. ⚡ Install and use node.js v22.20.0 to ensure long-term stability. If nvm is installed and you already have v22.20.0, you can: 
nvm use
Enter fullscreen mode Exit fullscreen mode

The .nvmrc file in the project specifies the correct Node.js version.

  1. ✏️ Change the project name in the package.json file to your project name. This is important because later Gulp will inject JS and CSS files automatically using your project name.

From this:

{
  "name": "gulp-nunjucks-template",
  "version": "1.0.0",
  "main": "gulpfile.js",
}
Enter fullscreen mode Exit fullscreen mode

To whatever your project name is:

{
  "name": "my-project",
  "version": "1.0.0",
  "main": "gulpfile.js",
}
Enter fullscreen mode Exit fullscreen mode
  1. 📦 Install dependencies 
npm install
Enter fullscreen mode Exit fullscreen mode
  1. 🏃 Start development server 
npm run dev
Enter fullscreen mode Exit fullscreen mode

This will:

  • 🧹 Clean the build folders (except 'dist/assets/images' and 'dist/assets/fonts')
  • 💅 Compile SCSS and JS
  • 🔤 Generate font icons from SVG files
  • 🖼️ Render Nunjucks templates
  • 🌐 Start live-reloading browser

💡 Best Practices

  • Use Node.js 22.20.0 for maximum compatibility
  • Run npm run icons whenever you add, remove, or rename an SVG icon
  • Structure your SCSS and templates modularly (base/, components/, layouts/)
  • Use nvm or .nvmrc to lock Node version across systems

🧩 Troubleshooting

Problem Solution
Build fails or icons missing Check for invalid or corrupted SVGs insrc/icons/
Icons not displaying Runnpm run icons again after changing icons
Live reload not working Ensurenpm run dev is running and not blocked by firewall
Styles not updating Confirm your SCSS files are saved and insidesrc/scss/

Made with ❤️ for reusability.

Thank you for reading. If you find the article useful, please do not forget to like and comment so that others can access it. If you're on a generous day, you can even buy me a coffee. 🙃

Buy Me A Coffee

Top comments (0)