Olo Gulp Build Helpers

Common errors

• Error: Cannot find module 'olo-gulp-helpers'

  cause Package not installed or incorrect path in `require` statement.
  fix Run `npm install olo-gulp-helpers` or `yarn add olo-gulp-helpers` in your project. Ensure the `require` path is correct.

• No command 'gulp' found

  cause Gulp CLI is not globally installed or not in your system's PATH.
  fix Install Gulp CLI globally: `npm install -g gulp-cli`. If it's installed, verify your system's PATH environment variable.

• TypeError: oloGulpHelpers.setupWebpack is not a function

  cause Attempting to call a helper function that either doesn't exist, is misspelled, or is not exported by the package.
  fix Verify the correct function name and its export status. Review the `olo-gulp-helpers` source code or internal documentation for available exports and their signatures.

• Webpack compilation failed: 'sinon' module not found

  cause Webpack is failing to resolve or properly ignore the 'sinon' module, potentially due to incorrect configuration or a regression of the path separator issue mentioned in v0.2.2.
  fix Ensure `olo-gulp-helpers` is at least version 0.2.2. Check Webpack configuration for proper aliasing or externalization of `sinon` if it's not meant to be bundled.

Warnings

• breaking The package's stated version (0.9.1) significantly diverges from its public release history (up to 0.2.3). This suggests potential undocumented breaking changes or features introduced in intermediate versions which are not publicly detailed, making upgrades or initial integration unpredictable.
  Fix: Thoroughly review internal Olo documentation or source code for changes between major/minor versions. Consult Olo's internal teams for guidance on upgrading.
• gotcha This package is specifically designed for 'Olo's gulp build pipeline' and 'ASP.NET sites'. It likely contains strong opinions, hardcoded paths, or specific configurations tailored to Olo's internal infrastructure. Using it outside of Olo's intended environment may lead to unexpected behavior or require significant customization.
  Fix: Evaluate the source code for hardcoded assumptions or dependencies on Olo-specific tools/environments. Be prepared to fork and modify for external use cases, or consider a more generic Gulp helper.
• gotcha Version 0.2.2 fixed a 'path separator issue that prevented Sinon from being properly ignored by Webpack on Windows'. Older versions of this helper might exhibit cross-platform build failures, particularly on Windows, due to path resolution inconsistencies.
  Fix: Ensure you are using at least version 0.2.2 or later. If maintaining older versions, explicitly test builds on all target operating systems (Linux, macOS, Windows) and consider manual path normalization within custom configurations.
• breaking The underlying Gulp ecosystem has evolved, with Gulp 4 and 5 introducing significant breaking changes (e.g., `gulp.task` API, series/parallel composition, Node.js version requirements). Older versions of `olo-gulp-helpers` may be incompatible with newer Gulp CLI or core library versions.
  Fix: Confirm compatibility with your installed Gulp version. If encountering issues, check the `package.json` for `gulp` peer dependencies (if any) or consult Olo's internal guidance on compatible Gulp versions.

Install

• npm install olo-gulp-helpers npm
• yarn add olo-gulp-helpers yarn
• pnpm add olo-gulp-helpers pnpm

Imports

• oloGulpHelpers
  wrong:

  import oloGulpHelpers from 'olo-gulp-helpers';

  correct:

  const oloGulpHelpers = require('olo-gulp-helpers');

  Primarily designed for CommonJS environments typical of Gulpfiles. ESM imports are generally not the intended usage.
• setupWebpack
  wrong:

  import { setupWebpack } from 'olo-gulp-helpers';

  correct:

  const { setupWebpack } = require('olo-gulp-helpers');

  Assumed named export for a specific helper function; actual exports may vary. ESM is generally not supported for older Gulp helpers.
• defineBundlingTasks
  wrong:

  import defineBundlingTasks from 'olo-gulp-helpers/bundling';

  correct:

  const { defineBundlingTasks } = require('olo-gulp-helpers');

  Hypothetical named export for defining common bundling tasks. Direct subpath imports are unlikely unless explicitly documented.

Quickstart

Demonstrates a basic Gulpfile setup using `olo-gulp-helpers` to configure Webpack and define bundling and watch tasks for scripts and styles.

const gulp = require('gulp');
const { setupWebpack, defineBundlingTasks } = require('olo-gulp-helpers');

// Define paths for your project assets
const paths = {
  scripts: 'src/scripts/**/*.js',
  styles: 'src/styles/**/*.scss',
  output: 'dist'
};

// Setup Webpack configuration using Olo's helpers
const webpackConfig = setupWebpack({
  entry: './src/index.js',
  output: { path: paths.output, filename: 'bundle.js' },
  // Optionally pass environment variables, e.g., for API keys
  apiUrl: process.env.API_URL ?? '' 
});

// Define Gulp tasks using Olo's bundling helpers
const { compileScripts, compileStyles, watchFiles } = defineBundlingTasks(gulp, paths, webpackConfig);

// Export public tasks
exports.scripts = compileScripts;
exports.styles = compileStyles;
exports.watch = watchFiles;
exports.default = gulp.series(compileStyles, compileScripts, watchFiles);