Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jpachecox/setup-gulp/llms.txt

Use this file to discover all available pages before exploring further.

Setup Gulp follows a deliberate directory layout that keeps raw source files completely separate from compiled output. Everything you author lives inside src/, organised by asset type and then further split into components/, sections/, and root-level files. The components/ and sections/ subdirectories follow a naming convention — Gulp watches those paths and applies the correct output prefix automatically when you create them. Gulp reads from src/, processes each file through the appropriate task chain, and writes the final minified result into assets/ — the flat directory that Shopify themes expect. You never edit anything inside assets/ directly; it is always regenerated by the build.

​
Directory Tree

setup-gulp/
├── assets/                   # Compiled output (auto-generated, gitignored)
├── src/
│   ├── app.ts                # Root-level TypeScript entry point
│   ├── fonts/                # Font files (.ttf, .woff, .woff2, etc.)
│   ├── img/                  # Source images (.png, .jpg, .jpeg, .gif, .svg)
│   ├── js/
│   │   ├── components/       # [convention] Per-component TypeScript files (create as needed)
│   │   ├── sections/         # [convention] Per-section TypeScript files (create as needed)
│   │   └── *.ts              # Root-level TypeScript modules (e.g. sum.ts)
│   ├── scss/
│   │   ├── components/       # Per-component SCSS partials
│   │   ├── sections/         # [convention] Per-section SCSS partials (create as needed)
│   │   ├── _colors.scss      # Color variable definitions
│   │   ├── _fonts.scss       # Font-face declarations
│   │   ├── _functions.scss   # Reusable SCSS functions
│   │   ├── _mixins.scss      # Reusable SCSS mixins
│   │   ├── _variables.scss   # Global SCSS variables
│   │   └── app.scss          # Main stylesheet entry point
│   └── css/                  # Intermediate compiled CSS (before minification, gitignored)
├── __tests__/                # Vitest unit test files
├── index.html                # Local dev entry point (served by BrowserSync)
├── gulpfile.js               # All Gulp task definitions
├── package.json              # Dependencies, scripts, Husky, and lint-staged config
├── tsconfig.json             # TypeScript compiler options (target: ES2016, strict: true)
└── vitest.config.ts          # Vitest configuration (jsdom environment, V8 coverage)
Directories marked [convention] — src/js/components/, src/js/sections/, and src/scss/sections/ — do not exist in the repository by default. They represent the naming convention Gulp expects when you add component or section files to your project. Create them as you need them; Gulp’s watch task will pick up any matching files automatically.

​
The src/ Directory Conventions

Gulp task definitions in gulpfile.js rely on the sub-directory structure inside src/ to decide how each file is named in the output. Understanding these conventions lets you add new source files in the right place without touching any configuration.

​
Naming prefixes by subdirectory

The compileSass and optimizeJs helper functions in gulpfile.js accept a prefix argument, and each Gulp task passes a different prefix depending on where the source file lives:

components/

Files inside src/scss/components/ and src/js/components/ are compiled with the component- prefix.Example: src/scss/components/loading-spinner.scss → assets/component-loading-spinner.min.css

sections/

Files inside src/scss/sections/ and src/js/sections/ are compiled with the section- prefix.Example: src/js/sections/hero.ts → assets/section-hero.min.js

Root-level files

Files at the root of src/scss/ and src/js/ are compiled without any prefix, using their original filename.Example: src/scss/app.scss → assets/app.min.css

​
SCSS source files

All SCSS source files live under src/scss/. Partials (_*.scss) are imported by other files and are never compiled standalone. The main entry point is app.scss, which imports partials and sets up the global styles. Bourbon and Bourbon Neat include paths are injected automatically via the sassCompiler options in gulpfile.js, so you can use all Bourbon utilities without manual @use paths. The compilation flow for SCSS has two stages:
  1. Sass compile — Dart Sass converts *.scss to *.css (with Bourbon/Neat include paths and PostCSS Autoprefixer applied), writing intermediate .css files to src/css/.
  2. Minification — gulp-clean-css reads from src/css/, minifies each file, appends the .min suffix, generates sourcemaps, and writes the result to assets/.

​
TypeScript source files

All TypeScript files live under src/js/. They are processed by Babel (using @babel/preset-env and @babel/preset-typescript) to transpile TypeScript to ES5 JavaScript. The output is then minified by gulp-uglify, given the appropriate prefix and a .min.js suffix, and written directly to assets/. Sourcemaps are embedded inline.

​
Images and fonts

Source images (src/img/) are run through gulp-imagemin with the following optimisers:
  • gifsicle — interlaced GIF compression
  • mozjpeg — quality 75, progressive encoding
  • optipng — optimisation level 5
  • svgo — SVG optimisation with removeViewBox enabled
Optimised images are copied to assets/. Font files (src/fonts/) are copied to assets/ as-is without any transformation.

​
The assets/ Output Directory

The assets/ directory is the sole output target for every Gulp task. Its structure is intentionally flat — all compiled CSS, JavaScript, images, and fonts live at the same level with no subdirectories. This matches the flat structure of a Shopify theme’s assets/ folder, which means you can point your Shopify theme configuration directly at this directory without any renaming or reorganisation. A typical assets/ directory after a full build looks like this: 
assets/
├── app.min.css
├── app.min.css.map
├── component-cart-drawer.min.css
├── component-cart-drawer.min.js
├── section-hero.min.css
├── section-hero.min.js
├── logo.svg
├── banner.jpg
└── icons.woff2
Every CSS and JavaScript file in assets/ is minified and accompanied by a sourcemap, so browser DevTools can still point you to the original source line during debugging.

​
The __tests__/ Directory

Unit tests written for Vitest live inside __tests__/. The vitest.config.ts configures the test runner with the jsdom environment (so DOM APIs are available without a real browser), enables Vitest globals (describe, it, expect, etc.), and sets up V8 coverage reporting. The gulpfile.js and everything inside assets/ are excluded from both test discovery and coverage collection.
The assets/ and src/css/ directories are auto-generated by Gulp and should be added to your .gitignore. Committing compiled output leads to noisy diffs and merge conflicts. Run yarn build (or yarn start during development) to regenerate them at any time, and use yarn clean to remove them entirely.

Build docs developers (and LLMs) love

Get started for freeTalk to us