Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
(Task Registration)
✓ require('gulpfile-config');
✗ import 'gulpfile-config';
This library is primarily designed for CommonJS `gulpfile.js` files where `require` executes the module and registers Gulp tasks. Direct ESM `import` is not natively supported for gulpfiles without additional configuration and may not properly register tasks.
GulpfileConfigInstance
✓ const config = require('gulpfile-config');
✗ import config from 'gulpfile-config';
The package exports an instance of `GulpfileConfig` directly via `module.exports` for programmatic access. Use `require` to obtain this instance in CommonJS environments. There is no `default` export for ESM modules.
NamedExport
✓
✗ const { compile, bundle } = require('gulpfile-config');
The `gulpfile-config` package does not expose named exports. All functionality is either triggered by the initial `require` call (task registration) or accessed via methods on the single exported instance (e.g., `require('gulpfile-config').method()`).
This quickstart demonstrates how to set up a project using `gulpfile-config` to compile HTML, SCSS, and JavaScript, then serve the compiled assets with a development server using `gulp` commands.
// 1. Ensure Gulp CLI is installed globally: npm install gulp-cli -g
// 2. Initialize a new project and install dependencies
// mkdir my-project && cd my-project
// npm init -y
// npm install --save-dev gulp@^4.0.0 gulpfile-config@^1.0.0-alpha.23
// 3. Create 'gulpfile.js' in your project root:
// const gulp = require('gulp');
// require('gulpfile-config'); // This line registers all tasks defined in gulpfile-config.json
// 4. Create 'gulpfile-config.json' in your project root:
/*
{
"targets": {
"browser": {
"compile": [
{ "input": "src/**/*.html", "output": "dist/", "minify": true },
{ "input": "src/css/main.scss", "output": "dist/css/main.css", "minify": true },
{ "input": "src/js/main.js", "output": "dist/js/main.js", "minify": true }
]
}
},
"server": { "root": "./dist", "port": 3000 }
}
*/
// 5. Create example source files in a 'src' directory:
// src/index.html:
/*
<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Gulp Config Example</title><link rel="stylesheet" href="css/main.css"></head><body><h1>Hello, Gulpfile Config!</h1><script src="js/main.js"></script></body></html>
*/
// src/css/main.scss:
/*
$primary-color: #3498db; body { font-family: Arial, sans-serif; color: $primary-color; h1 { text-align: center; } }
*/
// src/js/main.js:
/*
document.addEventListener('DOMContentLoaded', () => { console.log('JavaScript loaded and DOM is ready!'); const heading = document.querySelector('h1'); if (heading) { heading.textContent += ' (from JS)'; } });
*/
// 6. Run Gulp tasks from your terminal in the project root:
// To build, serve, and watch: gulp
// To build only: gulp build
// To build CSS only: gulp buildCss
gulp --version
Debug
Known issues
breakingThe package is currently at version `1.0.0-alpha.23`, indicating it is pre-release software. API stability is not guaranteed, and breaking changes may occur without major version bumps.fixRefer to the project's CHANGELOG (if available) for specific changes when updating between alpha versions. Consider pinning to exact alpha versions to avoid unexpected changes.
affects: >=1.0.0-alpha.0
gotchaThe project appears to be abandoned or unmaintained, with the last commit dating back to December 2021. This means there is no active development, bug fixes, or security updates, making it unsuitable for new projects or production environments.fixFor new projects, consider modern, actively maintained alternatives for asset bundling (e.g., Vite, Webpack, Rollup, Parcel). For existing projects, evaluate the risks of using unmaintained software.
affects: >=1.0.0-alpha.23
gotchaThis utility requires Gulp CLI version 4.0.0 installed globally (`npm install gulp-cli -g`). If `gulp-cli` is not installed or an incompatible version is present, Gulp commands will not function correctly.fixEnsure `gulp-cli` version 4.0.0 or higher is installed globally. Verify with `gulp --version`.
affects: >=1.0.0-alpha.0
gotchaThe package specifies older Node.js engine compatibility (`^17 || ^16 || ^15.0.1 || ^14 || ^12`). It may not function correctly with newer Node.js versions (e.g., Node.js 18+ or 20+), potentially leading to unexpected errors or installation issues.fixUse a Node.js version manager (like `nvm`) to switch to a compatible Node.js environment (e.g., Node.js 16 or 17) if encountering issues with newer Node.js runtimes.
affects: >=1.0.0-alpha.0
Errors
Common errors & fixes
Error: Gulpfile not found
The `gulpfile.js` or `gulpfile-config.json` file is missing from the project root, or `gulp` is being run from the wrong directory.
fixEnsure `gulpfile.js` and `gulpfile-config.json` exist in the root of your project directory. Navigate to the correct project directory before running `gulp` commands.
TypeError: gulp is not a function
This error typically occurs if `gulp` (the package itself, not just `gulp-cli`) is not installed in your project, or if there's a version mismatch between `gulpfile-config`'s expectations and the installed `gulp` version.
fixInstall `gulp` locally in your project: `npm install gulp@^4.0.0 --save-dev`. Verify that `gulpfile-config` is correctly requiring and using the `gulp` instance.
Cannot find module 'gulpfile-config'
The `gulpfile-config` package has not been installed as a dependency in your project.
fixInstall the package: `npm install gulpfile-config --save-dev`.
Upgrade
Version history
1.0.0-alpha.23latest on npm
Audit
Dependencies
No dependency data recorded yet.