Path Loader

Common errors

• Error: The file loader is not supported in the browser environment.

  cause Attempting to use `loader.load()` with a local file path (e.g., `./data.json` or `file:///path/to/data.txt`) in a browser environment.
  fix Ensure that `path-loader` is only used with `http:` or `https:` URLs when running in a browser. Local files must be served via a web server.

• TypeError: loader.load is not a function

  cause This usually occurs if `path-loader` was not correctly `require`d, or if an older, incompatible version was installed that lacked the `load` method, or if trying to call `load` directly on the `path-loader` module instead of the returned `loader` object.
  fix Verify that `const loader = require('path-loader');` is used and then call `loader.load(path)`. Check `package.json` to ensure `path-loader` is listed as a dependency and `npm install` has been run.

• UnhandledPromiseRejectionWarning: (node:XXXXX) Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch().

  cause The `loader.load()` method returns a Promise, and if an error occurs during loading (e.g., file not found, network error), the promise will reject without an attached `.catch()` handler.
  fix Always attach a `.catch()` block to your `loader.load()` calls to handle potential errors gracefully. Example: `loader.load(path).then(res => ...).catch(err => console.error(err));`

Warnings

• gotcha The `file` loader, which is used by default in Node.js for local paths, is explicitly not supported in browser environments and will throw an error if attempted.
  Fix: In browser environments, only use `http:` or `https:` URLs. To load local files, consider a web server to serve them via HTTP or alternative browser-specific file APIs.
• breaking The package has been effectively abandoned since its last update in August 2016. This means it may not be compatible with newer Node.js versions, browser APIs, or modern JavaScript features. Its dependencies (`superagent`, `native-promise-only`) may also contain unpatched security vulnerabilities or have breaking changes in their own development, potentially leading to supply chain issues.
  Fix: For new projects, consider modern alternatives like `node-fetch` (Node.js) or the native `fetch` API (browser) for HTTP requests, and `fs.promises` (Node.js) for file system operations. If you must use `path-loader`, thorough security audits and compatibility testing are essential.
• deprecated The primary API pattern is CommonJS `require()`. While UMD builds are provided for browsers, modern module systems (ESM) are not natively supported, making integration into contemporary build pipelines less straightforward.
  Fix: For Node.js ESM projects, you might need a wrapper or dynamic import (`import('path-loader')`) if direct `require` is problematic. For browser ESM, a bundler like Webpack or Rollup would be necessary, but consider migrating to modern `fetch` or a actively maintained HTTP client library.

Install

• npm install path-loader npm
• yarn add path-loader yarn
• pnpm add path-loader pnpm

Imports

• loader
  wrong:

  import loader from 'path-loader';

  correct:

  const loader = require('path-loader');

  Primarily designed for CommonJS; direct ESM import not officially supported. For browser, it exposes a global `pathLoader`.
• pathLoader (global)

  <!-- In HTML after script tag -->
  <script src="path-loader.js"></script>
  <script>
    pathLoader.load('https://example.com/data.json')
      .then(console.log)
      .catch(console.error);
  </script>

  When used directly in a browser via a `<script>` tag, the utility is exposed as a global `pathLoader` object.
• load
  wrong:

  const load = require('path-loader').load;

  correct:

  const { load } = require('path-loader');

  The `loader` object returned by `require('path-loader')` has a `load` method. Destructuring can be used.

Quickstart

Demonstrates loading JSON content from a remote URL (works in browser and Node.js) and a local file (Node.js only) using the unified `loader.load` API.

const loader = require('path-loader');

// Example: Loading content from a remote URL
loader.load('https://jsonplaceholder.typicode.com/posts/1')
  .then(function (res) {
    console.log('Successfully loaded remote data:');
    console.log(JSON.parse(res.text));
  })
  .catch(function (err) {
    console.error('Error loading remote data:', err.message);
  });

// Example: Loading a local file (Node.js only)
// This will likely fail if the file does not exist or permissions are incorrect.
// In a real application, replace 'package.json' with a valid local path.
if (typeof window === 'undefined') { // Check if running in Node.js
  loader.load('./package.json')
    .then(function (res) {
      console.log('\nSuccessfully loaded local file:');
      console.log(JSON.parse(res.text));
    })
    .catch(function (err) {
      console.error('\nError loading local file:', err.message);
    });
}