Gulp Bundler with JSON Configuration

Common errors

• Error: Gulpfile not found

  cause The `gulpfile.js` or `gulpfile-config.json` file is missing from the project root, or `gulp` is being run from the wrong directory.
  fix Ensure `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

  cause 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.
  fix Install `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'

  cause The `gulpfile-config` package has not been installed as a dependency in your project.
  fix Install the package: `npm install gulpfile-config --save-dev`.

Warnings

• breaking The 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.
  Fix: Refer 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.
• gotcha The 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.
  Fix: For 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.
• gotcha This 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.
  Fix: Ensure `gulp-cli` version 4.0.0 or higher is installed globally. Verify with `gulp --version`.
• gotcha The 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.
  Fix: Use 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.

Install

• npm install gulpfile-config npm
• yarn add gulpfile-config yarn
• pnpm add gulpfile-config pnpm

Imports

• (Task Registration)
  wrong:

  import 'gulpfile-config';

  correct:

  require('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
  wrong:

  import config from 'gulpfile-config';

  correct:

  const config = require('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
  wrong:

  const { compile, bundle } = require('gulpfile-config');

  correct:
  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()`).

Quickstart

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