{"id":21270432,"url":"https://github.com/dan503/gulp-auto-imports","last_synced_at":"2026-04-28T13:34:56.316Z","repository":{"id":47605725,"uuid":"149750226","full_name":"Dan503/gulp-auto-imports","owner":"Dan503","description":"Auto generate import-only files for any file type. SCSS, JS, TS, Pug, whatever you want.","archived":false,"fork":false,"pushed_at":"2021-08-22T10:53:01.000Z","size":1037,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-23T20:03:32.693Z","etag":null,"topics":["automated","automatic","automation","component-loader","file-loader","filesystem","gulp","gulp-plugin","loader","module-loader"],"latest_commit_sha":null,"homepage":"","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/Dan503.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":"2018-09-21T10:46:02.000Z","updated_at":"2022-09-07T23:19:08.000Z","dependencies_parsed_at":"2022-09-18T09:10:50.048Z","dependency_job_id":null,"html_url":"https://github.com/Dan503/gulp-auto-imports","commit_stats":null,"previous_names":["dan503/gulp-file-loader"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/Dan503/gulp-auto-imports","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dan503%2Fgulp-auto-imports","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dan503%2Fgulp-auto-imports/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dan503%2Fgulp-auto-imports/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dan503%2Fgulp-auto-imports/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dan503","download_url":"https://codeload.github.com/Dan503/gulp-auto-imports/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dan503%2Fgulp-auto-imports/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262614457,"owners_count":23337277,"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","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":["automated","automatic","automation","component-loader","file-loader","filesystem","gulp","gulp-plugin","loader","module-loader"],"created_at":"2024-11-21T08:17:26.347Z","updated_at":"2026-04-28T13:34:56.286Z","avatar_url":"https://github.com/Dan503.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gulp Auto Imports\n\n_Auto generate import-only files for any file type. SCSS, JS, Pug, whatever you want._\n\n[![Supported Node version](https://img.shields.io/node/v/gulp-auto-imports.svg?style=for-the-badge)](https://nodejs.org/en/)\n\nAre you sick of having to manually manage files that are purely just a bunch of import statements?\n\nWouldn't it be awesome if Gulp could just look at your file system and manage this busy work for you?\n\nThat is where Gulp Auto Imports comes in. Gulp Auto Imports will automatically manage these import-only files for you giving you more time to worry about the important stuff.\n\nDue to it's high level of customization, Gulp Auto Imports is able to generate any import file you can imagine. SCSS, JS, Pug, PHP, you name it, it can create an import file for it (assuming the language supports import functionality in some way).\n\nGulp Auto Imports also has the ability to remember the order that imports are declared in. If you have ever had any experience with glob-loading SCSS files, you will know the pain of trying to get `alpha.scss` to override styles in `beta.scss`. With Gulp Auto Imports, simply rearrange the import statements and you're done!\n\n\u003e **Note:** if using Gulp Auto Imports with Sass files, it is best used [_in combination_](#use-in-combination-with-gulp-sass-glob) with [Gulp Sass Glob](https://www.npmjs.com/package/gulp-sass-glob), not as a complete replacement for it.\n\n## Contents \u003c!-- omit in toc --\u003e\n\n-  [Before and after Gulp Auto Imports](#before-and-after-gulp-auto-imports)\n   -  [SCSS Before](#scss-before)\n   -  [SCSS After](#scss-after)\n   -  [JS before](#js-before)\n   -  [JS after](#js-after)\n-  [Install](#install)\n-  [Using the SCSS preset](#using-the-scss-preset)\n-  [Using the automated Gulp task generator function](#using-the-automated-gulp-task-generator-function)\n-  [Use in _combination_ with Gulp Sass Glob](#use-in-combination-with-gulp-sass-glob)\n   -  [Gulp 3 combination](#gulp-3-combination)\n   -  [Gulp 4 combination](#gulp-4-combination)\n   -  [Using a combination inside main.scss](#using-a-combination-inside-mainscss)\n-  [All available presets](#all-available-presets)\n   -  [Overriding a preset](#overriding-a-preset)\n-  [JS configuration examples](#js-configuration-examples)\n   -  [Rollup](#rollup)\n      -  [Rollup in Gulp 4](#rollup-in-gulp-4)\n      -  [Rollup in Gulp 3](#rollup-in-gulp-3)\n   -  [Browserify](#browserify)\n   -  [Making use of the generated JS file](#making-use-of-the-generated-js-file)\n-  [How to do custom configurations](#how-to-do-custom-configurations)\n   -  [Manual SCSS set up](#manual-scss-set-up)\n   -  [Manual JS set up](#manual-js-set-up)\n-  [Understanding the `format` and `template` settings](#understanding-the-format-and-template-settings)\n   -  [The `$name` placeholder](#the-name-placeholder)\n   -  [The `$fileName` placeholder](#the-filename-placeholder)\n   -  [The `$ext` placeholder](#the-ext-placeholder)\n   -  [The `$path` placeholder](#the-path-placeholder)\n   -  [The `$noExtPath` placeholder](#the-noextpath-placeholder)\n   -  [The `$dir` placeholder](#the-dir-placeholder)\n   -  [Using indents](#using-indents)\n-  [The `retainOrder` setting](#the-retainorder-setting)\n-  [Settings reference guide](#settings-reference-guide)\n-  [Change Log](#change-log)\n\n## Before and after Gulp Auto Imports\n\n### SCSS Before\n\n```scss\n// main.scss (manually edited)\n\n@import '../components/component-A/A.scss';\n@import '../components/component-B/B.scss';\n@import '../components/component-C/C.scss';\n@import '../components/component-D/D.scss';\n```\n\n### SCSS After\n\n```scss\n// main.scss (manually edited)\n\n@import './auto-imports.scss';\n```\n\n```scss\n// auto-imports.scss (auto-generated)\n// retains the order that imports are declared in if edited manually\n\n@import '../components/component-A/A.scss';\n@import '../components/component-B/B.scss';\n@import '../components/component-C/C.scss';\n@import '../components/component-D/D.scss';\n```\n\n### JS before\n\n```js\n// main.js (manually edited)\n\nimport $ from 'jquery'\n\nimport A from '../components/component-A/A.js'\nimport B from '../components/component-B/B.js'\nimport C from '../components/component-C/C.js'\nimport D from '../components/component-D/D.js'\n\n$(() =\u003e {\n   A()\n   B()\n   C()\n   D()\n})\n```\n\n### JS after\n\n```js\n// main.js (manually edited)\n\nimport $ from 'jquery'\n\nimport autoImports from './auto-imports.js'\n\n$(() =\u003e {\n   autoImports()\n})\n```\n\n```js\n// auto-imports.js (auto-generated)\n\nimport A from \"../components/component-A/A.js\";\nimport B from \"../components/component-B/B.js\";\nimport C from \"../components/component-C/C.js\";\nimport D from \"../components/component-D/D.js\";\n\nexport default function() {\n  A();\n  B();\n  C();\n  D();\n})\n```\n\n## Install\n\nInstall Gulp Auto Imports using the following command:\n\n```\nnpm install gulp-auto-imports --save-dev\n```\n\n---\n\nFor my examples, I am assuming that the project folder structure looks like this:\n\n```\n[root]\n|  source\n|  |  components\n|  |  |  [component-folders]\n|  |  |  |  [component-name].js\n|  |  |  |  [component-name].scss\n|  |  js\n|  |  |  auto-imports.js\n|  |  |  main.js\n|  |  scss\n|  |  |  config\n|  |  |  |  [scss-config-files]\n|  |  |  auto-imports.scss\n|  |  |  main.scss\n|  build\n|  |  assets\n|  |  |  css\n|  |  |  |  main.css\n|  |  |  js\n|  |  |  |  main.js\n| gulpfile.js\n```\n\n## Using the SCSS preset\n\nWriting out all of the required settings manually for this plugin can be a bit tiresome. As of version 2.0.0 I've included some common preset settings that you can use as defaults. All you need to do for a basic SCSS set up is the following. You will need the `gulp-sass` plugin for this to fully work. `npm i gulp-sass -D`).\n\n```js\nvar gulp = require('gulp')\nvar autoImports = require('gulp-auto-imports')\nvar sass = require('gulp-sass')\n\n// Preset SCSS gulp-auto-imports task\ngulp.task('sass:load', function () {\n   // Always relative to gulpfile.js even if this code is inside a folder\n   var dest = 'source/scss'\n   // Do not leave off the \"return\", it is vital!\n   return (\n      gulp\n         .src('./source/components/**/*.scss')\n         // Using the \"scss\" preset (\"dest\" must be provided here as well)\n         .pipe(autoImports({ preset: 'scss', dest: dest }))\n         .pipe(gulp.dest(dest))\n   )\n})\n\n/************\\\n    Gulp 4\n\\************/\n\n// Define a separate compile task\ngulp.task('sass:compile', function () {\n   return gulp\n      .src('source/scss/main.scss')\n      .pipe(sass())\n      .pipe(gulp.dest('build/assets/css'))\n})\n\n// make \"sass:load\" run before \"sass:compile\" when \"sass\" is run\ngulp.task('sass', gulp.series('sass:load', 'sass:compile'))\n\n// Watch for changes\ngulp.task('watch', function (done) {\n   gulp.watch('source/**/*.scss', gulp.series('sass'))\n   done()\n})\n\n/************\\\n    Gulp 3\n\\************/\n\n// Make \"sass\" dependent on \"sass:load\"\ngulp.task('sass', ['sass:load'], function () {\n   return gulp\n      .src('source/scss/main.scss')\n      .pipe(sass())\n      .pipe(gulp.dest('build/assets/css'))\n})\n\n// Watch for changes\ngulp.task('watch', function () {\n   gulp.watch('source/**/*.scss', ['sass'])\n})\n```\n\nThe `scss` preset will apply the following default settings:\n\n```js\n// scss preset default settings\n{\n  format: `@import '$path';`,\n  fileName: 'auto-imports.scss',\n  retainOrder: true,\n  header: `\n// This file is generated by gulp-auto-imports.\n// Save this file into source control.\n// You may rearrange the order of the imports however you like.\n// You may NOT make any other alterations to this file.\n`\n};\n```\n\nThe output of the example `'sass:load'` task will look something like this:\n\n```scss\n// This file is generated by gulp-auto-imports.\n// Save this file into source control.\n// You may rearrange the order of the imports however you like.\n// You may NOT make any other alterations to this file.\n\n@import '../components/A/A.scss';\n@import '../components/B/B.scss';\n@import '../components/C/C.scss';\n@import '../components/D/D.scss';\n```\n\nDue to the [`retainOrder: true` setting](#the-retainorder-setting), you can rearrange the output. Gulp Auto Imports will preserve the order when it recompiles.\n\n```scss\n// Rearrange the output and Gulp Auto Imports will preserve it\n// (Requires the `retainOrder` setting to be enabled)\n\n@import '../components/D/D.scss';\n@import '../components/A/A.scss';\n@import '../components/C/C.scss';\n@import '../components/B/B.scss';\n```\n\nIf you add a new file to the system (eg. a `../components/A/A-two.scss` file) gulp-auto-imports will aim to group it with the other files found in the same folder.\n\n```scss\n// gulp-auto-imports will aim to group new files with files found in the same folder\n\n@import '../components/D/D.scss';\n@import '../components/A/A.scss';\n@import '../components/A/A-two.scss'; // New file added\n@import '../components/C/C.scss';\n@import '../components/B/B.scss';\n```\n\nAdd this line to your main scss file to auto-loaded your component styles:\n\n```scss\n// Import the auto-imports.scss file from main.scss\n@import './auto-imports.scss';\n```\n\nYou can now auto-load all of you're component scss files while still retaining full control over CSS source order! 😃\n\n## Using the automated Gulp task generator function\n\nMaking a single auto-imports file is ok using the standard method, however when you start making more than one auto-import file, the process can become quite cumbersome. This is why Gulp Auto Imports also comes with a task generator to make generating multiple auto-import files super easy.\n\nFor this example, we are going to generate three separate auto-import files. One for `vars`, one for `mixins`, and one for `components`.\n\nHere is the full code:\n\n```js\nvar gulp = require('gulp')\nvar { createAutoImportTask } = require('gulp-auto-imports')\n\n// Create a function for generating auto-import gulp tasks\nconst createScssImporterTask = sourceFolder =\u003e\n   createAutoImportTask({\n      sourceFolder,\n      // [optional] default = *all files*; Restrict imports to only target files with a specific extension name\n      fileExtension: 'scss',\n      // [optional] use this to resolve task name conflicts\n      taskPrefix: 'compile',\n      // [optional] default = true; will ignore the generated import file\n      ignoreImporterFile: true,\n      // Same settings object that you apply to the main gulp task\n      importerSettings: {\n         preset: 'scss',\n         // Note: `dest` will default to the source folder unless you define it here\n         // The generated output file will be ignored\n      },\n   })\n\n// Destructure into separate importer and watcher tasks\nconst [scssVarsImporter, scssVarsImportWatcher] = createScssImporterTask(\n   './source/scss/config/vars'\n)\nconst [scssMixinsImporter, scssMixinsImportWatcher] = createScssImporterTask(\n   './source/scss/config/mixins'\n)\nconst [scssComponentsImporter, scssComponentsImportWatcher] =\n   createScssImporterTask('./source/scss/config/components')\n\n// Gulp 4\ngulp.task(\n   'scss-auto-imports',\n   gulp.parallel(\n      scssVarsImporter,\n      scssVarsImportWatcher,\n      scssMixinsImporter,\n      scssMixinsImportWatcher,\n      scssComponentsImporter,\n      scssComponentsImportWatcher\n   )\n)\n\n// Gulp 3\ngulp.task('scss-auto-imports', [\n   scssVarsImporter,\n   scssVarsImportWatcher,\n   scssMixinsImporter,\n   scssMixinsImportWatcher,\n   scssComponentsImporter,\n   scssComponentsImportWatcher,\n])\n```\n\nIf you don't want to write out all the task variables, you can also use destructuring as a shortcut.\n\n```js\n/**\n * Use array destructuring as a shortcut\n */\n\n// Gulp 4\ngulp.task(\n   'scss-auto-imports',\n   gulp.parallel(\n      ...createScssImporterTask('./source/scss/config/vars'),\n      ...createScssImporterTask('./source/scss/config/mixins'),\n      ...createScssImporterTask('./source/scss/config/mixins')\n   )\n)\n\n// Gulp 3\ngulp.task('scss-auto-imports', [\n   ...createScssImporterTask('./source/scss/config/vars'),\n   ...createScssImporterTask('./source/scss/config/mixins'),\n   ...createScssImporterTask('./source/scss/config/mixins'),\n])\n```\n\nIf you don't want to have gulp watch the files, simply don't pass the watcher into your gulp process.\n\n```js\n/**\n * Avoid watching files by not passing the generated watcher task into your main gulp process\n */\n\n// Destructure to extract only the build task\nconst [scssVarsImporter] = createScssImporterTask('./source/scss/config/vars')\nconst [scssMixinsImporter] = createScssImporterTask(\n   './source/scss/config/mixins'\n)\nconst [scssComponetsImporter] = createScssImporterTask(\n   './source/scss/config/mixins'\n)\n\n// Gulp 4 (no watching of files)\ngulp.task(\n   'scss-auto-imports',\n   gulp.parallel(scssVarsImporter, scssMixinsImporter, scssComponetsImporter)\n)\n\n// Gulp 3 (no watching of files)\ngulp.task('scss-auto-imports', [\n   scssVarsImporter,\n   scssMixinsImporter,\n   scssComponetsImporter,\n])\n```\n\nThe values that `createAutoImportTask` returns are two task names in the format demonstrated below:\n\n```js\nconst taskNames = createAutoImportTask({\n   sourceFolder: './path/to/sourceFolder',\n   fileExtension: 'fileExtension',\n   taskPrefix: 'taskPrefix',\n   importerSettings: {\n      preset: 'scss',\n   },\n})\n\ntaskNames ===\n   [\n      'taskPrefix:fileExtension:auto-imports:sourceFolder',\n      'taskPrefix:fileExtension:auto-imports-watcher:sourceFolder',\n   ]\n```\n\nMore details about the `createAutoImportTask` function are documented in the [createAutoImportTask.types.ts](https://github.com/Dan503/gulp-auto-imports/blob/master/createAutoImportTask.types.ts) file.\n\n## Use in _combination_ with [Gulp Sass Glob](https://www.npmjs.com/package/gulp-sass-glob)\n\nIf you are using Gulp Auto Imports to load scss files, it works best as a method used for loading your component files since those tend to require a specific order to work correctly.\n\nMost of the time, your config files (files that hold nothing but Sass variables) and helper files (mixins, utility classes etc.) don't need to retain their order. It is both easier and cleaner to use [Gulp Sass Glob](https://www.npmjs.com/package/gulp-sass-glob) to auto-load these types of files than it is to set up individual Gulp Auto Imports tasks for each of them.\n\n```\nnpm install gulp-sass-glob --save-dev\n```\n\n### Gulp 3 combination\n\n```js\n// Using Gulp Auto Imports in combination with Gulp Sass Glob in Gulp 3\n\nvar gulp = require('gulp')\nvar autoImports = require('gulp-auto-imports')\nvar sass = require('gulp-sass')\nvar sassGlob = require('gulp-sass-glob')\n\n// Gulp Auto Imports task\ngulp.task('sass:load', function () {\n   var dest = 'source/scss'\n   return gulp\n      .src('./source/components/**/*.scss')\n      .pipe(autoImports({ preset: 'scss', dest: dest }))\n      .pipe(gulp.dest(dest))\n})\n\n// Sass compile task (depends on 'sass:load' task)\ngulp.task('sass', ['sass:load'], function () {\n   return gulp\n      .src('source/scss/main.scss')\n      .pipe(sassGlob()) // Sass Glob\n      .pipe(sass())\n      .pipe(gulp.dest('build/assets/css'))\n})\n```\n\n### Gulp 4 combination\n\n```js\n// Using Gulp Auto Imports in combination with Gulp Sass Glob in Gulp 4\n\nvar gulp = require('gulp')\nvar autoImports = require('gulp-auto-imports')\nvar sass = require('gulp-sass')\nvar sassGlob = require('gulp-sass-glob')\n\n// Gulp Auto Imports task\ngulp.task('sass:load', function () {\n   var dest = 'source/scss'\n   return gulp\n      .src('./source/components/**/*.scss')\n      .pipe(autoImports({ preset: 'scss', dest: dest }))\n      .pipe(gulp.dest(dest))\n})\n\n// Sass compile task\ngulp.task('sass:compile', function () {\n   return gulp\n      .src('source/scss/main.scss')\n      .pipe(sassGlob()) // Sass Glob\n      .pipe(sass())\n      .pipe(gulp.dest('build/assets/css'))\n})\n\n// Combined sass compile task\ngulp.task('sass', gulp.series('sass:load', 'sass:compile'))\n```\n\n### Using a combination inside main.scss\n\n```scss\n/**********************\\\n    main.scss file\n\\**********************/\n\n// Use Gulp Sass Glob to load config and helper files\n@import 'vars/**/*.scss';\n@import 'mixins/**/*.scss';\n\n// Use the output from Gulp Auto Imports to load component files\n@import 'auto-imports.scss';\n```\n\n```scss\n/***************************\\\n    auto-imports.scss file\n  (automatically generated)\n\\***************************/\n\n@import '../components/one/one.scss';\n@import '../components/two/two.scss';\n@import '../components/three/three.scss';\n@import '../components/four/four.scss';\n```\n\n## All available presets\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/es6.js\"\u003ees6\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eImport a set of functions using ES6 \u003ccode\u003eimport\u003c/code\u003e syntax and then call them on page load (\u003ccode\u003eimport fileName from '../relative/path/fileName.js'\u003c/code\u003e; then after DOM load: \u003ccode\u003efileName()\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/es6_default_exports.js\"\u003ees6_default_exports\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eImport a bunch of ES6 JavaScript \u003cem\u003edefault\u003c/em\u003e exports and then export them all from one file (\u003ccode\u003eexport { default as fileName } from '../relative/path/fileName.js'\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/es6_named_exports.js\"\u003ees6_named_exports\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eImport a bunch of ES6 JavaScript \u003cem\u003enamed\u003c/em\u003e exports and then export them all from one file (\u003ccode\u003eexport { fileName } from '../relative/path/fileName.js'\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/es5.js\"\u003ees5\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eImport a set of functions using \u003ccode\u003erequire()\u003c/code\u003e and then call them on page load (\u003ccode\u003evar fileName = require('../relative/path/fileName.js')\u003c/code\u003e; then after DOM load: \u003ccode\u003efileName()\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/es5_default_exports.js\"\u003ees5_default_exports\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eImport a bunch of CommonJS \u003cem\u003edefault\u003c/em\u003e exports and then export them all from one file (\u003ccode\u003eexports.fileName = require('../relative/path/fileName.js')\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/es5_named_exports.js\"\u003ees5_named_exports\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eImport a bunch of CommonJS \u003cem\u003enamed\u003c/em\u003e exports and then export them all from one file (\u003ccode\u003eexports.fileName = require('../relative/path/fileName.js').fileName\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/ts.js\"\u003ets\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eImport a set of functions using TypeScript \u003ccode\u003eimport\u003c/code\u003e syntax and then call them on page load (\u003ccode\u003eimport fileName from '../relative/path/fileName'\u003c/code\u003e; then after DOM load: \u003ccode\u003efileName()\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/ts_default_exports.js\"\u003ets_default_exports\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eImport a bunch of TypeScript \u003cem\u003edefault\u003c/em\u003e exports and then export them all from one file (\u003ccode\u003eexport { default as fileName } from '../relative/path/fileName'\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/ts_named_exports.js\"\u003ets_named_exports\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eImport a bunch of TypeScript \u003cem\u003enamed\u003c/em\u003e exports and then export them all from one file (\u003ccode\u003eexport { fileName } from '../relative/path/fileName'\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/pug.js\"\u003epug\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eIntended for use with builds that use \u003ca href=\"https://pugjs.org/api/getting-started.html\"\u003ePug\u003c/a\u003e as the templating language (\u003ccode\u003einclude ../relative/path/fileName.pug\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/jade.js\"\u003ejade\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eFor use on projects that haven't upgraded their old \u003ca href=\"http://jade-lang.com/\"\u003eJade\u003c/a\u003e powered projects to \u003ca href=\"https://pugjs.org/api/getting-started.html\"\u003ePug\u003c/a\u003e yet (\u003ccode\u003einclude ../relative/path/fileName.jade\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/scss.js\"\u003escss\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eSass import statements that use the \u003ca href=\"https://sass-lang.com/guide\"\u003enewer SCSS style syntax\u003c/a\u003e (\u003ccode\u003e@import '../relative/path/fileName.scss';\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/sass.js\"\u003esass\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eSass import statements that use the \u003ca href=\"http://sass-lang.com/documentation/file.INDENTED_SYNTAX.html\"\u003eolder indented style syntax\u003c/a\u003e (\u003ccode\u003e@import ../relative/path/fileName.sass\u003c/code\u003e).\u003c/dd\u003e\n\n  \u003cdt\u003e\u003ca href=\"https://github.com/Dan503/gulp-auto-imports/blob/master/presets/stylus.js\"\u003estylus\u003c/a\u003e\u003c/dt\u003e\n  \u003cdd\u003eIntended for use with the \u003ca href=\"http://stylus-lang.com/\"\u003eStylus\u003c/a\u003e CSS generation language (\u003ccode\u003e@import '../relative/path/fileName.styl'\u003c/code\u003e).\u003c/dd\u003e\n\u003c/dl\u003e\n\nYou can browse the available presets and see what their settings look like in [the `presets` folder](https://github.com/Dan503/gulp-auto-imports/tree/master/presets). The presets are named after the file names in that folder.\n\nIf you would like other presets to be added, you can [log an issue](https://github.com/Dan503/gulp-auto-imports/issues/new) to request for a new preset to be added, or you can make a pull request to add one yourself.\n\n### Overriding a preset\n\nThe preset setting just tells Gulp Auto Imports what to use as the default settings.\n\nYou can override any of the preset settings by providing your own alternative setting. For example, to change the output file name, you can do this:\n\n```js\n// Overriding the default preset setting for \"fileName\"\n.pipe(autoImports({ preset: 'es6', fileName: 'different-file-name.js', dest: 'path/to/dest' }))\n```\n\n## JS configuration examples\n\nAdding this functionality to your JS compiler can be tricky since JS compilers generally don't run off typical gulp functionality for performance reasons.\n\n### Rollup\n\nRollup has a pretty straight forward integration. It is very similar to the Sass set up. It gets around the performance issues by allowing you to cache the last bundle that was generated.\n\nRunning `gulp start` will generate the auto imports, compile the JS, and then start watching files for changes.\n\n(Rollup by default does not bundle CommonJS `require()` statements).\n\n#### Rollup in Gulp 4\n\n```js\n'use strict';\n\n// Import the auto imports plugin\nvar autoImports = require('gulp-auto-imports');\n\nvar gulp = require('gulp');\nvar rollup = require('@rollup/stream');\nvar sourcemaps = require('gulp-sourcemaps');\nvar source = require('vinyl-source-stream');\nvar buffer = require('vinyl-buffer');\n\ngulp.task('js:load', function(){\n  const dest = './source/js';\n  return gulp.src([\n    './source/components/**/*.js',\n    // exclude files and folders starting with an underscore\n    '!./source/components/{**/\\_*,**/\\_*/**}',\n  ])\n    // Run the auto imports\n    .pipe(autoImports({ preset: 'es6', dest }))\n    .pipe(gulp.dest(dest));\n})\n\nvar cache;\ngulp.task('js:compile', function() {\n  return rollup({\n      // point to the entry file.\n      input: './source/js/main.js',\n\n      // use cache for better performance\n      cache: cache,\n\n      // Note: these options are placed at the root level in older versions of Rollup\n      output: {\n        // Output bundle is intended for use in browsers\n        // (iife = \"Immediately Invoked Function Expression\")\n        format: 'iife',\n\n        // Show source code when debugging in browser\n        sourcemap: true\n      }\n    })\n    .on('bundle', function(bundle) {\n      // update cache data after every bundle is created\n      cache = bundle;\n    })\n    // point to the entry file.\n    .pipe(source('main.js', './source/js'))\n    .pipe(buffer())\n    .pipe(sourcemaps.init({loadMaps: true}))\n    .pipe(sourcemaps.write('.'));\n\n    .pipe(gulp.dest('./build/assets/js'));\n});\n\ngulp.task('js', gulp.series('js:load', 'js:compile'));\n\ngulp.task('js:watch', function(done){\n  gulp.watch(['./source/**/*.js'], gulp.series('js'));\n  done();\n})\n\ngulp.task('start', gulp.series('js', 'js:watch'));\n```\n\n#### Rollup in Gulp 3\n\n```js\n'use strict'\n\n// Import the auto imports plugin\nvar autoImports = require('gulp-auto-imports')\n\nvar gulp = require('gulp')\nvar rollup = require('@rollup/stream')\nvar sourcemaps = require('gulp-sourcemaps')\nvar source = require('vinyl-source-stream')\nvar buffer = require('vinyl-buffer')\n\ngulp.task('js:load', function () {\n   const dest = './source/js'\n   return (\n      gulp\n         .src([\n            './source/components/**/*.js',\n            // exclude files and folders starting with an underscore\n            '!./source/components/{**/_*,**/_*/**}',\n         ])\n         // Run the auto imports\n         .pipe(autoImports({ preset: 'es6', dest }))\n         .pipe(gulp.dest(dest))\n   )\n})\n\nvar cache\ngulp.task('js', ['js:load'], function () {\n   return (\n      rollup({\n         // point to the entry file.\n         input: './source/js/main.js',\n\n         // use cache for better performance\n         cache: cache,\n\n         // Note: these options are placed at the root level in older versions of Rollup\n         output: {\n            // Output bundle is intended for use in browsers\n            // (iife = \"Immediately Invoked Function Expression\")\n            format: 'iife',\n\n            // Show source code when debugging in browser\n            sourcemap: true,\n         },\n      })\n         .on('bundle', function (bundle) {\n            cache = bundle\n         })\n         // point to the entry file.\n         .pipe(source('main.js', './source/js'))\n         .pipe(buffer())\n         .pipe(sourcemaps.init({ loadMaps: true }))\n         .pipe(sourcemaps.write('.'))\n         .pipe(gulp.dest('./build/assets/js'))\n   )\n})\n\ngulp.task('js:watch', function () {\n   gulp.watch(['./source/**/*.js'], ['js'])\n})\n\ngulp.task('start', ['js', 'js:watch'])\n```\n\n### Browserify\n\nBelow is a modified version of the of the [Gulp browserify + watchify recipe](https://github.com/gulpjs/gulp/blob/master/docs/recipes/fast-browserify-builds-with-watchify.md) that has Gulp Auto Imports installed.\n\nBrowserify gets around performance issues by using a special \"Watchify\" JS library instead of `gulp.watch()`. You specify an entry file. Watchify watches for any changes to files that are imported from that entry file. It will also watch for changes to files imported from those imported files (and so on and so on forever).\n\nThe code below will generate a new `auto-imports.js` file when it detects a JS file has been added to or removed from the components folder. The auto-generated `auto-imports.js` file is imported into the main entry js file meaning Watchify is watching it for changes. When the new `auto-imports.js` file is generated, Watchify detects that the file has changed. This triggers Watchify to initiate a Browserify rebundle.\n\nMost of the code below works in both both Gulp 3 and Gulp 4.\n\n```js\n'use strict'\n\n// Import the auto imports plugin\nvar autoImports = require('gulp-auto-imports')\n\nvar watchify = require('watchify')\nvar browserify = require('browserify')\nvar gulp = require('gulp')\nvar source = require('vinyl-source-stream')\nvar buffer = require('vinyl-buffer')\nvar log = require('gulplog')\nvar sourcemaps = require('gulp-sourcemaps')\n\nvar customOpts = {\n   // entry file defined here\n   entries: ['./source/js/main.js'],\n   debug: true,\n}\nvar opts = Object.assign({}, watchify.args, customOpts)\n\n// Watch for changes then bundle\nvar b = watchify(browserify(opts))\n\nb.on('update', bundle) // on any dep update, runs the bundler\nb.on('log', log.info) // output build logs to terminal\n\nfunction bundle() {\n   // Then bundle the code\n   return b\n      .bundle()\n      .on('error', log.error.bind(log, 'Browserify Error'))\n      .pipe(source('main.js'))\n      .pipe(buffer())\n      .pipe(sourcemaps.init({ loadMaps: true }))\n      .pipe(sourcemaps.write('./'))\n      .pipe(gulp.dest('./build/assets/js'))\n}\n\n// File loader Gulp task\ngulp.task('js:load', function () {\n   const dest = './source/js'\n   return (\n      gulp\n         .src([\n            './source/components/**/*.js',\n            // exclude files and folders starting with an underscore\n            '!./source/components/{**/_*,**/_*/**}',\n         ])\n         // Run the auto imports\n         .pipe(autoImports({ preset: 'es5', dest }))\n         .pipe(gulp.dest(dest))\n   )\n})\n\n///////////////////////////\n// Gulp 3 specific code //\n/////////////////////////\ngulp.task('js', ['js:load'], bundle) // so you can run `gulp js` to build the file\ngulp.task('watch', function () {\n   // Gulp 3 can't distinguish between 'add','unlink', and 'change' events\n   // so it also has to run on file changes\n   gulp.watch('./source/components/**/*.js', ['js:load'])\n})\n\n///////////////////////////\n// Gulp 4 specific code //\n/////////////////////////\ngulp.task('js', gulp.series('js:load', bundle)) // so you can run `gulp js` to build the file\ngulp.task('watch', function (done) {\n   var watcher = gulp.watch('./source/components/**/*.js')\n   //Gulp 4 has the advantage of only running when a file is added/removed, not changed\n   watcher.on('add', gulp.series('js:load'))\n   watcher.on('unlink', gulp.series('js:load'))\n   done()\n})\n```\n\n### Making use of the generated JS file\n\nNow that Gulp is set up to build a auto-imports JS file for you, import your generated file from main.js and call it as a function.\n\n```js\n// Import auto-imports.js inside main.js\nimport autoImports from './auto-imports.js' // ES6\nvar autoImports = require('./auto-imports.js') // ES5\n\ndocument.addEventListener('DOMContentLoaded', function () {\n   // Run the auto-imports code on page load\n   autoImports()\n})\n```\n\nNote that a typical component js file will need to export a function by default for this configuration to work.\n\n```js\n// component js file example\n\n/////////\n// ES6 //\n/////////\nexport default function on_page_load() {\n   // Place code here that you wish to run\n   // when the `autoImports()` function is called\n}\n\n/////////\n// ES5 //\n/////////\nmodule.exports = function on_page_load() {\n   // Place code here that you wish to run\n   // when the `autoImports()` function is called\n}\n```\n\n## How to do custom configurations\n\nNow that you know how to use presets, lets replicate some of these presets manually to show you how to use the plugin if the files you wish to load are not available as a preset.\n\n### Manual SCSS set up\n\nI'll use SCSS as an example first because it is both simple and popular.\n\nCreate a gulp task that looks like this:\n\n```js\n// Typical SCSS gulp-auto-imports task\n\nvar gulp = require('gulp')\nvar autoImports = require('gulp-auto-imports')\n\ngulp.task('sass:load', function () {\n   // Always relative to gulpfile.js even if this code is inside a folder\n   var dest = 'source/scss'\n\n   // Do not leave off the \"return\", it is vital!\n   return gulp\n      .src([\n         // These paths are always relative to gulpfile.js\n         './source/components/**/*.scss',\n         // Ignore files \u0026 folders that start with underscores\n         '!./source/{**/_*,**/_*/**}',\n      ])\n      .pipe(\n         autoImports({\n            // \"$path\" is replaced with a relative file path\n            format: '@import \"$path\";',\n            // destination folder (must match gulp.dest)\n            dest: dest,\n            // name of the output file\n            fileName: 'auto-imports.scss',\n            // Don't change the order that imports are currently in\n            retainOrder: true,\n            // Add a message to the top of the file\n            header: '// output from gulp-auto-imports',\n         })\n      )\n      .pipe(gulp.dest(dest))\n})\n```\n\nThe output of this Gulp task will look something like this:\n\n```scss\n// output from gulp-auto-imports\n@import '../components/A/A.scss';\n@import '../components/B/B.scss';\n@import '../components/C/C.scss';\n@import '../components/D/D.scss';\n```\n\n### Manual JS set up\n\nJS is slightly more complicated.\n\n```js\n// Typical JS gulp-auto-imports task\n\nvar gulp = require('gulp')\nvar autoImports = require('gulp-auto-imports')\n\n// Use an ES6 template literal for defining the template\n// Node has supported them natively ever since v4.0.0\nvar template = `\n$format[imports]\n\nexport default function(){\n$format[functions]\n}\n`\n\ngulp.task('js:load', function () {\n   var dest = 'source/js'\n\n   return gulp\n      .src([\n         './source/components/**/*.js',\n         // Ignore files \u0026 folders that start with underscores\n         '!./source/{**/_*,**/_*/**}',\n      ])\n      .pipe(\n         autoImports({\n            // Format is now split into an object holding named format strings\n            format: {\n               // \"$name\" is replaced with the name of the file\n               // \"$path\" is replaced with a relative path to the file\n               imports: 'import $name from \"$path\";',\n               // The indent is added here, not in the template\n               functions: '  $name();',\n            },\n            dest: dest,\n            fileName: 'auto-imports.js',\n            template: template,\n         })\n      )\n      .pipe(gulp.dest(dest))\n})\n```\n\nThe output from this task will look something like this:\n\n```js\n// Generated auto-imports.js file\n\nimport one from '../components/one/one.js'\nimport two from '../components/two/two.js'\nimport three from '../components/three/three.js'\nimport four from '../components/four/four.js'\n\nexport default function () {\n   one()\n   two()\n   three()\n   four()\n}\n```\n\n## Understanding the `format` and `template` settings\n\nIt is recommended that you use an ES6 Template Literal (the back tick style strings) for creating the template rather than regular strings. Template Literals will allow you to define the markup found inside the output file exactly as written in a single string. Regular strings don't accept new lines so it makes writing the template much more difficult.\n\nRemember that Template Literal's count all white space literally, so any white space you add to the template will appear in the final output. To avoid an odd looking output file, save the template to a `template` variable outside of the gulp task so that there is no indentation to the side of it.\n\nThe template works by replacing each `$format[formatName]` statement with a full list of imports formated in the specified way provided in the `format` object.\n\nIf the `format` setting is provided as a string, the `template` setting is ignored. If `format` is provided as an object, the `template` setting is required.\n\n### The `$name` placeholder\n\nThe `$name` placeholder in the `format` setting is replaced with the file name of the file. Any non-alphabetic and non-numeric characters are converted to underscores to prevent possible syntax errors.\n\n```\n./folder/path/gulp-auto-imports-is-awesome!123.js\n\n === converts to the $name ===\n\ngulp_auto_imports_is_awesome_123\n```\n\nIf there are duplicate file names, a number is added to the end of the name based on how many duplicates it has found to ensure that each name is unique.\n\n```\n./folder/one/thing.js\n./folder/two/thing.js\n\n === converts to the $name ===\n\nthing\nthing_1\n```\n\nThe `$name` placeholder is excellent for use cases where you need to assign an import path to a variable name.\n\nYou can use the `$name` placeholder as much as you like. That includes having the `$name` placeholder appear multiple times in a single format rule. The `$name` will always refer to the same import path.\n\n### The `$fileName` placeholder\n\nThe `$fileName` placeholder in the `format` setting holds the file name (excluding the extension) exactly as it is written.\n\n```\n// Assuming the full path is \"./path/to/file-name.ext\"\n$fileName = file-name\n```\n\n### The `$ext` placeholder\n\nThe `$ext` placeholder in the `format` setting holds the file extension.\n\n```\n// Assuming the full path is \"./path/to/file-name.ext\"\n$ext = ext\n```\n\nNote that you can get the full file name (including extension) by using this pattern in your `format` setting:\n\n```\n// Assuming the full path is \"./path/to/file-name.ext\"\n$fileName.$ext = file-name.ext\n```\n\n### The `$path` placeholder\n\nThe `$path` placeholder in the `format` setting is replaced with a relative path that goes from the auto-imports output file to the file that is being loaded in.\n\n```\n$path = ./path/to/file-name.ext\n```\n\n**Note 1:** only one out of `$path`, `$noExtPath`, and `$dir` can be declared in a single format rule and it can only be declared once.\n\n**Note 2:** The `retainOrder: true` setting only works with unaltered `$path` placeholders.\n\n### The `$noExtPath` placeholder\n\nThe `$noExtPath` placeholder in the `format` setting is exactly the same as `$path` except it will not add the file extension to the end.\n\n```\n$noExtPath = ./path/to/file-name\n```\n\n**Note 1:** only one out of `$path`, `$noExtPath`, and `$dir` can be declared in a single format rule and it can only be declared once.\n\n**Note 2:** The `retainOrder: true` setting is not compatible with the `$noExtPath` placeholder.\n\n### The `$dir` placeholder\n\nThe `$dir` placeholder in the `format` setting stands for \"directory\" and is essentially the same as `$path` except it does not include the file name or the extension.\n\n```\n// Assuming the full path is \"./path/to/file-name.ext\"\n$dir = ./path/to\n```\n\n**Note 1:** only one out of `$path`, `$noExtPath`, and `$dir` can be declared in a single format rule and it can only be declared once.\n\n**Note 2:** The `retainOrder: true` setting is not compatible with the `$dir` placeholder.\n\n### Using indents\n\nIf you want indenting, the **indenting should be added through the `format` setting** _not_ the `template` setting. If you indent the template, only the first item in the list will be indented. The rest will press hard up against the edge of the page.\n\nFor example, if you use this as your template:\n\n```js\n// How NOT to indent your template\n\nvar template = `\n$format[imports]\n\nexport default function(){\n    // Notice the indent here\n    $format[functions]\n}\n`\n```\n\nYou will end up with a JS file that looks like this:\n\n```js\n// The result of incorrect indentation\n\nimport one from '../components/one/one.js'\nimport two from '../components/two/two.js'\nimport three from '../components/three/three.js'\nimport four from '../components/four/four.js'\n\nexport default function () {\n   // Notice the indent here\n   one()\n   two()\n   three()\n   four()\n}\n```\n\nInstead, apply indentation through the `format` setting:\n\n```js\n//How to apply correct indentation\n\nvar template = `\n$format[imports]\n\nexport default function(){\n    // Notice the indent here\n$format[functions]\n}\n`;\n\n// ... other Gulp code ...\n\n.pipe(autoImports({\n  format: {\n    imports: 'import $name from \"$path\";',\n    // The indent is added here, not in the template\n    functions: '    $name();'\n  },\n  dest: dest,\n  fileName: 'auto-imports.js',\n  template: template\n}))\n```\n\nThat will produce the desired output:\n\n```js\n// The result of correct indenting\n\nimport one from '../components/one/one.js'\nimport two from '../components/two/two.js'\nimport three from '../components/three/three.js'\nimport four from '../components/four/four.js'\n\nexport default function () {\n   // Notice the indent here\n   one()\n   two()\n   three()\n   four()\n}\n```\n\n## The `retainOrder` setting\n\nI briefly touched on the `retainOrder` setting earlier, however there is a bit more to know about it.\n\nIn CSS, the order that styles are written in matters significantly. It is important that you are able to alter the order that files are loaded in if you wish to have full control over your CSS specificity.\n\nOther globing methods (eg. `@import \"../path/to/components/**/*.scss\";`) do not give you the ability to alter the order that the files are loaded in. You are generally restricted to loading files in alphabetical order. Gulp Auto Imports gives you back the ability to control the order that your CSS loads in with it's `retainOrder` setting (introduced in v2.0.0).\n\nBy default `retainOrder` is set to `false`. When `retainOrder` is set to `true`, Gulp Auto Imports will not alter the order of the existing `$path` placeholder import paths if you manually edit them yourself. Make sure that if you enable the `retainOrder` setting you **save the output file into source control**. This will ensure that your co-workers don't end up with a CSS file that is in a different order to yours.\n\nGulp Auto Imports will still delete old files from the list that don't exist any more.\n\nIf it detects that a new file is added to the system, Gulp Auto Imports will aim to keep that new file grouped with other files found in the same folder. (Prior to v2.1.0 it just dumped it at the bottom of the file). This means that new scss config file imports will be placed at the top of the auto-imports file with the other config files. This gives all your component files access to the new config settings without you having to make any alterations to the imports file.\n\nIt will not retain any comments or other alterations to the file. It will only retain the order that the imports were announced in.\n\n**Note:** The `retainOrder: true` setting only works if you use an unaltered `$path` placeholder. `$noExtPath`, and `$dir` are not supported.\n\n## Settings reference guide\n\nThe settings documentation can now be found in the [index.d.ts file](https://github.com/Dan503/gulp-auto-imports/blob/master/index.d.ts).\n\n## Change Log\n\nThe Change log can be viewed on the [Gulp Auto Imports GitHub releases](https://github.com/Dan503/gulp-auto-imports/releases) page.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdan503%2Fgulp-auto-imports","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdan503%2Fgulp-auto-imports","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdan503%2Fgulp-auto-imports/lists"}