loadImage silent failure when sketch served from subpath in production

Handling Dynamic Asset Paths in p5.js

p5.js does not provide a built-in global configuration or runtime method to define a custom asset prefix. Because functions like loadImage() and loadSound() resolve paths relative to the document's base URL, sketches served from a subpath (e.g., /app/index.html) will fail to find assets located at /assets/ if the code assumes a root-level directory.

The Resilient Path Pattern

To ensure assets load correctly across both local development and production subpaths without hard-coding absolute URLs, use a dynamic base path variable. The most reliable method is to derive the path from the current window location or a data attribute in your HTML.

Implementation Example:

let assetPath = '';

function setup() {
  // Option A: Derive from a data attribute in HTML (Recommended)
  // <body data-asset-path="/app/assets/">
  const base = document.body.getAttribute('data-asset-path');
  assetPath = base ? base : 'assets/'; 
  
  createCanvas(400, 400);
} 

function preload() {
  // Concatenate the dynamic path with the filename
  img = loadImage(assetPath + 'image.png');
}

Explanation of Behavior

• Silent Failures: p5.js handles preload() asynchronously. If a 404 occurs, the library may not throw a visible console error that halts execution; instead, the sketch may simply fail to render the asset or hang indefinitely depending on the version and mode.
• Root-Relative vs. Relative: Paths starting with / are root-relative and will break on subpaths. Paths starting with assets/ are relative to the current URL, which may also break if the sketch is accessed via different routing levels.

CI Verification in Headless Environments

To verify asset resolution in a CI pipeline, use a headless browser (such as Playwright or Puppeteer) configured to serve the application from a simulated subpath. The test should:

1. Launch the application at the production-mimicking URL (e.g., http://localhost:8080/app/).
2. Intercept network requests or monitor the console.log for 404 errors.
3. Verify that the canvas element is populated or that specific image objects have a width > 0 after the setup() function completes.

Verification Steps

To diagnose current failures, open the Browser Developer Tools Network Tab and filter by Img or XHR. Compare the Request URL of the failed asset against the actual location of the file on your production server.

Note: Please specify if you are using p5.js in Global Mode or Instance Mode, as the scope of the assetPath variable will differ.