StencilJS 'dist' vs 'dist-custom-elements': Resolving Asset URLs in Subpath Deployments

Handling Subpath Asset Resolution in StencilJS

StencilJS does not provide a built-in basePath or publicPath configuration in stencil.config.ts to globally rewrite asset URLs during the build process. When using the dist-custom-elements target, the browser resolves relative asset paths against the current page URL, not the location of the hosted JavaScript bundle. This is why assets load correctly in stencil dev (which uses a dedicated dev server) but fail with 404s when deployed to a subpath like /app/.

The Root Cause: Relative Path Resolution

In a production build, references to assets in your JSX/TSX templates are treated as static strings. If you use src="./assets/image.png", and your page is hosted at example.com/app/index.html, the browser attempts to fetch the image from example.com/app/assets/image.png. However, if your build artifacts are structured differently or hosted on a CDN, this path will be invalid.

Implementation Strategy for Subpaths

Since Stencil does not perform build-time URL transformations for these targets, you must implement a dynamic path resolution strategy. The most reliable method is to define a global configuration variable that is set at runtime or injected during your CI/CD pipeline.

1. Define a Base URL Variable: Create a utility or a global constant to hold your asset prefix.
2. Prefix Asset References: Update your component templates to use this prefix.

// src/utils/paths.ts
const ASSET_BASE_PATH = window.location.origin + '/app/build/assets/';

export const getAssetUrl = (path: string) => `${ASSET_BASE_PATH}${path}`;

In your component:

import { getAssetUrl } from '../../utils/paths';

render() {
  return <img src={getAssetUrl('logo.png')} />;
}

Verification Steps

• Inspect Production Bundles: Check the dist-custom-elements folder. Confirm that asset paths remain exactly as written in your source code; Stencil will not rewrite them automatically.
• Network Tab Audit: Deploy to your subpath and open the Browser DevTools Network tab. If you see 404s, check if the requested URL is relative to the page root rather than the asset folder.
• CDN Test: If using a CDN, replace the local path with the absolute CDN URL to verify the component renders correctly.

Required Diagnostic Detail

To provide a more tailored build-time transformation (such as a custom Webpack or Rollup plugin), please specify if you are using a custom build pipeline or relying solely on the stencil build command.