Jake

Common errors

• 'jake' is not recognized as an internal or external command, operable program or batch file.

  cause Jake is not installed globally or its installation directory is not in the system's PATH, or a local installation is not being invoked via `npx`.
  fix Install Jake globally (`npm install -g jake`) and ensure npm's global bin directory is in your system PATH, or install it locally (`npm install --save-dev jake`) and run tasks using `npx jake [taskName]`.

• SyntaxError: Cannot use import statement outside a module

  cause An `import` statement was used in a `Jakefile.js` or a module loaded by it, which Node.js is treating as a CommonJS module.
  fix Refactor the `Jakefile.js` and any directly loaded modules to use CommonJS `require()` syntax instead of ESM `import`. Jakefiles inherently run in a CJS context.

• Task not found: my-nonexistent-task

  cause The specified task name does not match any task defined in the `Jakefile.js`, or the `Jakefile.js` itself was not found or has syntax errors preventing task definition.
  fix Verify the task name spelling, ensure the `Jakefile.js` is in the current directory or specified with `-f`, and check the `Jakefile.js` for JavaScript syntax errors. Use `jake -T` to list available tasks.

• Error: asynchronous task function completed without calling 'complete()'

  cause An asynchronous task was defined (with `{ async: true }`) but did not call `this.complete()` at the end of its execution, causing Jake to detect an incomplete task.
  fix Ensure all asynchronous tasks explicitly call `this.complete()` after their operations have finished to signal completion to Jake.

Warnings

• gotcha Jakefiles are executed in a CommonJS context. Attempting to use ES Modules `import` syntax directly in a `Jakefile.js` will likely result in a `SyntaxError: Cannot use import statement outside a module` or similar, as Jake does not natively support ESM for task definition files.
  Fix: Always use CommonJS `require()` syntax for modules within your `Jakefile.js`. For core Jake API, prefer destructuring `require('jake')` or relying on globals if implicitly available in your specific Jake setup.
• breaking Jake drops support for older Node.js versions with major releases. Users should always check the `engines.node` field in `package.json` to ensure compatibility with their Node.js environment. Currently, Node.js `>=10` is required.
  Fix: Update your Node.js runtime to version 10 or newer. Refer to Jake's `package.json` for the exact minimum Node.js requirement.
• gotcha When defining asynchronous tasks, the task function *must* be marked with `{ async: true }` in its options object and *must* explicitly call `this.complete()` when the asynchronous work is finished. Failure to do so will result in Jake completing the task immediately, potentially before work is done, or hanging indefinitely.
  Fix: For any task involving asynchronous operations (e.g., `setTimeout`, `jake.exec` with callbacks, Promises), define it as `task('myTask', { async: true }, function () { /* ... async work ... */ this.complete(); });`.
• gotcha On Windows, global installation of Jake (e.g., `npm install -g jake`) has historically led to issues where the `jake` command is not recognized or behaves unexpectedly, potentially trying to run shell scripts. While some issues may be resolved, local installation (`npm install jake`) and execution via `npx jake` is often more robust.
  Fix: Consider installing Jake locally as a development dependency (`npm install --save-dev jake`) and invoking it using `npx jake [task]` from your project's root. If installing globally, ensure your system's PATH variable is correctly configured.
• gotcha When programmatically invoking tasks, `Task['my:task'].invoke()` will execute the task and its prerequisites only once, even if called multiple times within a build. If a task needs to be run multiple times, it must be 'reenabled' using `Task['my:task'].reenable()` before each subsequent invocation.
  Fix: Use `Task['my:task'].reenable()` before calling `Task['my:task'].invoke()` if the task needs to execute more than once within a single Jake run.

Install

• npm install jake npm
• yarn add jake yarn
• pnpm add jake pnpm

Imports

• desc, task, namespace
  wrong:

  import { desc, task, namespace } from 'jake';

  correct:

  const { desc, task, namespace } = require('jake');

  Jakefiles are typically executed in a CommonJS context. While `desc`, `task`, and `namespace` functions are often available implicitly as globals within a Jakefile, explicit `require` is the recommended and clearest approach, especially for programmatic use or when using other API methods. ESM `import` is not natively supported for Jakefiles and may lead to errors without transpilation.
• jake.exec
  wrong:

  import jake from 'jake'; jake.exec(...);

  correct:

  const jake = require('jake');
  jake.exec(['command'], { printStdout: true }, () => {
    console.log('Command finished.');
  });

  The `jake` object, containing utility methods like `exec` for running shell commands, `mkdirP`, `cpR`, etc., is accessed via `require('jake')` in a CommonJS context. Ensure to handle asynchronous `jake.exec` calls with a callback.
• Task['my:task'].invoke()
  wrong:

  const jake = require('jake'); jake.Task.invoke('my:task');

  correct:

  const { Task } = require('jake');
  Task['my:task'].invoke();

  To programmatically invoke a defined task (including its prerequisites), access it via `Task['namespace:taskName']`. The `Task` object is available from `require('jake')`.

Quickstart

This quickstart demonstrates how to define tasks and namespaces in a `Jakefile.js`, including prerequisites and an asynchronous task, and how to execute them from the command line.

/* Jakefile.js */
const { desc, task, namespace } = require('jake');

desc('This is the default task.');
task('default', function () {
  console.log('Running the default task.');
});

namespace('build', function () {
  desc('Cleans the build directory.');
  task('clean', function () {
    console.log('Cleaning build artifacts...');
    // Example: jake.rmRf('dist'); (requires 'jake' object)
  });

  desc('Compiles source files.');
  task('compile', ['build:clean'], function () {
    console.log('Compiling source...');
    // Simulate async operation
    setTimeout(() => {
      console.log('Compilation complete.');
      this.complete(); // Important for async tasks
    }, 1000);
  }, { async: true });

  desc('Lints JavaScript files.');
  task('lint', function () {
    console.log('Running linter...');
  });

  desc('Performs a full build, including linting.');
  task('all', ['build:lint', 'build:compile'], function () {
    console.log('Full build finished!');
  });
});

desc('Runs all tests.');
task('test', ['build:all'], function () {
  console.log('Running tests...');
});

// To run:
// npm install -g jake
// jake default
// jake build:all
// jake test