{"id":18773108,"url":"https://github.com/webfactory/webfactory-gulp-preset","last_synced_at":"2026-02-15T15:02:41.019Z","repository":{"id":37897597,"uuid":"298822938","full_name":"webfactory/webfactory-gulp-preset","owner":"webfactory","description":"A collection of standard Gulp tasks to use in projects","archived":false,"fork":false,"pushed_at":"2026-02-10T17:09:28.000Z","size":324,"stargazers_count":1,"open_issues_count":9,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-02-10T21:08:07.736Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webfactory.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-09-26T13:44:25.000Z","updated_at":"2026-02-10T17:09:32.000Z","dependencies_parsed_at":"2023-11-17T14:07:49.923Z","dependency_job_id":"7ec5848b-de35-4910-946b-f2dc8d09228f","html_url":"https://github.com/webfactory/webfactory-gulp-preset","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/webfactory/webfactory-gulp-preset","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webfactory%2Fwebfactory-gulp-preset","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webfactory%2Fwebfactory-gulp-preset/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webfactory%2Fwebfactory-gulp-preset/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webfactory%2Fwebfactory-gulp-preset/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webfactory","download_url":"https://codeload.github.com/webfactory/webfactory-gulp-preset/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webfactory%2Fwebfactory-gulp-preset/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29481924,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T11:35:25.641Z","status":"ssl_error","status_checked_at":"2026-02-15T11:34:57.128Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T19:32:47.344Z","updated_at":"2026-02-15T15:02:40.990Z","avatar_url":"https://github.com/webfactory.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# webfactory-gulp-preset\n\nThis is a collection of useful Gulp tasks for \n\n- linting \u0026 compiling Sass (SCSS) to CSS\n- bundling JavaScript with Webpack\n- optimizing SVG source files\n\nWhile almost all dependencies are declared by this package, the choice of Sass compiler is left to the project – either\n`sass-embedded` (Dart Sass, current canonical implementation, recommended) or `node-sass` need to be installed as direct\nproject dependencies. \n\n## Table of contents\n\n1. [Basic Setup](#basic-setup)\n   1. [Folder structure](#folder-structure)\n   2. [Minimum dependencies](#minimum-dependencies-packagejson)\n   3. [Gulpfile](#gulpfile-gulpfilejs)\n   4. [Project-specific config](#project-specific-config-gulp-configjs)\n2. [Options](#options)\n   1. [SCSS/CSS pipeline](#scsscss-pipeline)\n      1. [Choose the Sass compiler](#choose-the-sass-compiler)\n      2. [Custom include paths for SCSS](#custom-include-paths-for-scss)\n      3. [PurgeCSS](#purgecss)\n   2. [JS pipeline](#js-pipeline)\n      1. [Svelte](#svelte)\n      2. [Custom paths for module resolving](#custom-paths-for-module-resolving)\n      3. [Transpile packages from `node_modules`](#transpile-packages-from-nodemodules)\n      4. [[legacy] Don't use Webpack to bundle JavaScript modules](#legacy-dont-use-webpack-to-bundle-javascript-modules)\n         - [Convert (\"transcompile\") modern JavaScript to backwards compatible ES5 for older browsers](#convert-transcompile-modern-javascript-to-backwards-compatible-es5-for-older-browsers)\n   3. [SVG optimizations](#svg-optimizations)\n\n## Basic Setup\n\n### Folder structure\n\nwebfactory-gulp-preset assumes that `gulpfile.js` and a `gulp-config.js` are located in the project's root folder.\n\n### Minimum dependencies (`package.json`)\n\n```json\n{\n  \"private\": true,\n  \"dependencies\": {\n    \"browserslist-config-webfactory\": \"^1.1.0\",\n    \"webfactory-gulp-preset\": \"^3.0.0\",\n    \"sass-embedded\": \"1.64.2\"\n  },\n  \"browserslist\": [\n    \"extends browserslist-config-webfactory/default\"\n  ]\n}\n```\n\n### Gulpfile (`gulpfile.js`)\n\n```js\nconst gulp = require('gulp');\nconst config = require('./gulp-config');\nconst $ = require('./node_modules/webfactory-gulp-preset/plugins')(config); // loads all gulp-* modules in $.* for easy reference\n\n\nconst { webpack } = require('./node_modules/webfactory-gulp-preset/tasks/webpack');\nconst { styles } = require('./node_modules/webfactory-gulp-preset/tasks/styles');\nconst { browsersync } = require('./node_modules/webfactory-gulp-preset/tasks/browsersync');\n\nfunction js(cb) {\n    webpack(gulp, $, config);\n    cb();\n}\n\nfunction css(cb) {\n    styles(gulp, $, config);\n    cb();\n}\n\nfunction serve(cb) {\n    browsersync(gulp, $, config, css, js);\n    cb();\n}\n\nexports.js = js;\nexports.css = css;\nexports.serve = serve;\nexports.compile = gulp.parallel(css, js);\nexports.default = gulp.series(gulp.parallel(css, js), serve);\n```\n\n### Project-specific config (`gulp-config.js`)\n\n```js\nconst argv = require('minimist')(process.argv.slice(2));\n\n// roll your own function if you need to use more or different plugins\nconst { postCssPlugins } = require('./node_modules/webfactory-gulp-preset/config/postcss-plugins-default');\n\nmodule.exports = {\n    scripts: {\n        files: [\n            {\n                name: 'scripts',\n                inputPath: [\n                    'PATH_TO_PROJECT_ASSETS_DIR/js/scripts.js',\n                ],\n                destDir: 'js'\n            }\n        ],\n        watch: ['PATH_TO_PROJECT_ASSETS_DIR/assets/js/**/*.js'],\n    },\n    styles: {\n        files: [\n            {\n                name: 'main.css',\n                files: [\n                    'PATH_TO_PROJECT_ASSETS_DIR/scss/main.scss',\n                ],\n                destDir: 'css'\n            }\n        ],\n        postCssPlugins: postCssPlugins,\n        sassCompiler: 'sass', // this passes Dart Sass to gulp-sass\n        watch: ['PATH_TO_PROJECT_ASSETS_DIR/scss/**/*.scss']\n    },\n    stylelint: {\n        files: [\n            'PATH_TO_PROJECT_ASSETS_DIR/scss/**/*.scss'\n        ],\n        destDir: 'PATH_TO_PROJECT_ASSETS_DIR/scss'\n    },\n\n    \"development\": (argv.env || process.env.APP_ENV || 'development') === 'development',\n    \"webdir\": \"www\",\n    \"libdir\": \"vendor\", // composer deps directory, might be called \"lib\"\n    \"tempdir\": \"tmp\",\n    \"npmdir\": \"node_modules\"\n}\n```\n\n## Options\n\n### SCSS/CSS pipeline\n\n#### Choose the Sass compiler\n\nFor backwards-compatibility reasons, the default compiler is LibSass via node-sass, [which has been deprecated by the Sass project](https://sass-lang.com/blog/libsass-is-deprecated). You can pick the canonical implementation (Dart Sass) by setting `sassCompiler` on the `styles` object in `gulp-config.js`. You will need to install the Dart Sass Node package via npm or yarn (`npm install sass` or `yarn add sass`).\n\nExample (excerpt from `gulp-config.js`):\n\n```js\n// […]\nstyles: {\n    files: [\n        …\n    ],\n    sassCompiler: 'sass', // this passes Dart Sass to gulp-sass\n    postCssPlugins: postCssPlugins,\n    watch: ['src/**/*.scss']\n},\n// […]\n```\n\n#### Custom include paths for SCSS\n\nYou can optionally pass include paths directly as a property of the `styles` object in `gulp-config.js` if you need more than the default `[config.npmdir]`:\n\nExample (excerpt from `gulp-config.js`):\n\n```js\n// […]\nstyles: {\n    files: [\n        …\n    ],\n    includePaths: ['PATH_TO_DEPENDENCIES_1', 'PATH_TO_DEPENDENCIES_2'],\n    postCssPlugins: postCssPlugins,\n    watch: ['src/**/*.scss']\n},\n// […]\n```\n\n#### PurgeCSS\n\n[PurgeCSS](https://purgecss.com/) is a tool to automatically remove unused CSS. webfactory-gulp-preset comes with \npostcss-purgecss preinstalled, but it is only activated if a `purgeCss` object is defined as a property of the \n`styles` object in `gulp-config.js`.\n\nAll documented options (for the PostCSS implementation) are supported. \n\nExample (excerpt from `gulp-config.js`):\n\n```js\n// […]\nstyles: {\n    files: [\n        {\n            name: 'main.css',\n            files: [\n                'PATH_TO_PROJECT_ASSETS_DIR/scss/main.scss',\n            ],\n            destDir: 'css'\n        }\n    ],\n    purgeCss: {\n        content: [\n            './src/PROJECT_TEMPLATES/**/*.twig',\n            './src/JS_COMPONENTS_THAT_USE_CSS_SELECTORS/**/*.js',\n            './vendor/PACKAGE/TEMPLATES/**/*.twig',\n        ],\n        safelist: ['ANY_VALID_CSS_SELECTOR']\n    },\n    postCssPlugins: postCssPlugins,\n    watch: ['src/**/*.scss']\n},\n// […]\n```\n\n#### PostCSS Preset Env\n\nPostCSS Preset Env lets us convert modern CSS into something the browsers targeted by our browserslist config can understand. We usually use default settings for PostCSS Preset Env, but you can pass a custom config by defining a `postCssPresetEnvConfig` object either on `styles` for all files or on a specific file.\n\nExample (excerpt from `gulp-config.js`):\n\n```js\n// […]\nstyles: {\n    files: [\n        {\n            name: 'custom.css',\n            files: [\n                'PATH_TO_PROJECT_ASSETS_DIR/scss/custom.scss',\n            ],\n            postCssPresetEnv: {\n              // options for postcss-logical in case you need to always output CSS for a vertical writing mode… \n              \"logical\": {\n                 \"inlineDirection\": \"bottom-to-top\",\n                 \"blockDirection\": \"right-to-left\"\n              },\n              // …for very old browsers \n              browsers: [\n                 'Chrome \u003e= 56',\n              ],\n            },\n            destDir: 'css',\n        }\n    ],\n    …\n},\n// […]\n```\n\n### JS pipeline\n\n#### Svelte\nThe Webpack Gulp task is preconfigured for compiling Svelte apps, but you need to require `svelte` and `svelte-loader` as a direct dependencies in your project to make it work. \n\nSpecify \n- the `svelteVersion` as a first-level property (string or number) in `gulp-config.js`, e.g. `svelteVersion: '4.2'` (you can supply a string or a number as long as the value can be transformed into a floating point by `parseFloat()`); the path to Svelte internals changed in v4 which is why the project needs to supply the Svelte version that is in use. If no `svelteVersion` is provided, this preset defaults to settings for version 3. \n- the entry point (.js file) as any other in `gulp-config.js`, \n\nand Webpack will auto-detect Svelte and know what to do.\n\n#### Custom paths for module resolving\nWebpack has defaults (like `node_modules`, for obvious reasons) for what directories should be searched when resolving modules. It's possible to pass through additional paths to the resolver; this can be helpful if you want to be able to `import` JS files from a Symfony bundle without having to supply a long and fragile relative path. To do so, add the following property to the scripts object:\n`resolveModulesPaths: ['www/bundles']`\n\nIn your project's JS file you can now import relative to the symlinked folder, i.e. `import 'webfactoryembed/js/embed.esm.js';`.\n\n#### Transpile packages from `node_modules`\nDue to performance reasons, `node_modules` is excluded from transpiling by default. To ensure backwards-compatibility you can whitelist certain modules from the exclusion. To do so, add the following property to the scripts object:  \n`includeModules: ['module_folder_name_1', 'module_folder_name_2']`\n\n#### [legacy] Don't use Webpack to bundle JavaScript modules\n\nAs of Version 2.9 the Webpack task is the standard for bundling Javascript modules. The \"old\" way of concatenating all JS is still usable, but needs some changes to your projects `gulpfile.js` and `gulp-config.js`. \nFrom version 2.2 onwards, webfactory-gulp-preset offers a Webpack task that can be invoked **instead of** the \"old\" way\nof concatenating all JS files listed in an array of input paths. The Webpack task can be configured with multiple entry \npoints and supports Svelte Apps and backwards-compatible builds with Babel out of the box.\n\nIf you dont't want to use Webpack, require the corrensponding task `sripts` and call it in the JS function in your Gulpfile instead of\n`webpack`:\n\n```js\nconst { scripts } = require('./node_modules/webfactory-gulp-preset/tasks/scripts');\n\nfunction js(cb) {\n    scripts(gulp, $, config);\n    cb();\n}\n```\n\nThe scripts object in `gulp-config.js` needs to be adapted as follows:\n\n```js\n// […]\nscripts: {\n    files: [\n        {\n            name: 'main.js',\n            files: [\n                '../node_modules/some-cool-package/cool-package.min.js',\n                'PATH_TO_PROJECT_ASSETS_DIR/js/my-cool-interactive-feature.js',\n            ],\n            destDir: 'js'\n        },\n        {\n            name: 'polyfills',\n            inputPath: 'bundles/app/js/object-fit-polyfill.js',\n            destDir: 'js'\n        },\n    ],\n    watch: ['…']\n},\n// […]\n```\n\n`scripts.js` should have top-level `import` statements to your JS modules/components, which can in turn contain further\n`import` statements to their respective dependencies.\n\n##### Convert (\"transcompile\") modern JavaScript to backwards compatible ES5 for older browsers\n\n[Babel](https://babeljs.io/) is a toolchain that is mainly used to convert ECMAScript 2015+ code into a backwards \ncompatible version of JavaScript in current and older browsers or environments. webfactory-gulp-preset comes with\nBabel preinstalled and preconfigured with the default `@babel/preset-env` preset. \n\n**Please note:** To save precious compile time, the Babel step is not run by default. Set `convertToES5` to `true` in \nthe config object of the JS files you want to transcompile back down to ES5.\n\nExample (excerpt from `gulp-config.js`):\n\n```js\n// […]\nscripts: {\n    files: [\n        {\n            name: 'script-for-old-browsers.js',\n            files: [\n                '../node_modules/some-cool-package/cool-package.min.js',\n                'PATH_TO_PROJECT_ASSETS_DIR/js/my-cool-interactive-feature.js',\n            ],\n            convertToES5: true,\n            destDir: 'js'\n        }\n    ],\n    watch: ['…']\n},\n// […]\n```\n\n### SVG optimizations\n\nFrom version 2.7 onwards, webfactory-gulp-preset offers a SVGMin task that can be used to optimize SVGs when they first\nenter the code base. The task uses a hardwired SVGO configuration that takes care of the risk of ID collisions across \ndifferent inline SVGs (i.e. multiple references to a clip-path by the same optimized ID \"a\") by replacing IDs with \nrandom strings. As this would generate changes every time the task is run, it is advisable to use CLI parameters to at \nscope the source file(s) per run. Files are overwritten by default, but a dest path can be passed if needed.\n\n```js\nconst {svgmin} = require(\"webfactory-gulp-preset/tasks/svgmin\");\n\nfunction svgo(cb) {\n    svgmin(gulp, $, config);\n    cb();\n}\n\nexports.svgo = svgo;\n```\n\n**Example CLI usage:**\n\nThe task uses root (`./`) as base for `gulp.src()`.\n\n```bash\ngulp svgo --src src/AppBundle/Resources/public/img/logo.svg\ngulp svgo --src www/bundles/app/img/logo.svg\n```\n\nPlease note: any kind of file globbing with `*` or `**` needs to be quoted on the command line.\n\n```bash\ngulp svgo --src \"src/AppBundle/Resources/public/img/icons/*.svg\"\ngulp svgo --src \"src/AppBundle/Resources/public/img/**/*.svg\"\n```\n\n```bash\ngulp svgo --src \"src/AppBundle/Resources/public/img/**/*.svg\" --dest tmp/svg-test/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebfactory%2Fwebfactory-gulp-preset","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebfactory%2Fwebfactory-gulp-preset","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebfactory%2Fwebfactory-gulp-preset/lists"}