RequireJS

Common errors

• Mismatched anonymous define() modules

  cause Multiple `define()` calls without module IDs in a single file or incorrect module loading order in optimized builds.
  fix Ensure each AMD module file contains only one top-level `define()` call. For optimized builds, consider using the optimizer's naming conventions or ensuring `name` configuration is correct to prevent anonymous modules from clashing.

• Load timeout for modules: [module-name]

  cause RequireJS could not load the specified module within the configured `waitSeconds`. Common causes include incorrect paths, server issues (404s), or script errors preventing execution.
  fix Check the module's path in your `requirejs.config({ paths: ... })`. Verify the file exists and is accessible. Inspect browser developer tools (Network tab) for 404 errors or console for script errors in the module. Increase `waitSeconds` in `requirejs.config` if the script legitimately takes longer to load (e.g., `waitSeconds: 200`).

• require is not defined

  cause This error typically occurs when using Node.js's CommonJS `require()` function in a browser environment without a bundler, or when attempting to use RequireJS's AMD `require()` without the `require.js` script being loaded in the HTML.
  fix In browsers, ensure `require.js` is loaded via a `<script>` tag before any AMD modules, and use its `require()` or `define()` for modules. In Node.js, use `const module = require('module');` for CommonJS modules, and the `requirejs` package's configured instance for AMD modules.

• Error evaluating module [module-name]

  cause A runtime JavaScript error (e.g., syntax error, uncaught exception) occurred within the `define()` function's factory callback for the specified AMD module.
  fix Inspect your browser's console or Node.js terminal for the full stack trace. The error message should point to the file and line number where the issue originated, indicating a bug within your module's logic.

Warnings

• deprecated The AMD (Asynchronous Module Definition) module format, championed by RequireJS, is largely superseded by native ES Modules (ESM) for new JavaScript projects in both browser and Node.js environments. ESM offers static analysis, tree-shaking, and standardized syntax.
  Fix: For new projects, consider using native ES Modules (`import`/`export`) or CommonJS (`require`/`module.exports`) depending on your target environment and existing codebase. Modern bundlers like Webpack, Rollup, or Vite can handle ESM efficiently.
• gotcha When using `requirejs` in Node.js, there's a distinction between Node's native CommonJS `require()` function and RequireJS's AMD `require()` function. Without proper configuration (`nodeRequire`), RequireJS may not correctly resolve modules intended for Node's CommonJS system.
  Fix: When initializing RequireJS in Node, pass Node's `require` function to the `nodeRequire` configuration option: `requirejs.config({ nodeRequire: require });` This allows RequireJS to fall back to Node's module loader if an AMD module is not found.
• security RequireJS versions up to 2.3.6 (and 2.3.7 for browser-only usage) were affected by a prototype pollution vulnerability. This could allow attackers to inject arbitrary properties into JavaScript object prototypes.
  Fix: Upgrade to RequireJS version 2.3.8 or later to mitigate the prototype pollution vulnerability. If an upgrade is not immediately possible, apply a global shim to prevent prototype pollution.
• gotcha The RequireJS optimizer (`r.js`) does not support building with network paths for modules. All resources must be local files.
  Fix: Ensure all module paths in your build configuration are relative to the `baseUrl` or `mainConfigFile` and point to local files. If you have external dependencies, configure them as module names and map them to local files or use a different build strategy for those parts.
• gotcha Using `shim` configuration to manage non-AMD scripts (e.g., older 'browser globals' libraries) is primarily for browser environments. The `shim` config is not fully supported or reliable when running RequireJS in Node.js, and may lead to unexpected behavior or warnings.
  Fix: Avoid using `shim` configuration when running RequireJS within a Node.js environment. If you need to include non-AMD libraries, consider using a separate CommonJS-compatible version if available, or isolate their usage to the browser build. RequireJS will log a warning about `shim` config in Node, which can be suppressed with `requirejs.config({ suppress: { nodeShim: true }});`.

Install

• npm install requirejs npm
• yarn add requirejs yarn
• pnpm add requirejs pnpm

Imports

• requirejs
  wrong:

  import requirejs from 'requirejs';

  correct:

  const requirejs = require('requirejs');

  This is the CommonJS entry point for the Node.js adapter, providing access to the RequireJS configuration and optimizer. Direct ES Module `import` syntax is not typically supported without a CommonJS wrapper or bundler.
• define
  wrong:

  const define = require('requirejs').define;

  correct:

  // In an AMD module file:
  define(['dependency'], function(dependency) { /* ... */ });

  `define` is a global function made available by the RequireJS runtime (e.g., when `require.js` or `r.js` is loaded) for defining Asynchronous Module Definition (AMD) modules. It is not directly imported from the `requirejs` npm package but is part of the environment it creates.
• require
  wrong:

  const require = require('requirejs').require;

  correct:

  // In an AMD module file:
  require(['dependency'], function(dependency) { /* ... */ });

  The `require` function in the context of RequireJS is used to load AMD modules asynchronously. It is a global function provided by the RequireJS runtime, distinct from Node.js's native CommonJS `require` function. When using the `requirejs` Node adapter, you can also use `requirejs(['module-id'], callback)` after configuration.

Quickstart

This quickstart demonstrates how to use the `requirejs` npm package in Node.js to load a simple AMD module and programmatically run the `r.js` optimizer to bundle modules.

const requirejs = require('requirejs');
const path = require('path');
const fs = require('fs');

// 1. Define sample AMD modules
fs.writeFileSync('dep.js', `define(function() { return { value: 'I am a dependency!' }; });`);
fs.writeFileSync('main.js', `define(['./dep'], function(dep) { return { message: 'Hello from main! Dep says: ' + dep.value }; });`);

// 2. Configure requirejs for Node.js to load AMD modules
requirejs.config({
  baseUrl: __dirname, // Current directory as base for AMD modules
  nodeRequire: require // Pass Node's require to enable fallback for non-AMD modules
});

// 3. Load an AMD module using the configured requirejs instance
requirejs(['main'], function(mainModule) {
  console.log('AMD Module loaded:', mainModule.message);
});

// 4. Using the optimizer programmatically
const buildConfig = {
  baseUrl: __dirname,
  name: 'main', // The main module to optimize
  out: path.join(__dirname, 'main-built.js'), // Output file
  optimize: 'none', // For demonstration, keep it unminified
  paths: {
    dep: './dep' // Ensure optimizer knows about relative paths
  }
};

requirejs.optimize(buildConfig, function (buildResponse) {
  console.log('\n--- Build Optimization Complete ---');
  console.log(buildResponse);
  const builtContent = fs.readFileSync(buildConfig.out, 'utf8');
  console.log('\nContent of main-built.js (first 500 chars):\n', builtContent.substring(0, 500), '...');

  // Clean up generated files
  fs.unlinkSync('dep.js');
  fs.unlinkSync('main.js');
  fs.unlinkSync('main-built.js');

}, function (err) {
  console.error('\nRequireJS Optimizer Error:', err);
  // Clean up in case of error too
  if (fs.existsSync('dep.js')) fs.unlinkSync('dep.js');
  if (fs.existsSync('main.js')) fs.unlinkSync('main.js');
  if (fs.existsSync('main-built.js')) fs.unlinkSync('main-built.js');
});