Gulp + Nunjucks Automation: Modern Frontend Build Workflow

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

🖼️ 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

2. ⚡ 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

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

3. ✏️ 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",
}

To whatever your project name is:

{
  "name": "my-project",
  "version": "1.0.0",
  "main": "gulpfile.js",
}

4. 📦 Install dependencies

npm install

5. 🏃 Start development server

npm run dev

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

---

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. 🙃