feat(setAssetPath): customize path of asset base urls

src/compiler/output-targets/dist-custom-elements-bundle/custom-elements-types.ts

@@ -39,6 +39,17 @@ const generateCustomElementsTypesOutput = async (
     ` */`,
     `export declare const defineCustomElements: (opts?: any) => void;`,
     ``,
+    `/**`,
+    `* Used to manually set the base path where assets can be found.`,
+    `* If the script is used as "module", it's recommended to use "import.meta.url",`,
+    `* such as "setAssetPath(import.meta.url)". Other options include`,
+    `* "setAssetPath(document.currentScript.src)", or using a bundler's replace plugin to`,
+    `* dynamically set the path at build time, such as "setAssetPath(process.env.ASSET_PATH)".`,
+    `* But do note that this configuration depends on how your script is bundled, or lack of`,
+    `* bunding, and where your assets can be loaded from. Additionally custom bundling`,
+    `* will have to ensure the static assets are copied to its build directory.`,
+    `export declare const setAssetPath: (path: string) => void;`,
+    ``,
   ];
 
   const usersIndexJsPath = join(config.srcDir, 'index.ts');

src/compiler/output-targets/dist-custom-elements-bundle/index.ts

@@ -86,9 +86,10 @@ const generateEntryPoint = (buildCtx: d.BuildCtx) => {
 
   imp.push(
     `import { proxyCustomElement } from '${STENCIL_INTERNAL_CLIENT_ID}';`,
+    `export { setAssetPath } from '${STENCIL_INTERNAL_CLIENT_ID}';`,
     `export * from '${USER_INDEX_ENTRY_ID}';`,
     `import { globalScripts } from '${STENCIL_APP_GLOBALS_ID}';`,
-    'globalScripts();',
+    `globalScripts();`,
   );
 
   buildCtx.components.forEach(cmp => {

src/declarations/stencil-core.ts

@@ -35,6 +35,7 @@ export {
   RafCallback,
   readTask,
   setMode,
+  setAssetPath,
   State,
   VNode,
   VNodeData,

src/declarations/stencil-public-runtime.ts

@@ -266,10 +266,26 @@ export declare const setMode: (handler: ResolutionHandler) => void;
 export declare function getMode<T = string | undefined>(ref: any): T;
 
 /**
- * getAssetPath
+ * Get the base path to where the assets can be found. Use `setAssetPath(path)`
+ * if the path needs to be customized.
  */
 export declare function getAssetPath(path: string): string;
 
+/**
+ * Used to manually set the base path where assets can be found. For lazy-loaded
+ * builds the asset path is automatically set and assets copied to the correct
+ * build directory. However, for custom elements builds, the `setAssetPath(path)` could
+ * be used to customize the asset path depending on how the script file is consumed.
+ * If the script is used as "module", it's recommended to use "import.meta.url", such
+ * as `setAssetPath(import.meta.url)`. Other options include
+ * `setAssetPath(document.currentScript.src)`, or using a bundler's replace plugin to
+ * dynamically set the path at build time, such as `setAssetPath(process.env.ASSET_PATH)`.
+ * But do note that this configuration depends on how your script is bundled, or lack of
+ * bunding, and where your assets can be loaded from. Additionally custom bundling
+ * will have to ensure the static assets are copied to its build directory.
+ */
+export declare function setAssetPath(path: string): string;
+
 /**
  * getElement
  */

src/runtime/get-asset-path.ts → src/runtime/asset-path.ts

@@ -4,3 +4,5 @@ export const getAssetPath = (path: string) => {
   const assetUrl = new URL(path, plt.$resourcesUrl$);
   return assetUrl.origin !== win.location.origin ? assetUrl.href : assetUrl.pathname;
 };
+
+export const setAssetPath = (path: string) => (plt.$resourcesUrl$ = path);

src/runtime/context.ts

@@ -1,6 +1,6 @@
 import { BUILD } from '@app-data';
 import { Context, doc, nextTick, readTask, win, writeTask } from '@platform';
-import { getAssetPath } from './get-asset-path';
+import { getAssetPath } from './asset-path';
 
 export const getContext = (_elm: HTMLElement, context: string) => {
   if (context in Context) {

src/runtime/index.ts

@@ -4,7 +4,7 @@ export { bootstrapLazy } from './bootstrap-lazy';
 export { connectedCallback } from './connected-callback';
 export { createEvent } from './event-emitter';
 export { disconnectedCallback } from './disconnected-callback';
-export { getAssetPath } from './get-asset-path';
+export { getAssetPath, setAssetPath } from './asset-path';
 export { getConnect } from './connect';
 export { getContext } from './context';
 export { getElement } from './element';