@stencil/core
Version:
A Compiler for Web Components and Progressive Web Apps
1,352 lines (1,351 loc) • 79.8 kB
TypeScript
import type { JsonDocs } from './stencil-public-docs';
import type { PrerenderUrlResults } from '../internal';
export * from './stencil-public-docs';
/**
* https://stenciljs.com/docs/config/
*/
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.
*
* Additonally, 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 overriden.
*/
rollupConfig?: RollupConfig;
/**
* 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` confg 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 perfers 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 unnecesary reflows in some cases, especially during startup. `congestionAsync`
* is ideal for apps running animations while also simultaniously executing intesive tasks
* which may lock-up the main thread.
*
* - `immediate`: Makes writeTask() and readTask() callbacks to be executed syncronously. 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;
}
export interface ConfigExtras {
/**
* By default, the slot polyfill does not update `appendChild()` so that it appends
* new child nodes into the correct child slot like how shadow dom works. This is an opt-in
* polyfill for those who need it when using `element.appendChild(node)` and expecting the
* child to be appended in the same location shadom dom would. This is not required for
* IE11 or Edge 18, but can be enabled if the app is using `appendChild()`. Defaults to `false`.
*/
appendChildSlotFix?: boolean;
/**
* By default, the runtime does not polyfill `cloneNode()` when cloning a component
* that uses the slot polyfill. This is an opt-in polyfill for those who need it.
* This is not required for IE11 or Edge 18, but can be enabled if the app is using
* `cloneNode()` and unexpected node are being cloned due to the slot polyfill
* simulating shadow dom. Defaults to `false`.
*/
cloneNodeFix?: boolean;
/**
* Include the CSS Custom Property polyfill/shim for legacy browsers. ESM builds will
* not include the css vars shim. Defaults to `false`
*/
cssVarsShim?: boolean;
/**
* Dynamic `import()` shim. This is only needed for Edge 18 and below, and Firefox 67
* and below. Defaults to `false`.
*/
dynamicImportShim?: boolean;
/**
* Dispatches component lifecycle events. Mainly used for testing. Defaults to `false`.
*/
lifecycleDOMEvents?: boolean;
/**
* Safari 10 supports ES modules with `<script type="module">`, however, it did not implement
* `<script nomodule>`. When set to `true`, the runtime will patch support for Safari 10
* due to its lack of `nomodule` support.
* Defaults to `false`.
*/
safari10?: boolean;
/**
* It is possible to assign data to the actual `<script>` element's `data-opts` property,
* which then gets passed to Stencil's initial bootstrap. This feature is only required
* for very special cases and rarely needed. Defaults to `false`.
*/
scriptDataOpts?: boolean;
/**
* Experimental flag to align the behavior of invoking `textContent` on a scoped component to act more like a
* component that uses the shadow DOM. Defaults to `false`
*/
scopedSlotTextContentFix?: boolean;
/**
* If enabled `true`, the runtime will check if the shadow dom shim is required. However,
* if it's determined that shadow dom is already natively supported by the browser then
* it does not request the shim. When set to `false` it will avoid all shadow dom tests.
* Defaults to `false`.
*/
shadowDomShim?: boolean;
/**
* When a component is first attached to the DOM, this setting will wait a single tick before
* rendering. This works around an Angular issue, where Angular attaches the elements before
* settings their initial state, leading to double renders and unnecessary event dispatches.
* Defaults to `false`.
*/
initializeNextTick?: boolean;
/**
* For browsers that do not support shadow dom (IE11 and Edge 18 and below), slot is polyfilled
* to simulate the same behavior. However, the host element's `childNodes` and `children`
* getters are not patched to only show the child nodes and elements of the default slot.
* Defaults to `false`.
*/
slotChildNodesFix?: boolean;
/**
* Enables the tagNameTransform option of `defineCustomElements()`, so the component tagName
* can be customized at runtime. Defaults to `false`.
*/
tagNameTransform?: boolean;
}
export interface Config extends StencilConfig {
buildAppCore?: boolean;
buildDocs?: boolean;
configPath?: string;
writeLog?: boolean;
devServer?: DevServerConfig;
flags?: ConfigFlags;
fsNamespace?: string;
logLevel?: LogLevel;
rootDir?: string;
packageJsonFilePath?: string;
suppressLogs?: boolean;
profile?: boolean;
tsCompilerOptions?: any;
_isValidated?: boolean;
_isTesting?: boolean;
}
export interface HydratedFlag {
/**
* Defaults to `hydrated`.
*/
name?: string;
/**
* Can be either `class` or `attribute`. Defaults to `class`.
*/
selector?: 'class' | 'attribute';
/**
* The CSS property used to show and hide components. Defaults to use the CSS `visibility`
* property. Other commonly used CSS properties would be `display` with the `initialValue`
* setting as `none`, or `opacity` with the `initialValue` as `0`. Defaults to `visibility`
* and the default `initialValue` is `hidden`.
*/
property?: string;
/**
* This is the CSS value to give all components before it has been hydrated.
* Defaults to `hidden`.
*/
initialValue?: string;
/**
* This is the CSS value to assign once a component has finished hydrating.
* This is the CSS value that'll allow the component to show. Defaults to `inherit`.
*/
hydratedValue?: string;
}
export interface StencilDevServerConfig {
/**
* IP address used by the dev server. The default is `0.0.0.0`, which points to all IPv4 addresses
* on the local machine, such as `localhost`.
*/
address?: string;
/**
* Base path to be used by the server. Defaults to the root pathname.
*/
basePath?: string;
/**
* EXPERIMENTAL!
* During development, node modules can be independently requested and bundled, making for
* faster build times. This is only available using the Stencil Dev Server throughout
* development. Production builds and builds with the `es5` flag will override
* this setting to `false`. Default is `false`.
*/
experimentalDevModules?: boolean;
/**
* If the dev server should respond with gzip compressed content. Defaults to `true`.
*/
gzip?: boolean;
/**
* When set, the dev server will run via https using the SSL certificate and key you provide
* (use `fs` if you want to read them from files).
*/
https?: Credentials;
/**
* The URL the dev server should first open to. Defaults to `/`.
*/
initialLoadUrl?: string;
/**
* When `true`, every request to the server will be logged within the terminal.
* Defaults to `false`.
*/
logRequests?: boolean;
/**
* By default, when dev server is started the local dev URL is opened in your default browser.
* However, to prevent this URL to be opened change this value to `false`. Defaults to `true`.
*/
openBrowser?: boolean;
/**
* Sets the server's port. Defaults to `3333`.
*/
port?: number;
/**
* When files are watched and updated, by default the dev server will use `hmr` (Hot Module Replacement)
* to update the page without a full page refresh. To have the page do a full refresh use `pageReload`.
* To disable any reloading, use `null`. Defaults to `hmr`.
*/
reloadStrategy?: PageReloadStrategy;
/**
* Local path to a NodeJs file with a dev server request listener as the default export.
* The user's request listener is given the first chance to handle every request the dev server
* receives, and can choose to handle it or instead pass it on to the default dev server
* by calling `next()`.
*
* Below is an example of a NodeJs file the `requestListenerPath` config is using.
* The request and response arguments are the same as Node's `http` module and `RequestListener`
* callback. https://nodejs.org/api/http.html#http_http_createserver_options_requestlistener
*
* ```js
* module.exports = function (req, res, next) {
* if (req.url === '/ping') {
* // custom response overriding the dev server
* res.setHeader('Content-Type', 'text/plain');
* res.writeHead(200);
* res.end('pong');
* } else {
* // pass request on to the default dev server
* next();
* }
* };
* ```
*/
requestListenerPath?: string;
/**
* The root directory to serve the files from.
*/
root?: string;
/**
* If the dev server should Server-Side Render (SSR) each page, meaning it'll dynamically generate
* server-side rendered html on each page load. The `--ssr` flag will most commonly be used with
* the`--dev --watch --serve` flags during development. Note that this is for development purposes
* only, and the built-in dev server should not be used for production. Defaults to `false`.
*/
ssr?: boolean;
/**
* If the dev server fails to start up within the given timout (in milliseconds), the startup will
* be canceled. Set to zero to disable the timeout. Defaults to `15000`.
*/
startupTimeout?: number;
/**
* Whether to use the dev server's websocket client or not. Defaults to `true`.
*/
websocket?: boolean;
/**
* If the dev server should fork a worker for the server process or not. A singled-threaded dev server
* is slower, however it is useful for debugging http requests and responses. Defaults to `true`.
*/
worker?: boolean;
}
export interface DevServerConfig extends StencilDevServerConfig {
browserUrl?: string;
devServerDir?: string;
excludeHmr?: string[];
historyApiFallback?: HistoryApiFallback;
openBrowser?: boolean;
prerenderConfig?: string;
protocol?: 'http' | 'https';
srcIndexHtml?: string;
}
export interface HistoryApiFallback {
index?: string;
disableDotRule?: boolean;
}
export interface DevServerEditor {
id: string;
name?: string;
supported?: boolean;
priority?: number;
}
export interface ConfigFlags {
task?: TaskCommand;
args?: string[];
knownArgs?: string[];
unknownArgs?: string[];
address?: string;
build?: boolean;
cache?: boolean;
checkVersion?: boolean;
ci?: boolean;
compare?: boolean;
config?: string;
debug?: boolean;
dev?: boolean;
docs?: boolean;
docsApi?: string;
docsJson?: string;
e2e?: boolean;
emulate?: string;
es5?: boolean;
headless?: boolean;
help?: boolean;
log?: boolean;
logLevel?: string;
verbose?: boolean;
maxWorkers?: number;
open?: boolean;
port?: number;
prerender?: boolean;
prod?: boolean;
profile?: boolean;
root?: string;
screenshot?: boolean;
screenshotConnector?: string;
serve?: boolean;
serviceWorker?: boolean;
spec?: boolean;
ssr?: boolean;
stats?: boolean;
updateScreenshot?: boolean;
version?: boolean;
watch?: boolean;
devtools?: boolean;
}
export declare type TaskCommand = 'build' | 'docs' | 'generate' | 'g' | 'help' | 'info' | 'prerender' | 'serve' | 'telemetry' | 'test' | 'version';
export declare type PageReloadStrategy = 'hmr' | 'pageReload' | null;
/**
* The prerender config is used when prerendering a `www` output target.
* Within `stencil.config.ts`, set the path to the prerendering
* config file path using the `prerenderConfig` property, such as:
*
* ```tsx
* import { Config } from '@stencil/core';
* export const config: Config = {
* outputTargets: [
* {
* type: 'www',
* baseUrl: 'https://stenciljs.com/',
* prerenderConfig: './prerender.config.ts',
* }
* ]
* };
* ```
*
* The `prerender.config.ts` should export a `config` object using
* the `PrerenderConfig` interface.
*
* ```tsx
* import { PrerenderConfig } from '@stencil/core';
* export const config: PrerenderConfig = {
* ...
* };
* ```
*
* For more info: https://stenciljs.com/docs/static-site-generation
*/
export interface PrerenderConfig {
/**
* Run after each `document` is hydrated, but before it is serialized
* into an HTML string. Hook is passed the `document` and its `URL`.
*/
afterHydrate?(document: Document, url: URL, results: PrerenderUrlResults): any | Promise<any>;
/**
* Run before each `document` is hydrated. Hook is passed the `document` it's `URL`.
*/
beforeHydrate?(document: Document, url: URL): any | Promise<any>;
/**
* Runs after the template Document object has serialize into an
* HTML formatted string. Returns an HTML string to be used as the
* base template for all prerendered pages.
*/
afterSerializeTemplate?(html: string): string | Promise<string>;
/**
* Runs before the template Document object is serialize into an
* HTML formatted string. Returns the Document to be serialized which
* will become the base template html for all prerendered pages.
*/
beforeSerializeTemplate?(document: Document): Document | Promise<Document>;
/**
* A hook to be used to generate the canonical `<link>` tag
* which goes in the `<head>` of every prerendered page. Returning `null`
* will not add a canonical url tag to the page.
*/
canonicalUrl?(url: URL): string | null;
/**
* While prerendering, crawl same-origin URLs found within `<a href>` elements.
* Defaults to `true`.
*/
crawlUrls?: boolean;
/**
* URLs to start the prerendering from. By default the root URL of `/` is used.
*/
entryUrls?: string[];
/**
* Return `true` the given `<a>` element should be crawled or not.
*/
filterAnchor?(attrs: {
[attrName: string]: string;
}, base?: URL): boolean;
/**
* Return `true` if the given URL should be prerendered or not.
*/
filterUrl?(url: URL, base: URL): boolean;
/**
* Returns the file path which the prerendered HTML content
* should be written to.
*/
filePath?(url: URL, filePath: string): string;
/**
* Returns the hydrate options to use for each individual prerendered page.
*/
hydrateOptions?(url: URL): PrerenderHydrateOptions;
/**
* Returns the template file's content. The template is the base
* HTML used for all prerendered pages.
*/
loadTemplate?(filePath: string): string | Promise<string>;
/**
* Used to normalize the page's URL from a given a string and the current
* page's base URL. Largely used when reading an anchor's `href` attribute
* value and normalizing it into a `URL`.
*/
normalizeUrl?(href: string, base: URL): URL;
robotsTxt?(opts: RobotsTxtOpts): string | RobotsTxtResults;
sitemapXml?(opts: SitemapXmpOpts): string | SitemapXmpResults;
/**
* Static Site Generated (SSG). Does not include Stencil's clientside
* JavaScript, custom elements or preload modules.
*/
staticSite?: boolean;
/**
* If the prerenndered URLs should have a trailing "/"" or not. Defaults to `false`.
*/
trailingSlash?: boolean;
}
export interface HydrateDocumentOptions {
/**
* Build ID that will be added to `<html data-stencil-build="BUILD_ID">`. By default
* a random ID will be generated
*/
buildId?: string;
/**
* Sets the `href` attribute on the `<link rel="canonical">`
* tag within the `<head>`. If the value is not defined it will
* ensure a canonical link tag is no included in the `<head>`.
*/
canonicalUrl?: string;
/**
* Include the HTML comments and attributes used by the clientside
* JavaScript to read the structure of the HTML and rebuild each
* component. Defaults to `true`.
*/
clientHydrateAnnotations?: boolean;
/**
* Constrain `setTimeout()` to 1ms, but still async. Also
* only allows `setInterval()` to fire once, also constrained to 1ms.
* Defaults to `true`.
*/
constrainTimeouts?: boolean;
/**
* Sets `document.cookie`
*/
cookie?: string;
/**
* Sets the `dir` attribute on the top level `<html>`.
*/
direction?: string;
/**
* Component tag names listed here will not be prerendered, nor will
* hydrated on the clientside. Components listed here will be ignored
* as custom elements and treated no differently than a `<div>`.
*/
excludeComponents?: string[];
/**
* Sets the `lang` attribute on the top level `<html>`.
*/
language?: string;
/**
* Maximum number of components to hydrate on one page. Defaults to `300`.
*/
maxHydrateCount?: number;
/**
* Sets `document.referrer`
*/
referrer?: string;
/**
* Removes every `<script>` element found in the `document`. Defaults to `false`.
*/
removeScripts?: boolean;
/**
* Removes CSS not used by elements within the `document`. Defaults to `true`.
*/
removeUnusedStyles?: boolean;
/**
* The url the runtime uses for the resources, such as the assets directory.
*/
resourcesUrl?: string;
/**
* Prints out runtime console logs to the NodeJS process. Defaults to `false`.
*/
runtimeLogging?: boolean;
/**
* Component tags listed here will only be prerendered or serverside-rendered
* and will not be clientside hydrated. This is useful for components that
* are not dynamic and do not need to be defined as a custom element within the
* browser. For example, a header or footer component would be a good example that
* may not require any clientside JavaScript.
*/
staticComponents?: string[];
/**
* The amount of milliseconds to wait for a page to finish rendering until
* a timeout error is thrown. Defaults to `15000`.
*/
timeout?: number;
/**
* Sets `document.title`.
*/
title?: string;
/**
* Sets `location.href`
*/
url?: string;
/**
* Sets `navigator.userAgent`
*/
userAgent?: string;
}
export interface SerializeDocumentOptions extends HydrateDocumentOptions {
/**
* Runs after the `document` has been hydrated.
*/
afterHydrate?(document: any): any | Promise<any>;
/**
* Sets an approximate line width the HTML should attempt to stay within.
* Note that this is "approximate", in that HTML may often not be able
* to be split at an exact line width. Additionally, new lines created
* is where HTML naturally already has whitespce, such as before an
* attribute or spaces between words. Defaults to `100`.
*/
approximateLineWidth?: number;
/**
* Runs before the `document` has been hydrated.
*/
beforeHydrate?(document: any): any | Promise<any>;
/**
* Format the HTML in a nicely indented format.
* Defaults to `false`.
*/
prettyHtml?: boolean;
/**
* Remove quotes from attribute values when possible.
* Defaults to `true`.
*/
removeAttributeQuotes?: boolean;
/**
* Remove the `=""` from standardized `boolean` attributes,
* such as `hidden` or `checked`. Defaults to `true`.
*/
removeBooleanAttributeQuotes?: boolean;
/**
* Remove these standardized attributes when their value is empty:
* `class`, `dir`, `id`, `lang`, and `name`, `title`. Defaults to `true`.
*/
removeEmptyAttributes?: boolean;
/**
* Remove HTML comments. Defaults to `true`.
*/
removeHtmlComments?: boolean;
}
export interface HydrateFactoryOptions extends SerializeDocumentOptions {
serializeToHtml: boolean;
destroyWindow: boolean;
destroyDocument: boolean;
}
export interface PrerenderHydrateOptions extends SerializeDocumentOptions {
/**
* Adds `<link rel="modulepreload">` for modules that will eventually be requested.
* Defaults to `true`.
*/
addModulePreloads?: boolean;
/**
* Hash the content of assets, such as images, fonts and css files,
* and add the hashed value as `v` querystring. For example,
* `/assets/image.png?v=abcd1234`. This allows for assets to be
* heavily cached by setting the server's response header with
* `Cache-Control: max-age=31536000, immutable`.
*/
hashAssets?: 'querystring';
/**
* External stylesheets from `<link rel="stylesheet">` are instead inlined
* into `<style>` elements. Defaults to `false`.
*/
inlineExternalStyleSheets?: boolean;
/**
* Minify CSS content within `<style>` elements. Defaults to `true`.
*/
minifyStyleElements?: boolean;
/**
* Minify JavaScript content within `<script>` elements. Defaults to `true`.
*/
minifyScriptElements?: boolean;
/**
* Entire `document` should be static. This is useful for specific pages that
* should be static, rather than the entire site. If the whole site should be static,
* use the `staticSite` property on the prerender config instead. If only certain
* components should be static then use `staticComponents` instead.
*/
staticDocument?: boolean;
}
export interface RobotsTxtOpts {
urls: string[];
sitemapUrl: string;
baseUrl: string;
dir: string;
}
export interface RobotsTxtResults {
content: string;
filePath: string;
url: string;
}
export interface SitemapXmpOpts {
urls: string[];
baseUrl: string;
dir: string;
}
export interface SitemapXmpResults {
content: string;
filePath: string;
url: string;
}
/**
* Common system used by the compiler. All file reads, writes, access, etc. will all use
* this system. Additionally, throughout each build, the compiler will use an internal
* in-memory file system as to prevent unnecessary fs reads and writes. At the end of each
* build all actions the in-memory fs performed will be written to disk using this system.
* A NodeJS based system will use APIs such as `fs` and `crypto`, and a web-based system
* will use in-memory Maps and browser APIs. Either way, the compiler itself is unaware
* of the actual platform it's being ran ontop of.
*/
export interface CompilerSystem {
name: 'node' | 'in-memory';
version: string;
events?: BuildEvents;
details?: SystemDetails;
/**
* Add a callback which will be ran when destroy() is called.
*/
addDestory(cb: () => void): void;
/**
* Always returns a boolean, does not throw.
*/
access(p: string): Promise<boolean>;
/**
* SYNC! Always returns a boolean, does not throw.
*/
accessSync(p: string): boolean;
applyGlobalPatch?(fromDir: string): Promise<void>;
applyPrerenderGlobalPatch?(opts: {
devServerHostUrl: string;
window: any;
}): void;
cacheStorage?: CacheStorage;
checkVersion?: (logger: Logger, currentVersion: string) => Promise<() => void>;
copy?(copyTasks: Required<CopyTask>[], srcDir: string): Promise<CopyResults>;
/**
* Always returns a boolean if the files were copied or not. Does not throw.
*/
copyFile(src: string, dst: string): Promise<boolean>;
/**
* Used to destroy any listeners, file watchers or child processes.
*/
destroy(): Promise<void>;
/**
* Does not throw.
*/
createDir(p: string, opts?: CompilerSystemCreateDirectoryOptions): Promise<CompilerSystemCreateDirectoryResults>;
/**
* SYNC! Does not throw.
*/
createDirSync(p: string, opts?: CompilerSystemCreateDirectoryOptions): CompilerSystemCreateDirectoryResults;
homeDir(): string;
/**
* Used to determine if the current context of the terminal is TTY.
*/
isTTY(): boolean;
/**
* Each plaform as a different way to dynamically import modules.
*/
dynamicImport?(p: string): Promise<any>;
/**
* Creates the worker controller for the current system.
*/
createWorkerController?(maxConcurrentWorkers: number): WorkerMainController;
encodeToBase64(str: string): string;
ensureDependencies?(opts: {
rootDir: string;
logger: Logger;
dependencies: CompilerDependency[];
}): Promise<{
stencilPath: string;
diagnostics: Diagnostic[];
}>;
ensureResources?(opts: {
rootDir: string;
logger: Logger;
dependencies: CompilerDependency[];
}): Promise<void>;
/**
* process.exit()
*/
exit(exitCode: number): Promise<void>;
/**
* Optionally provide a fetch() function rather than using the built-in fetch().
* First arg is a url string or Request object (RequestInfo).
* Second arg is the RequestInit. Returns the Response object
*/
fetch?(input: string | any, init?: any): Promise<any>;
/**
* Generates a sha1 digest encoded as HEX
*/
generateContentHash?(content: string | any, length?: number): Promise<string>;
/**
* Generates a sha1 digest encoded as HEX from a file path
*/
generateFileHash?(filePath: string | any, length?: number): Promise<string>;
/**
* Get the current directory.
*/
getCurrentDirectory(): string;
/**
* The compiler's executing path.
*/
getCompilerExecutingPath(): string;
/**
* The dev server's executing path.
*/
getDevServerExecutingPath?(): string;
getEnvironmentVar?(key: string): string;
/**
* Gets the absolute file path when for a dependency module.
*/
getLocalModulePath(opts: {
rootDir: string;
moduleId: string;
path: string;
}): string;
/**
* Gets the full url when requesting a dependency module to fetch from a CDN.
*/
getRemoteModuleUrl(opts: {
moduleId: string;
path?: string;
version?: string;
}): string;
/**
* Aync glob task. Only available in NodeJS compiler system.
*/
glob?(pattern: string, options: {
cwd?: string;
nodir?: boolean;
[key: string]: any;
}): Promise<string[]>;
/**
* The number of logical processors available to run threads on the user's computer (cpus).
*/
hardwareConcurrency: number;
/**
* Tests if the path is a symbolic link or not. Always resolves a boolean. Does not throw.
*/
isSymbolicLink(p: string): Promise<boolean>;
lazyRequire?: LazyRequire;
nextTick(cb: () => void): void;
/**
* Normalize file system path.
*/
normalizePath(p: string): string;
onProcessInterrupt?(cb: () => void): void;
parseYarnLockFile?: (content: string) => {
type: 'success' | 'merge' | 'conflict';
object: any;
};
platformPath: PlatformPath;
/**
* All return paths are full normalized paths, not just the basenames. Always returns an array, does not throw.
*/
readDir(p: string): Promise<string[]>;
/**
* SYNC! All return paths are full normalized paths, not just the basenames. Always returns an array, does not throw.
*/
readDirSync(p: string): string[];
/**
* Returns undefined if file is not found. Does not throw.
*/
readFile(p: string): Promise<string>;
readFile(p: string, encoding: 'utf8'): Promise<string>;
readFile(p: string, encoding: 'binary'): Promise<any>;
/**
* SYNC! Returns undefined if file is not found. Does not throw.
*/
readFileSync(p: string, encoding?: string): string;
/**
* Does not throw.
*/
realpath(p: string): Promise<CompilerSystemRealpathResults>;
/**
* SYNC! Does not throw.
*/
realpathSync(p: string): CompilerSystemRealpathResults;
/**
* Remove a callback which will be ran when destroy() is called.
*/
removeDestory(cb: () => void): void;
/**
* Rename old path to new path. Does not throw.
*/
rename(oldPath: string, newPath: string): Promise<CompilerSystemRenameResults>;
resolveModuleId?(opts: ResolveModuleIdOptions): Promise<ResolveModuleIdResults>;
resolvePath(p: string): string;
/**
* Does not throw.
*/
removeDir(p: string, opts?: CompilerSystemRemoveDirectoryOptions): Promise<CompilerSystemRemoveDirectoryResults>;
/**
* SYNC! Does not throw.
*/
removeDirSync(p: string, opts?: CompilerSystemRemoveDirectoryOptions): CompilerSystemRemoveDirectoryResults;
/**
* Does not throw.
*/
removeFile(p: string): Promise<CompilerSystemRemoveFileResults>;
/**
* SYNC! Does not throw.
*/
removeFileSync(p: string): CompilerSystemRemoveFileResults;
setupCompiler?: (c: {
ts: any;
}) => void;
/**
* Always returns an object. Does not throw. Check for "error" property if there's an error.
*/
stat(p: string): Promise<CompilerFsStats>;
/**
* SYNC! Always returns an object. Does not throw. Check for "error" property if there's an error.
*/
statSync(p: string): CompilerFsStats;
tmpDirSync(): string;
watchDirectory?(p: string, callback: CompilerFileWatcherCallback, recursive?: boolean): CompilerFileWatcher;
watchFile?(p: string, callback: CompilerFileWatcherCallback): CompilerFileWatcher;
/**
* How many milliseconds to wait after a change before calling watch callbacks.
*/
watchTimeout?: number;
/**
* Does not throw.
*/
writeFile(p: string, content: string): Promise<CompilerSystemWriteFileResults>;
/**
* SYNC! Does not throw.
*/
writeFileSync(p: string, content: string): CompilerSystemWriteFileResults;
}
export interface TranspileOnlyResults {
diagnostics: Diagnostic[];
output: string;
sourceMap: any;
}
export interface ParsedPath {
root: string;
dir: string;
base: string;
ext: string;
name: string;
}
export interface PlatformPath {
normalize(p: string): string;
join(...paths: string[]): string;
resolve(...pathSegments: string[]): string;
isAbsolute(p: string): boolean;
relative(from: string, to: string): string;
dirname(p: string): string;
basename(p: string, ext?: string): string;
extname(p: string): string;
parse(p: string): ParsedPath;
sep: string;
delimiter: string;
posix: any;
win32: any;
}
export interface CompilerDependency {
name: string;
version: string;
main: string;
resources?: string[];
}
export interface ResolveModuleIdOptions {
moduleId: string;
containingFile?: string;
exts?: string[];
packageFilter?: (pkg: any) => void;
}
export interface ResolveModuleIdResults {
moduleId: string;
resolveId: string;
pkgData: {
name: string;
version: string;
[key: string]: any;
};
pkgDirPath: string;
}
export interface WorkerMainController {
send(...args: any[]): Promise<any>;
handler(name: string): (...args: any[]) => Promise<any>;
destroy(): void;
maxWorkers: number;
}
export interface CopyResults {
diagnostics: Diagnostic[];
filePaths: string[];
dirPaths: string[];
}
export interface SystemDetails {
cpuModel: string;
freemem(): number;
platform: 'darwin' | 'windows' | 'linux' | '';
release: string;
totalmem: number;
}
export interface BuildOnEvents {
on(cb: (eventName: CompilerEventName, data: any) => void): BuildOnEventRemove;
on(eventName: CompilerEventFileAdd, cb: (path: string) => void): BuildOnEventRemove;
on(eventName: CompilerEventFileDelete, cb: (path: string) => void): BuildOnEventRemove;
on(eventName: CompilerEventFileUpdate, cb: (path: string) => void): BuildOnEventRemove;
on(eventName: CompilerEventDirAdd, cb: (path: string) => void): BuildOnEventRemove;
on(eventName: CompilerEventDirDelete, cb: (path: string) => void): BuildOnEventRemove;
on(eventName: CompilerEventBuildStart, cb: (buildStart: CompilerBuildStart) => void): BuildOnEventRemove;
on(eventName: CompilerEventBuildFinish, cb: (buildResults: CompilerBuildResults) => void): BuildOnEventRemove;
on(eventName: CompilerEventBuildLog, cb: (buildLog: BuildLog) => void): BuildOnEventRemove;
on(eventName: CompilerEventBuildNoChange, cb: () => void): BuildOnEventRemove;
}
export interface BuildEmitEvents {
emit(eventName: CompilerEventFileAdd, path: string): void;
emit(eventName: CompilerEventFileDelete, path: string): void;
emit(eventName: CompilerEventFileUpdate, path: string): void;
emit(eventName: CompilerEventDirAdd, path: string): void;
emit(eventName: CompilerEventDirDelete, path: string): void;
emit(eventName: CompilerEventBuildStart, buildStart: CompilerBuildStart): void;
emit(eventName: CompilerEventBuildFinish, buildResults: CompilerBuildResults): void;
emit(eventName: CompilerEventBuildNoChange, buildNoChange: BuildNoChangeResults): void;
emit(eventName: CompilerEventBuildLog, buildLog: BuildLog): void;
emit(eventName: CompilerEventFsChange, fsWatchResults: FsWatchResults): void;
}
export interface FsWatchResults {
dirsAdded: string[];
dirsDeleted: string[];
filesUpdated: string[];
filesAdded: string[];
filesDeleted: string[];
}
export interface BuildLog {
buildId: number;
messages: string[];
progress: number;
}
export interface BuildNoChangeResults {
buildId: number;
noChange: boolean;
}
export interface CompilerBuildResults {
buildId: number;
componentGraph?: BuildResultsComponentGraph;
diagnostics: Diagnostic[];
dirsAdded: string[];
dirsDeleted: string[];
duration: number;
filesAdded: string[];
filesChanged: string[];
filesDeleted: string[];
filesUpdated: string[];
hasError: boolean;
hasSuccessfulBuild: boolean;
hmr?: HotModuleReplacement;
hydrateAppFilePath?: string;
isRebuild: boolean;
namespace: string;
outputs: BuildOutput[];
rootDir: string;
srcDir: string;
timestamp: string;
}
export interface BuildResultsComponentGraph {
[scopeId: string]: string[];
}
export interface BuildOutput {
type: string;
files: string[];
}
export interface HotModuleReplacement {
componentsUpdated?: string[];
excludeHmr?: string[];
externalStylesUpdated?: string[];
imagesUpdated?: string[];
indexHtmlUpdated?: boolean;
inlineStylesUpdated?: HmrStyleUpdate[];
reloadStrategy: PageReloadStrategy;
scriptsAdded?: string[];
scriptsDeleted?: string[];
serviceWorkerUpdated?: boolean;
versionId?: string;
}
export interface HmrStyleUpdate {
styleId: string;
styleTag: string;
styleText: string;
}
export declare type BuildOnEventRemove = () => boolean;
export interface BuildEvents extends BuildOnEvents, BuildEmitEvents {
unsubscribeAll(): void;
}
export interface CompilerBuildStart {
buildId: number;
timestamp: string;
}
export declare type CompilerFileWatcherCallback = (fileName: string, eventKind: CompilerFileWatcherEvent) => void;
export declare type CompilerFileWatcherEvent = CompilerEventFileAdd | CompilerEventFileDelete | CompilerEventFileUpdate | CompilerEventDirAdd | CompilerEventDirDelete;
export declare type CompilerEventName = CompilerEventFsChange | CompilerEventFileUpdate | CompilerEventFileAdd | CompilerEventFileDelete | CompilerEventDirAdd | CompilerEventDirDelete | CompilerEventBuildStart | CompilerEventBuildFinish | CompilerEventBuildNoChange | CompilerEventBuildLog;
export declare type CompilerEventFsChange = 'fsChange';
export declare type CompilerEventFileUpdate = 'fileUpdate';
export declare type CompilerEventFileAdd = 'fileAdd';
export declare type CompilerEventFileDelete = 'fileDelete';
export declare type CompilerEventDirAdd = 'dirAdd';
export declare type CompilerEventDirDelete = 'dirDelete';
export declare type CompilerEventBuildStart = 'buildStart';
export declare type CompilerEventBuildFinish = 'buildFinish';
export declare type CompilerEventBuildLog = 'buildLog';
export declare type CompilerEventBuildNoChange = 'buildNoChange';
export interface CompilerFileWatcher {
close(): void | Promise<void>;
}
export interface CompilerFsStats {
/**
* If it's a directory. `false` if there was an error.
*/
isDirectory: boolean;
/**
* If it's a file. `false` if there was an error.
*/
isFile: boolean;
/**
* If it's a symlink. `false` if there was an error.
*/
isSymbolicLink: boolean;
/**
* The size of the file in bytes. `0` for directories or if there was an error.
*/
size: number;
/**
* The timestamp indicating the last time this file was modified expressed in milliseconds since the POSIX Epoch.
*/
mtimeMs?: number;
/**
* Error if there was one, otherwise `null`. `stat` and `statSync` do not throw errors but always returns this interface.
*/
error: any;
}
export interface CompilerSystemCreateDirectoryOptions {
/**
* Indicates whether parent directories should be created.
* @default false
*/
recursive?: boolean;
/**
* A file mode. If a string is passed, it is parsed as an octal integer. If not specified
* @default 0o777.
*/
mode?: number;
}
export interface CompilerSystemCreateDirectoryResults {
basename: string;
dirname: string;
path: string;
newDirs: string[];
error: any;
}
export interface CompilerSystemRemoveDirectoryOptions {
/**
* Indicates whether child files and subdirectories should be removed.
* @default false
*/
recursive?: boolean;
}
export interface CompilerSystemRemoveDirectoryResults {
basename: string;
dirname: string;
path: string;
removedDirs: string[];
removedFiles: string[];
error: any;
}
export interface CompilerSystemRenameResults extends CompilerSystemRenamedPath {
renamed: CompilerSystemRenamedPath[];
oldDirs: string[];
oldFiles: string[];
newDirs: string[];
newFiles: string[];
error: any;
}
export interface CompilerSystemRenamedPath {
oldPath: string;
newPath: string;
isFile: boolean;
isDirectory: boolean;
}
export interface CompilerSystemRealpathResults {
path: string;
error: any;
}
export interface CompilerSystemRemoveFileResults {
basename: string;
dirname: string;
path: string;
error: any;
}
export interface CompilerSystemWriteFileResults {
path: string;
error: any;
}
export interface Credentials {
key: string;
cert: string;
}
export interface ConfigBundle {
components: string[];
}
export interface CopyTask {
src: string;
dest?: string;
warn?: boolean;
keepDirStructure?: boolean;
}
export interface BundlingConfig {
namedExports?: {
[key: string]: string[];
};
}
export interface NodeResolveConfig {
module?: boolean;
jsnext?: boolean;
main?: boolean;
browser?: boolean;
extensions?: string[];
preferBuiltins?: boolean;
jail?: string;
only?: Array<string | RegExp>;
modulesOnly?: boolean;
/**
* @see https://github.com/browserify/resolve#resolveid-opts-cb
*/
customResolveOptions?: {
basedir?: string;
package?: string;
extensions?: string[];
readFile?: Function;