This content originally appeared on DEV Community and was authored by bekdev
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
- Clone the repository:
git clone https://github.com/serhatbek/gulp-nunjucks-template.git ./my-project
cd my-project
- ⚡ 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.
- ✏️ Change the project name in the
package.jsonfile 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",
}
- 📦 Install dependencies
npm install
- 🏃 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
| 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. 🙃
This content originally appeared on DEV Community and was authored by bekdev
bekdev | Sciencx (2025-10-18T17:19:43+00:00) Gulp + Nunjucks Automation: Modern Frontend Build Workflow. Retrieved from https://www.scien.cx/2025/10/18/gulp-nunjucks-automation-modern-frontend-build-workflow/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.