{"id":31128840,"url":"https://github.com/stnaire/gulp-yaml-packages","last_synced_at":"2026-05-03T22:32:49.981Z","repository":{"id":57259562,"uuid":"61872967","full_name":"Stnaire/gulp-yaml-packages","owner":"Stnaire","description":"Your gulpfile driven by a YAML configuration file.","archived":false,"fork":false,"pushed_at":"2019-04-15T21:30:16.000Z","size":3093,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-07T00:29:13.966Z","etag":null,"topics":["gulp-tasks","packages","yaml"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Stnaire.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-24T09:20:51.000Z","updated_at":"2019-04-15T21:30:18.000Z","dependencies_parsed_at":"2022-08-24T22:31:20.194Z","dependency_job_id":null,"html_url":"https://github.com/Stnaire/gulp-yaml-packages","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Stnaire/gulp-yaml-packages","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stnaire%2Fgulp-yaml-packages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stnaire%2Fgulp-yaml-packages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stnaire%2Fgulp-yaml-packages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stnaire%2Fgulp-yaml-packages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stnaire","download_url":"https://codeload.github.com/Stnaire/gulp-yaml-packages/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stnaire%2Fgulp-yaml-packages/sbom","scorecard":{"id":134554,"data":{"date":"2025-08-04","repo":{"name":"github.com/Stnaire/gulp-yaml-packages","commit":"7daed5f980fadd4df9446873fa90ecb8467d0831"},"scorecard":{"version":"v5.2.1-28-gc1d103a9","commit":"c1d103a9bb9f635ec7260bf9aa0699466fa4be0e"},"score":3,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#maintained"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#token-permissions"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#sast"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#signed-releases"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#license"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#vulnerabilities"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#branch-protection"}}]},"last_synced_at":"2025-08-16T06:09:02.587Z","repository_id":57259562,"created_at":"2025-08-16T06:09:02.587Z","updated_at":"2025-08-16T06:09:02.587Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275691395,"owners_count":25510531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-17T02:00:09.119Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["gulp-tasks","packages","yaml"],"created_at":"2025-09-18T01:06:24.393Z","updated_at":"2025-09-18T01:06:26.767Z","avatar_url":"https://github.com/Stnaire.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gulp yaml packages\nAllows you to define complex dependency tree with ease for all your projects.\nYou define packages and how they should be merged in a YAML file then the module generates corresponding gulp tasks for you.\n\n## Install\n\nInstall using node :\n```\nnpm install gulp-yaml-packages\n```\n\nAdd the module to your gulpfile.js : \n```javascript\nvar yamlPackages = require('gulp-yaml-packages');\n```\n\nIf you want to run the example, download the whole repository and do: \n* `$ bower install` to install vendor dependencies.\n* `$ gulp` to execute the gulpfile.\n\n## Options\n\n- **`--watch`** - To watch for changes on files declared on the .yml and rerun tasks automatically.\n- **`--env`** - Set the environment (if prod, scripts and styles will be uglified, if dev sourcemaps will be generated).\n- **`--theme`** - Theme name that can be used by packages with dynamic theme.\n- **`--strict`** - Check that all 'standalone' packages define an output for each input.\n- **`--verbose`** - To get more feedback on what is happening.\n\n\n## How does it work?\nInstead of manually writing tasks managing your resources, you define packages in a YAML configuration file.\nThe configuration file will be far more readable when your project uses a lot of resources with a complex dependency tree.\n\nThe YAML is then used to generate gulp tasks that you can execute in your gulpfile.\nHere an example on how to use it:\n\nWith `Gulp 3`:\n\n```javascript\n// gulpfile.js\n\nvar gulp = require('gulp');\nvar loader = require('gulp-yaml-packages');\nvar tasks = loader.load(__dirname+'/app/config/gulp_packages.yml', gulp);\n\ngulp.task('default', tasks);\n```\n\nWith `Gulp 4`:\n\n```javascript\n// gulpfile.js\n\nvar gulp = require('gulp');\nvar loader = require('gulp-yaml-packages');\nvar tasks = loader.loadForGulp4(__dirname+'/app/config/app.packages.yml', gulp);\n\ngulp.task('default', gulp.series(\n    gulp.series.call(gulp, tasks.series),\n    tasks.parallel.length ? gulp.parallel.call(gulp, tasks.parallel) : []\n));\n```\n\nSo first `gulp` is required, then `gulp-yaml-packages`.\nThe `load` method can take 3 arguments : \n\n- **`path`** - The **`absolute`** path to the YAML file to load. It's very important to give an **_absolute_** path here.\n- **`gulp`** - The `gulp` instance created in your gulpfile.js.\n- **`processors`** - (Optional) An object defining custom processors. You can define new processors or override internal ones. More info in the processors section.\n\nThe `load` method returns an array containing the name of tasks generated by the module.\nThis array is then passed as dependencies to the `default` gulp task so they are executed.\n\nIn `Gulp 4` an object containing two arrays is returned. It contains the following keys:\n  - **series**: for tasks that should be run in series\n  - **parallel**: for tasks that should be run in parallel (watch tasks)\n\nYou can still create your own tasks if you so desire, like: \n\nWith `Gulp 3`:\n\n```javascript\n// gulpfile.js\n\nvar gulp = require('gulp');\nvar loader = require('gulp-yaml-packages');\nvar tasks = loader.load(__dirname+'/app/config/gulp_packages.yml', gulp);\n\ngulp.task('myCustomTask', function() {\n    // Do some other work.\n});\n\ngulp.task('default', ['myCustomTask'].concat(tasks));\n```\n\nWith `Gulp 4`:\n\n```javascript\nvar gulp = require('gulp');\nvar loader = require('gulp-yaml-packages');\nvar tasks = loader.loadForGulp4(__dirname+'/app/config/gulp_packages.yml', gulp);\n\ngulp.task('myCustomTask', function(cb) {\n    // Do some other work.\n    cb();\n});\ngulp.task('default', gulp.series(\n    gulp.series.call(gulp, ['myCustomTask'].concat(tasks.series)),\n    tasks.parallel.length ? gulp.parallel.call(gulp, tasks.parallel) : []\n));\n```\n\n## Structure of the YAML\n\nThe YAML is divided in 4 main parts : \n\n- **`packages`** - This is where you define your resources and what should be done with them.\n- **`processors`** - Defines custom processing that should be done on resources. Each processor is simply a function that will be executed when the concerned resource is processed.\n- **`parameters`** - Inspired by Symfony parameters, allows you to define reusable strings.\n- **`imports`** - Allows you to import other YAML files into the current one.\n\n## Packages\n\nA basic package file is defined like this : \n\n```yaml\npackages:\n  # This is the package name\n  app:\n    # This is the type of resource\n    styles:\n      input: 'assets/less/my-private-file.less'\n      output: 'public/css/this-one-is-public.css'\n```\n\n3 types of resources are recognized : \n\n- **`styles`** - For css, less, sass, etc.\n- **`scripts`** - For js, ts, coffee, etc.\n- **`misc`** - For everything that is not a script or a style (images, pdf, etc.).\n\nThe difference is that `styles` and `scripts` are merged in a single output and uglified in production.\nAlso, a sourcemap is generated in development so you can keep debuggable resources while testing.\n\n`misc` files are only copied if you don't set any processor on them.\n\n### Glob patterns\n\nYou can set glob patterns as input :\n```yaml\npackages:\n  app:\n    styles:\n      input: 'assets/less/**/*.less'\n      output: 'public/css/this-one-is-public.css'\n```\n\nIn this case, every `.less` file in the `assets/less` folder will be compiled in `this-one-is-public.css`.\n\nWhen dealing with `misc` resources (like `images`), the structure of your folders after the **first** \"globstar\" (`/**/`) will be preserved.\nConsider the following example : \n\n```yaml\npackages:\n  app:\n    misc:\n      input: 'assets/images/**/*'\n      output: 'public/images'\n```\n\nWith a folder structure like this :\n\n```\n|-- assets\n|   |-- images\n|   |   |-- sub\n|   |   |   |-- other.png\n|   |   |-- cake.jpg\n```\n\nThe output will be : \n\n```\n|-- public\n|   |-- images\n|   |   |-- sub\n|   |   |   |-- other.png\n|   |   |-- cake.jpg\n```\n\n### Multiple input\n\nYou can set multiple input selectors for one output :\n```yaml\npackages:\n  app:\n    styles:\n      input:\n        - 'assets/less/**/*.less'\n        - 'assets/sass/**/*.scss'\n        - 'assets/css/specific.css'\n      output: 'public/css/everything-in-here.css'\n```\n\n### Basic dependencies\n\nPackages can depend on one another, use the `deps` key to define dependencies :\n\n```yaml\npackages:\n  # jQuery\n  jquery:\n    # Here the 'input' is implicit. You can also give an array of paths.\n    scripts: 'vendor/jquery/jquery.js'\n  \n  # Application\n  app:\n    # You can of course define an array of dependencies ([jquery, bootstrap, ...]).\n    deps: jquery\n    styles:\n      ...\n```\n\n### Versions \u0026 themes\n\nA package can define multiple versions. There are two criteria that define a version:\n\n- **`version`** - The version number of the package (1.2, 3.2.3, etc.). Only support digits for now (3.1b will throw an error).\n- **`theme`** - The package's theme name. Can be anything alphanumerical.\n\nFor example, to define two versions of jQuery:\n```yaml\npackages:\n  jquery:\n    -\n      version: 1.12.4\n      scripts: 'vendor/jquery-legacy/jquery.js'\n    -\n      version: 3.0.0\n      scripts: 'vendor/jquery/jquery.js'\n```\n\nTo define two different themes:\n\n```yaml\npackages:\n  bootstrap:\n    -\n      theme: default\n      styles: 'vendor/bootstrap/less/bootstrap.less'\n    -\n      theme: green\n      deps: 'bootstrap:default'\n      styles: 'assets/vendor/bootstrap/green-theme.less'\n```\n\nThis will merge `bootstrap.less` and `green-theme.less` together in a single output.\nPlease note the `bootstrap:default` in `deps`. This is how you specify a theme in a dependency.\n\nWhen importing a dependency, you can then ask for a minimum version:\n\n```yaml\npackages:\n  app:\n    deps: 'jquery#1.9'\n```\n\nThis will look for a `jquery` package with a version `\u003e= 1.9`. The closest one will be selected.\n\nYou can combine `theme` and `version` like this:\n\n```yaml\npackages:\n  app:\n    deps: 'bootstrap:green#3.3'\n```\n\nThis will look for a `bootstrap` package with a `green` theme and a version `\u003e= 3.3`.\n\n### Advanced dependencies\n\nYou can also require a package from another YAML file:\n\n```yaml\n# app/config/gulp_packages.yml\n\npackages:\n  app:\n    deps: 'app/config/vendor_packages.yml#jquery'\n    styles:\n      ...\n```\n\n```yaml\n# app/config/vendor_packages.yml\n\npackages:\n  jquery:\n    scripts: 'vendor/jquery/jquery.js'\n```\n\nHere the `jquey` package defined in `app/config/vendor_packages.yml` will be imported as dependency in the `app` package.\n\nYou can also use `theme` and `version` filters when importing a dependency:\n\n```yaml\npackages:\n  app:\n    deps: 'app/config/vendor_packages.yml#bootstrap:green#3.3.6'\n    styles:\n      ...\n```\n\n### Custom watches\n\nBy default, all files defined in your packages are automatically watched when the `--watch` option is set.\nBut, for example, `less` or `sass` files may `import` other files that are not defined in the yaml file, and so, not watched.\n\nTo solve this problem, you can add a `watch` key to your `styles` or `scripts` definitions: \n\n```yaml\npackages:\n  app:\n    styles:\n      watch: 'vendor/bootstrap/less/**/*.less'\n      input: 'vendor/bootstrap/less/bootstrap.less'\n```\n\nNow a change on any `less` file in the `vendor/bootstrap/less` folder will trigger the watcher.\nBut only `bootstrap.less` will be compiled and copied.\n\n## Parameters\n\nInspired by Symfony, parameters are a very basic replace by key thing.\nYou define them like this : \n\n```yaml\nparameters:\n  assets_dir: 'app/Resources/assets'\n  vendor_dir: 'app/Resources/vendor'\n  \npackages:\n  ...\n```\n\nAnd use them like this : \n\n```yaml\npackages:\n  app:\n    styles:\n      input: '%assets_dir%/styles/css/**/*.css'\n      output: 'web/css/frontend.css'\n```\n\nThe `%assets_dir%` will be replaced by `app/Resources/assets`.\n\nYou can also use parameters in parameters:\n\n```yaml\nparameters:\n  root_dir: '../../'\n  assets_dir: '%root_dir%/app/Resources/assets'\n  vendor_dir: '%root_dir%/app/Resources/vendor'\n```\n\nThey are two parameters that are always set internally:\n\n- **`_theme`** - The value is given by the `--theme` option. If the option is not set, the default value is `default`.\n- **`_env`** - The value is given by the `--env` option. If the option is not set, the default value is `dev`.\n\n**Note:** You can't override these values.\n\nThese parameters are useful to dynamically change a package theme for example.\n\nConsider the following example:\n\n```yaml\npackages:\n  bootstrap:\n    -\n      # Default theme (only styles for example). If no 'theme' key is defined, the value 'default' is set.\n      styles: 'vendor/bootstrap/less/bootstrap.less'\n    -\n      # 'default' theme is implicit.\n      deps: bootstrap\n      theme: red\n      styles: 'assets/vendor/bootstrap/less/my-RED-theme.less'\n    - \n      deps: bootstrap:default\n      theme: green\n      styles: 'assets/vendor/bootstrap/less/my-GREEN-theme.less'\n  \n  # And your application that uses that\n  app:\n    deps: bootstrap:red\n    styles:\n      output: 'web/css/output.css'\n      \n```\n\nHere 2 themes are defined for bootstrap, a `red` one and a `green` one. The application then uses the `red` theme.\nNot very exiting, but if you change the application dependency to : \n\n```yaml\n  app:\n    deps: bootstrap:%_theme%\n    styles:\n      output: 'web/css/output.css'\n```\n\nIt becomes more interesting as the `_theme` parameter is set by the `--theme` option.\n\nSo you can run : \n* `$ gulp --theme=green` to switch to the green theme in no time.\n\n## Processors\n\nProcessors are a set of callbacks you can use to make some custom processing on files.\n\nHere the list of built-in processors:\n\n- **`typescript`** - Compiles typescript files. Uses the `gulp-typescript` module (\u003ca href=\"https://github.com/ivogabe/gulp-typescript\" target=\"_blank\"\u003eGitHub\u003c/a\u003e).\n- **`coffee`** - Compiles coffee script files. Uses the `gulp-coffee` module (\u003ca href=\"https://github.com/contra/gulp-coffee\" target=\"_blank\"\u003eGitHub\u003c/a\u003e).\n- **`sass`** - Compiles sass files. Uses the `gulp-sass` module (\u003ca href=\"https://github.com/dlmanning/gulp-sass\" target=\"_blank\"\u003eGitHub\u003c/a\u003e).\n- **`less`** - Compiles less files. Uses the `gulp-less` module (\u003ca href=\"https://github.com/plus3network/gulp-less\" target=\"_blank\"\u003eGitHub\u003c/a\u003e).\n- **`cssurladjuster`** - Rewrite urls in css files. Uses the `gulp-css-url-adjuster` module (\u003ca href=\"https://github.com/trentearl/gulp-css-url-adjuster\" target=\"_blank\"\u003eGitHub\u003c/a\u003e).\n- **`image`** - Optimize images. Uses the `gulp-image-optimization` module (\u003ca href=\"https://github.com/firetix/gulp-image-optimization\" target=\"_blank\"\u003eGitHub\u003c/a\u003e).\n\nYou can assign a processor to a package using the key `processors`: \n\n```yaml\npackages: \n  app: \n    styles:\n      output: 'public/css/public-file.css'\n      input:\n        files:\n          - 'assets/less/first.less'\n          - 'assets/less/second.less'\n        processors: less\n```\n\nYou can define custom options like this:\n\n```yaml\npackages: \n  app: \n    styles:\n      output: 'public/css/public-file.css'\n      input:\n        files: 'assets/less/styles.less'\n        processors: \n          less: \n            option1: val1\n            option2: val2\n```\n\nOf course it's **very** annoying to type this for every package using a less file. So you can a global configuration using the global key `processors`:\n\n```yaml\n#\n# Defines that the 'sass' processor must be run\n# on every file having a 'sass' or 'scss' extension.\n#\nprocessors:\n  -\n    name: sass\n    extensions: [sass, scss]\n    options:\n      option1: val1\n\n#\n# Then define packages like before\n# Sass files will be automatically processed.\n#\npackages:\n  app:\n    styles:\n      output: 'public/css/public-file.css'\n      input:\n        - 'assets/less/first.scss'\n        - 'assets/less/second.scss'\n```\n\nNow both `scss` files will use the `sass` processor.\n\nNotice that the `processors` key is **an array**. It's very important as the array defines the **order of execution**.\n\nThen, each processor configuration can define the following attributes: \n- **`name`** - The name of your processor. That's the name you will refer to in your packages.\n- **`callback`** - (Optional) The name of the function **callback** to call when executing the processor. If not defined, takes the value of `name`. \n- **`extensions`** - (Optional) If defined, the processor will be automatically assigned to every file matching one of the extensions.\n- **`options`** - (Optional) Options object to send to the callback.\n\nThis configuration is already done internally for the built-in processors.\nSo any `.scss` or `.sass` file will be compiled using the `sass` processor, same goes for `less`, `typescript` and `coffee`.\n\n### Custom processors\n\nYou can very easily add your own logic by creating a custom processor. In your `gulpfile.js`, simply add a third argument to the `load` method:\n\n```javascript\n// gulpfile.js\n\nvar gulp = require('gulp');\nvar loader = require('gulp-yaml-packages');\nvar tasks = loader.load(__dirname+'/app/config/gulp_packages.yml', gulp, {\n    myCustomProcessor: function(stream, options) {\n        // Do some custom processing here\n        //\n        // \\!/ Be sure to return the stream or the pipeline will break.\n        // If you modify the stream, by doing a pipe for example, return the new one.\n        return stream;\n    }\n});\n\ngulp.task('default', tasks);\n```\n\nThen you can use it in any of your YAML files:\n\n```yaml\npackages:\n  app:\n    scripts:\n      input:\n        files: 'assets/js/need-processing.js'\n        processors: myCustomProcessor\n```\n\nYou can also define you want to apply it on every `.js` file like this:\n\n```yaml\nprocessors:\n  -\n    name: myCustomProcessor\n    extensions: js\n    options: ~\n```\n\n**Note:** Currently, the processor will only be applied to files defined in the YAML file defining the processor configuration. May have some improvement to do here, ideas are welcome.\n\n### Processors priority\n\nTo ensure processors are executed in a certain order, their configuration is defined as an array.\nThey are then executed in the order they were defined in the array.\n\nBuilt-in processors are executed in the following order:\n`typescript, coffee, sass, less, cssurladjuster, image`.\n\nIf you need to execute a custom processor before the `sass` processor for example, you can do:\n\n```yaml\nprocessors:\n  -\n    name: myCustomProcessor\n    options: ~\n  - sass\n  \npackages:\n  ...\n```\n\nThe `sass` processor here is only a string. This means you don't define a new configuration, but simply indicate the order of execution.\nThe new order of execution will be:\n`typescript, coffee, myCustomProcessor, sass, less, cssurladjuster, image`.\n\nNot defining the `sass` element will result in the following order:\n`typescript, coffee, sass, less, cssurladjuster, image, myCustomProcessor`.\n\n## Imports\n\nYou can import other YAML files to merge their packages with the current file:\n\n```yaml\nimports: '%vendor_dir%/vendor_packages.yml'\n\npackages:\n  app:\n    # jQuery is defined in 'vendor_packages.yml'\n    deps: jquery\n    scripts: 'web/js/app.js'\n```\n\nYou can import as many files as you want: \n\n```yaml\nimports: \n  - app/config/file1.yml\n  - other/file2.yml\n  \npackages:\n  ...\n```\n\nIf packages with the same are found, they will be added as new versions.\nFor example, writing :\n\n```yaml\n# app/config/vendors1.yml\n  \npackages:\n  jquery:\n    version: 1.12\n    scripts: ...\n```\n\n```yaml\n# app/config/vendors2.yml\n  \npackages:\n  jquery:\n    version: 3.0.0\n    scripts: ...\n```\n\n\n```yaml\n# app/config/gulp_packages.yml\n\nimports: \n  - app/config/vendors1.yml\n  - app/config/vendors2.yml\n\npackages:\n  ...\n```\n\nis the same as writing :\n```yaml\n# app/config/gulp_packages.yml\n\npackages:\n  jquery:\n    - \n      version: 1.12\n      scripts: ...\n    -\n      version: 3.0.0\n      scripts: ...\n```\n\n**Note:** processors and parameters are NOT merged. They are **local to the YAML file defining them**.\n\n## Advanced concepts\n\nHere are explained some more \"advanced\" functionality that can be useful in certain cases but are not important enough to discuss in the main part of the documentation.\n\n### Naming\n\nPackages' names are global by default. Defining packages with the same name in multiple files is the same as defining a package with multiple versions in a single file.\nYou can isolate a package name to its YAML file by adding the prefix `@`:\n\n```yaml\n# src/bundles/bundle1/config/bundle1_packages.yml\n\npackages:\n  '@main':\n    styles:\n      ...\n```\n\n```yaml\n# src/bundles/bundle2/config/bundle2_packages.yml\n\npackages:\n  '@main':\n    styles:\n      ...\n```\n\nHere we have 2 files defining a package named `main`. Without the `@` we would have two versions on the package available everywhere.\nWith the `@` we can only include these packages by directly referring to the YAML file:\n\n```yaml\n# app/config/gulp_packages.yml\n\npackages:\n  app:\n    deps: \n      - 'src/bundles/bundle1/config/bundle1_packages.yml#main'\n      - 'src/bundles/bundle2/config/bundle2_packages.yml#main'\n    styles:\n      ...\n```\n\n**Note:** when importing a YAML file using the `imports` key, packages prefixed with `@` are ignored.\n\n### Standalone\n\nEvery package with input files and an output will create gulp tasks.\nBut there are some cases where you may want to define a package without using it.\n\nImagine you create a `vendor_packages.yml` that follows you between your projects.\nIn this file you would like to define packages for all the libraries you usually use: \n\n\n```yaml\n# vendor_packages.yml\n\npackages:\n  jquery:\n    scripts: 'vendor/jquery/jquery.js'\n  bootstrap:\n    styles: 'vendor/bootstrap/less/bootstrap.less'\n    scripts: 'vendor/bootstrap/js/bootstrap.js'\n    misc:\n      input: 'vendor/bootstrap/fonts/**'\n      output: 'web/fonts/bootstrap'\n  angular:\n    ...\n  moment:\n    ...\n```\n\nBut in your current project, you don't use `bootstrap` and `jquery`, their files are not even present in your project.\n\nFor jquery it's all good, because you didn't define any `output` in the package. \nSo until another package include its resources by doing `deps: jquery` the package will not do anything.\n\nBut `bootstrap` is different, it has `misc` resources that must define an `output`. \nWhen the YAML file will be loaded, a gulp task will be generated and the fonts will be copied, event if none of your packages depend on `bootstrap`. \n\nYou can prevent this behavior by adding a `standalone` attribute to the package. It's value is `true` by default, which means the package is enough to generate output on its own.\nIf you set it to `false`, the package will only generate output when included in another package.\n\nSo :\n\n```yaml\n# vendor_packages.yml\n\npackages:\n  bootstrap:\n    standalone: false\n    styles: 'vendor/bootstrap/less/bootstrap.less'\n    scripts: 'vendor/bootstrap/js/bootstrap.js'\n    misc:\n      input: 'vendor/bootstrap/fonts/**'\n      output: 'web/fonts/bootstrap'\n```\n\nwill only generate output if another package do `deps: bootstrap`.\n\n### Advanced theming\n\nTo go further on the theming topic, I would like to share a technique I use to easily theme libraries.\n\nWhen you want to override styles of a library you have basically two solutions : \n\n-  Make a new stylesheet that will be loaded after the library one. In this file you'll override the parts you want to change.\n-  If your library is coded in `sass` or `less` ou can recompile it after changing some variables.\n\nWhen the first one is obvious, the second one can be trickier than it appear.\nI've came up with the following solution (depending on the language) :\n\n#### In SASS\n\nWith the following file in the role of the library :\n\n```sass\n// vendor/my-library/main.scss\n\n$primary-color: #ff0000 !default;\n\n.btn { background: $primary-color }\n```\n\nTo modify the button color without rewriting the `.btn` class or modifying the original file, you can simply create a new file :\n\n```sass\n// app/my-library-theme.scss\n\n// First, override the variable you want to change\n$primary-color: #00ff00;\n\n// Then import the original library file\n@import \"../vendor/my-library/main.scss\";\n```\n\nThis will work because of the `!default` attribute on the `$primary-color` variable which indicates the variable must be set only if it doesn't exist yet.\n\n#### In LESS\n\nIn LESS it's even more powerful as you can set variables **after** they have been used.\n\n```less\n// vendor/my-library/main.less\n\n@primary-color: #ff0000;\n\n.btn { background: @primary-color }\n```\n\nAnd the custom theme file :\n\n```less\n// app/my-library-theme.less\n\n// You can import the library BEFORE overriding its variables\n@import \"../vendor/my-library/main.less\";\n\n// This is legal, the previous import will use this value\n@primary-color: #00ff00;\n```\n\n#### The problem with packages\n\nBut by doing this, you're replacing a file of the library by one of your own (which then includes the library).\n\nIf you define your packages like I did in the \u003ca href=\"#versions--themes\"\u003eVersions \u0026 themes\u003c/a\u003e section, you'll have a problem.\n\nIf you define your library like this :\n\n```yaml\nmy-library:\n  -\n    theme: default\n    styles: 'vendor/my-library/main.less'\n  -\n    deps: 'my-library:default'\n    theme: green\n    styles: 'app/my-library-theme.less'\n```\n\nWhen you include `my-library:green` in a package, the library will be compiled and concatenated **`two times`** because files of the `green` and `default` themes will be merged and because `my-library-theme.less` do an `@import`.\n\nYou could remove the `deps` key and copy/paste common parts of the two packages, but its ugly and remove a lot of value to the module.\n\nThe easiest way I've found is to create a `shared` theme to centralise what is common between themes : \n\n```yaml\nmy-library:\n  -\n    theme: shared\n    scripts: ...\n    misc: ...\n  -\n    deps: 'my-library:shared'\n    theme: default\n    styles: 'vendor/my-library/main.less'\n  -\n    deps: 'my-library:shared'\n    theme: green\n    styles: 'app/my-library-theme.less'\n```\n\nLike this you can do `deps: 'my-library:green'` without having two copies of the styles.\n\n### Explicit globs\n\nAs described in the \u003ca href=\"#glob-patterns\"\u003eGlob patterns\u003c/a\u003e section, you can define a glob pattern as input of a package: \n\n```yaml\npackages:\n  app:\n    scripts:\n      input: 'assets/scripts/**/*.js'\n      output: 'public/js/this-one-is-public.js'\n```\n\nBut in certain cases, you may be tempted to use a very vague glob like this:\n\n```yaml\npackages:\n  app:\n    scripts:\n      input: 'assets/scripts/**'\n      output: 'public/js/this-one-is-public.js'\n```\n\nNEVER do this, because multiple problems can appear.\n\nFirst, if other file than a script file is put in the `scripts` directory, the sourcemap generator or uglifier may crash.\n\nBut even if you are 100% certain only scripts file will ever be in that directory, you may experience crashes anyway.\n\nFor example, if you use `PHPStorm` or `WebStorm`, temporary files may be created when the IDE is compiling your files.\nFor instance, when compiling a `demo.ts` file, the IDE will create a `demo.ts___jb_tmp___` file (probably to ensure no data are lost if an error occurs while compiling).\n\nThis file will only last for a very short time, but it's enough to trigger the watch, to start the task and include it file in the pipeline when resolving the glob.\nIf you're unlucky, this file may be removed by the IDE before then end of the processing, and you'll get a fatal exception like : \n\n```\nevents.js:141\n      throw er; // Unhandled 'error' event\n      ^\n\nError: ENOENT: no such file or directory, stat '/app/Resources/assets/scripts/ts/demo.ts___jb_tmp___'\n  at Error (native)\n```\n\nTo prevent this, always filter your globs by extensions. `scripts/**/*.js`.\nIf you have multiple extensions, simply do: `scripts/**/*.{ts,js,coffee}`.\n\nHope it helps.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstnaire%2Fgulp-yaml-packages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstnaire%2Fgulp-yaml-packages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstnaire%2Fgulp-yaml-packages/lists"}