gulp-importer

A simple gulp plugin that allows importing any kind of file to any kind of file. Nevertheless, gulp-importer looks up to the importing files and automatically updates dependency. So, when developing lib files other such, you don't have to go through every file that imports that lib and recompile it; instead, just let gulp-importer take care of it for you.

Note: If you experience any issues or come across some bugs, or even have a feature suggestion, feel free to open an issue or contribute if you'd like to.

Installation

To install the plugin, run the following command in your terminal:

npm install gulp-importer --save-dev

Usage

Execute Imports

Here you execute the imports in your files. gulp-importer supports both buffering and streaming with custom encoding. See Options for detailed configuration.

It's recommended that you also use a caching plugin like gulp-cached alongside gulp-importer to avoid unnecessarily repeat import execution.

const gulp     = require('gulp');
const cache    = require("gulp-cached");
const Importer = require('gulp-importer').default;

const importer = new Importer({
    encoding: "utf-8", // Check the available encodings in the options
    dependencyOutput: "dependant"
});

gulp.task('import', () => {
    return gulp.src('index.js')
    
        // Adding a caching step to the chain will prevent
        // unnecessary import executions.
        .pipe(cache("imports", {
            optimizeMemory: true
        }))
        .pipe(importer.execute()) // <-- Execute imports here
        .pipe(gulp.dest('./dist'));
});

Dependency Transformation New

Starting by version 1.5.0 the library supports alter pipelines for file dependencies.

gulp.task('import', () => {
    return gulp.src('*.js')
        .pipe(importer.execute(src => src.pipe(uglifyJs())))
        .pipe(gulp.dest('./dist'));

The dependency transformation only applies to the imported files.

Updating Dependency

Automatically execute imports for specific files when dependencies change. This saves you a lot of time from going through each file after a simple dependency change. So, we'll watch the resources that's supposed to be cached in the import step above. Why cached? Well, it's much faster to run the imports once and cache a dependency tree rather than looking up through a whole file tree, right?!

gulp.task('import', () => {
    return gulp.src('some-lib.js')
    
        // Again, it's useful to use caching to avoid
        // watching unchanged resources.
        .pipe(cache("imports", {
            optimizeMemory: true
        }))
        .pipe(importer.updateDependency()) // <-- Update dependency here
        .pipe(gulp.dest('./dist'));
});

gulp.task("watch", () => {
    gulp.watch("./lib/**/*.js", gulp.series("update"));
});

Note: Dependency update doesn't apply any imports on the primary file. It will go out the same as it was, coming in.

Options

Name	Type	Default	Info
encoding	ascii, utf8, utf-8, utf16le, ucs2, base64, base64url, latin1, binary, hex	utf-8	The encoding to be used for buffering and streaming.
importOnce	boolean	true	The flag indicates whether to ingore repeated import statements. In other words, a file can only be imported once
dependencyOutput	primary, all, dependant	primary	1. primary: Only the primary file will be piped out. 2. dependant: Only dependant files will be piped out. 3. all: The primary file and the dependant files will all be piped out. This option only applies in buffer mode, wherein stream mode, dependant files are always piped out.
disableLog	boolean	false	Disables the built-in log messages.
detailedLog	boolean	false	Provides detailed log messages describing each step taken through the process.
regexPattern	RegExp	/@{0,1}import\s+["']\s*(.*)\s*["'];{0,1}/gi	The regular expression pattern is used to place the import statements. Note that the "(.*)" part of the pattern is required, being pointing to the path. For example, the regex for (hello <./path/here>) is (/hello\s+<(.*)>/gi).
regexGroup	number	1	The index of the capturing group that represents the file path.
importRecursively	boolean	false	The flag indicates whether to recursively resolve nested imports. Which means that dependencies can also have dependencies.
requireExtension	boolean	true	The flag indicates whether to resolve extensionless files. So, instead of "./index.js", "./index" would do just fine.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT