Stencil bundling externals
Stencil bundles all external dependencies on its own. It creates challenges with the transpiled lib code and in the case on stencil libs importing stencil libs we presume it creates duplicate instances of supposedly Singleton objects.
So far we've been unable to override this issue and while it has not proved to be a problem, it still might.
To work around this, so far, for opendsu, we've created a script that deletes the importing lines from the code:
function fixImports (){
const jsFiles = ['www/build/**/*.js']
return src(jsFiles)
.pipe(replace(/import(:?[^\{\}/]+? from)?\s?['"]opendsu['"];/g, function(match, p1, offset, string) {
console.log(`Found an OpenDSU import in Bundle '${match}'. Removing...`)
return ' '.repeat(match.length);
}))
.pipe(dest('www/build/'));
}called by gulp.
as for the remaining, if it becomes a problem, we can follow Stencil Config object to reveal some undocumented features:
export interface StencilConfig {
/**
* By default, Stencil will attempt to optimize small scripts by inlining them in HTML. Setting
* this flag to `false` will prevent this optimization and keep all scripts separate from HTML.
*/
allowInlineScripts?: boolean;
/**
* By setting `autoprefixCss` to `true`, Stencil will use the appropriate config to automatically
* prefix css. For example, developers can write modern and standard css properties, such as
* "transform", and Stencil will automatically add in the prefixed version, such as "-webkit-transform".
* As of Stencil v2, autoprefixing CSS is no longer the default.
* Defaults to `false`
*/
autoprefixCss?: boolean | any;
/**
* By default, Stencil will statically analyze the application and generate a component graph of
* how all the components are interconnected.
*
* From the component graph it is able to best decide how components should be grouped
* depending on their usage with one another within the app.
* By doing so it's able to bundle components together in order to reduce network requests.
* However, bundles can be manually generated using the bundles config.
*
* The bundles config is an array of objects that represent how components are grouped together
* in lazy-loaded bundles.
* This config is rarely needed as Stencil handles this automatically behind the scenes.
*/
bundles?: ConfigBundle[];
/**
* Stencil will cache build results in order to speed up rebuilds.
* To disable this feature, set enableCache to false.
*/
enableCache?: boolean;
/**
* Stencil is traditionally used to compile many components into an app,
* and each component comes with its own compartmentalized styles.
* However, it's still common to have styles which should be "global" across all components and the website.
* A global CSS file is often useful to set CSS Variables.
*
* Additionally, the globalStyle config can be used to precompile styles with Sass, PostCss, etc.
* Below is an example folder structure containing a webapp's global sass file, named app.css.
*/
globalStyle?: string;
/**
* When the hashFileNames config is set to true, and it is a production build,
* the hashedFileNameLength config is used to determine how many characters the file name's hash should be.
*/
hashedFileNameLength?: number;
/**
* During production builds, the content of each generated file is hashed to represent the content,
* and the hashed value is used as the filename. If the content isn't updated between builds,
* then it receives the same filename. When the content is updated, then the filename is different.
*
* By doing this, deployed apps can "forever-cache" the build directory and take full advantage of
* content delivery networks (CDNs) and heavily caching files for faster apps.
*/
hashFileNames?: boolean;
/**
* The namespace config is a string representing a namespace for the app.
* For apps that are not meant to be a library of reusable components,
* the default of App is just fine. However, if the app is meant to be consumed
* as a third-party library, such as Ionic, a unique namespace is required.
*/
namespace?: string;
/**
* Stencil is able to take an app's source and compile it to numerous targets,
* such as an app to be deployed on an http server, or as a third-party library
* to be distributed on npm. By default, Stencil apps have an output target type of www.
*
* The outputTargets config is an array of objects, with types of www and dist.
*/
outputTargets?: OutputTarget[];
/**
* The plugins config can be used to add your own rollup plugins.
* By default, Stencil does not come with Sass or PostCss support.
* However, either can be added using the plugin array.
*/
plugins?: any[];
/**
* Generate js source map files for all bundles
*/
sourceMap?: boolean;
/**
* The srcDir config specifies the directory which should contain the source typescript files
* for each component. The standard for Stencil apps is to use src, which is the default.
*/
srcDir?: string;
/**
* Passes custom configuration down to the "@rollup/plugin-commonjs" that Stencil uses under the hood.
* For further information: https://stenciljs.com/docs/module-bundling
*/
commonjs?: BundlingConfig;
/**
* Passes custom configuration down to the "@rollup/plugin-node-resolve" that Stencil uses under the hood.
* For further information: https://stenciljs.com/docs/module-bundling
*/
nodeResolve?: NodeResolveConfig;
/**
* Passes custom configuration down to rollup itself, not all rollup options can be overridden.
*/
rollupConfig?: RollupConfig; <-- THIS IS NOT DOCUMENTED!
/**
* Sets if the ES5 build should be generated or not. Stencil generates a modern build without ES5,
* whereas this setting to `true` will also create es5 builds for both dev and prod modes. Setting
* `buildEs5` to `prod` will only build ES5 in prod mode. Basically if the app does not need to run
* on legacy browsers (IE11 and Edge 18 and below), it's safe to not build ES5, which will also speed
* up build times. Defaults to `false`.
*/
buildEs5?: boolean | 'prod';
/**
* Sets if the JS browser files are minified or not. Stencil uses `terser` under the hood.
* Defaults to `false` in dev mode and `true` in production mode.
*/
minifyJs?: boolean;
/**
* Sets if the CSS is minified or not.
* Defaults to `false` in dev mode and `true` in production mode.
*/
minifyCss?: boolean;
/**
* Forces Stencil to run in `dev` mode if the value is `true` and `production` mode
* if it's `false`.
*
* Defaults to `false` (ie. production) unless the `--dev` flag is used in the CLI.
*/
devMode?: boolean;
/**
* Object to provide a custom logger. By default a `logger` is already provided for the
* platform the compiler is running on, such as NodeJS or a browser.
*/
logger?: Logger;
/**
* Config to add extra runtime for DOM features that require more polyfills. Note
* that not all DOM APIs are fully polyfilled when using the slot polyfill. These
* are opt-in since not all users will require the additional runtime.
*/
extras?: ConfigExtras;
/**
* The hydrated flag identifies if a component and all of its child components
* have finished hydrating. This helps prevent any flash of unstyled content (FOUC)
* as various components are asynchronously downloaded and rendered. By default it
* will add the `hydrated` CSS class to the element. The `hydratedFlag` config can be used
* to change the name of the CSS class, change it to an attribute, or change which
* type of CSS properties and values are assigned before and after hydrating. This config
* can also be used to not include the hydrated flag at all by setting it to `null`.
*/
hydratedFlag?: HydratedFlag;
/**
* Ionic prefers to hide all components prior to hydration with a style tag appended
* to the head of the document containing some `visibility: hidden;` css rules.
*
* Disabling this will remove the style tag that sets `visibility: hidden;` on all
* unhydrated web components. This more closely follows the HTML spec, and allows
* you to set your own fallback content.
*
*/
invisiblePrehydration?: boolean;
/**
* Sets the task queue used by stencil's runtime. The task queue schedules DOM read and writes
* across the frames to efficiently render and reduce layout thrashing. By default,
* `async` is used. It's recommended to also try each setting to decide which works
* best for your use-case. In all cases, if your app has many CPU intensive tasks causing the
* main thread to periodically lock-up, it's always recommended to try
* [Web Workers](https://stenciljs.com/docs/web-workers) for those tasks.
*
* - `async`: DOM read and writes are scheduled in the next frame to prevent layout thrashing.
* During intensive CPU tasks it will not reschedule rendering to happen in the next frame.
* `async` is ideal for most apps, and if the app has many intensive tasks causing the main
* thread to lock-up, it's recommended to try [Web Workers](https://stenciljs.com/docs/web-workers)
* rather than the congestion async queue.
*
* - `congestionAsync`: DOM reads and writes are scheduled in the next frame to prevent layout
* thrashing. When the app is heavily tasked and the queue becomes congested it will then
* split the work across multiple frames to prevent blocking the main thread. However, it can
* also introduce unnecessary reflows in some cases, especially during startup. `congestionAsync`
* is ideal for apps running animations while also simultaneously executing intensive tasks
* which may lock-up the main thread.
*
* - `immediate`: Makes writeTask() and readTask() callbacks to be executed synchronously. Tasks
* are not scheduled to run in the next frame, but do note there is at least one microtask.
* The `immediate` setting is ideal for apps that do not provide long running and smooth
* animations. Like the async setting, if the app has intensive tasks causing the main thread
* to lock-up, it's recommended to try [Web Workers](https://stenciljs.com/docs/web-workers).
*/
taskQueue?: 'async' | 'immediate' | 'congestionAsync';
/**
* Provide a object of key/values accessible within the app, using the `Env` object.
*/
env?: {
[prop: string]: string | undefined;
};
globalScript?: string;
srcIndexHtml?: string;
watch?: boolean;
testing?: TestingConfig;
maxConcurrentWorkers?: number;
preamble?: string;
rollupPlugins?: {
before?: any[];
after?: any[];
};
entryComponentsHint?: string[];
buildDist?: boolean;
buildLogFilePath?: string;
cacheDir?: string;
devInspector?: boolean;
devServer?: StencilDevServerConfig;
enableCacheStats?: boolean;
sys?: CompilerSystem;
tsconfig?: string;
validateTypes?: boolean;
/**
* An array of RegExp patterns that are matched against all source files before adding
* to the watch list in watch mode. If the file path matches any of the patterns, when it
* is updated, it will not trigger a re-run of tests.
*/
watchIgnoredRegex?: RegExp | RegExp[];
excludeUnusedDependencies?: boolean;
stencilCoreResolvedId?: string;
}following the RollupCOnfig object we have:
export interface RollupConfig {
inputOptions?: RollupInputOptions;
outputOptions?: RollupOutputOptions;
}
export interface RollupInputOptions {
context?: string;
moduleContext?: ((id: string) => string) | {
[id: string]: string;
};
treeshake?: boolean;
}
export interface RollupOutputOptions {
globals?: {
[name: string]: string;
} | ((name: string) => string);
}which in the end, exposes the Externals Rollup API, so this might be useful eventually!