stencil-public-compiler.d.ts 98 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662
  1. import type { ConfigFlags } from '../cli/config-flags';
  2. import type { PrerenderUrlResults, PrintLine } from '../internal';
  3. import type { BuildCtx, CompilerCtx } from './stencil-private';
  4. import type { JsonDocs } from './stencil-public-docs';
  5. export * from './stencil-public-docs';
  6. /**
  7. * https://stenciljs.com/docs/config/
  8. */
  9. export interface StencilConfig {
  10. /**
  11. * By default, Stencil will attempt to optimize small scripts by inlining them in HTML. Setting
  12. * this flag to `false` will prevent this optimization and keep all scripts separate from HTML.
  13. */
  14. allowInlineScripts?: boolean;
  15. /**
  16. * By setting `autoprefixCss` to `true`, Stencil will use the appropriate config to automatically
  17. * prefix css. For example, developers can write modern and standard css properties, such as
  18. * "transform", and Stencil will automatically add in the prefixed version, such as "-webkit-transform".
  19. * As of Stencil v2, autoprefixing CSS is no longer the default.
  20. * Defaults to `false`
  21. */
  22. autoprefixCss?: boolean | any;
  23. /**
  24. * By default, Stencil will statically analyze the application and generate a component graph of
  25. * how all the components are interconnected.
  26. *
  27. * From the component graph it is able to best decide how components should be grouped
  28. * depending on their usage with one another within the app.
  29. * By doing so it's able to bundle components together in order to reduce network requests.
  30. * However, bundles can be manually generated using the bundles config.
  31. *
  32. * The bundles config is an array of objects that represent how components are grouped together
  33. * in lazy-loaded bundles.
  34. * This config is rarely needed as Stencil handles this automatically behind the scenes.
  35. */
  36. bundles?: ConfigBundle[];
  37. /**
  38. * Stencil will cache build results in order to speed up rebuilds.
  39. * To disable this feature, set enableCache to false.
  40. */
  41. enableCache?: boolean;
  42. /**
  43. * The directory where sub-directories will be created for caching when `enableCache` is set
  44. * `true` or if using Stencil's Screenshot Connector.
  45. *
  46. * @default '.stencil'
  47. *
  48. * @example
  49. *
  50. * A Stencil config like the following:
  51. * ```ts
  52. * export const config = {
  53. * ...,
  54. * enableCache: true,
  55. * cacheDir: '.cache',
  56. * testing: {
  57. * screenshotConnector: 'connector.js'
  58. * }
  59. * }
  60. * ```
  61. *
  62. * Will result in the following file structure:
  63. * ```tree
  64. * stencil-project-root
  65. * └── .cache
  66. * ├── .build <-- Where build related file caching is written
  67. * |
  68. * └── screenshot-cache.json <-- Where screenshot caching is written
  69. * ```
  70. */
  71. cacheDir?: string;
  72. /**
  73. * Stencil is traditionally used to compile many components into an app,
  74. * and each component comes with its own compartmentalized styles.
  75. * However, it's still common to have styles which should be "global" across all components and the website.
  76. * A global CSS file is often useful to set CSS Variables.
  77. *
  78. * Additionally, the globalStyle config can be used to precompile styles with Sass, PostCSS, etc.
  79. * Below is an example folder structure containing a webapp's global sass file, named app.css.
  80. */
  81. globalStyle?: string;
  82. /**
  83. * Will generate {@link https://nodejs.org/api/packages.html#packages_exports export map} entry points
  84. * for each component in the build when `true`.
  85. *
  86. * @default false
  87. */
  88. generateExportMaps?: boolean;
  89. /**
  90. * When the hashFileNames config is set to true, and it is a production build,
  91. * the hashedFileNameLength config is used to determine how many characters the file name's hash should be.
  92. */
  93. hashedFileNameLength?: number;
  94. /**
  95. * During production builds, the content of each generated file is hashed to represent the content,
  96. * and the hashed value is used as the filename. If the content isn't updated between builds,
  97. * then it receives the same filename. When the content is updated, then the filename is different.
  98. *
  99. * By doing this, deployed apps can "forever-cache" the build directory and take full advantage of
  100. * content delivery networks (CDNs) and heavily caching files for faster apps.
  101. */
  102. hashFileNames?: boolean;
  103. /**
  104. * The namespace config is a string representing a namespace for the app.
  105. * For apps that are not meant to be a library of reusable components,
  106. * the default of App is just fine. However, if the app is meant to be consumed
  107. * as a third-party library, such as Ionic, a unique namespace is required.
  108. */
  109. namespace?: string;
  110. /**
  111. * Stencil is able to take an app's source and compile it to numerous targets,
  112. * such as an app to be deployed on an http server, or as a third-party library
  113. * to be distributed on npm. By default, Stencil apps have an output target type of www.
  114. *
  115. * The outputTargets config is an array of objects, with types of www and dist.
  116. */
  117. outputTargets?: OutputTarget[];
  118. /**
  119. * The plugins config can be used to add your own rollup plugins.
  120. * By default, Stencil does not come with Sass or PostCSS support.
  121. * However, either can be added using the plugin array.
  122. */
  123. plugins?: any[];
  124. /**
  125. * Generate js source map files for all bundles
  126. */
  127. sourceMap?: boolean;
  128. /**
  129. * The srcDir config specifies the directory which should contain the source typescript files
  130. * for each component. The standard for Stencil apps is to use src, which is the default.
  131. */
  132. srcDir?: string;
  133. /**
  134. * Sets whether or not Stencil should transform path aliases set in a project's
  135. * `tsconfig.json` from the assigned module aliases to resolved relative paths.
  136. *
  137. * This behavior defaults to `true`, but may be opted-out of by setting this flag to `false`.
  138. */
  139. transformAliasedImportPaths?: boolean;
  140. /**
  141. * When `true`, we will validate a project's `package.json` based on the output target the user has designated
  142. * as `isPrimaryPackageOutputTarget: true` in their Stencil config.
  143. */
  144. validatePrimaryPackageOutputTarget?: boolean;
  145. /**
  146. * Passes custom configuration down to the "@rollup/plugin-commonjs" that Stencil uses under the hood.
  147. * For further information: https://stenciljs.com/docs/module-bundling
  148. */
  149. commonjs?: BundlingConfig;
  150. /**
  151. * Passes custom configuration down to the "@rollup/plugin-node-resolve" that Stencil uses under the hood.
  152. * For further information: https://stenciljs.com/docs/module-bundling
  153. */
  154. nodeResolve?: NodeResolveConfig;
  155. /**
  156. * Passes custom configuration down to rollup itself, not all rollup options can be overridden.
  157. */
  158. rollupConfig?: RollupConfig;
  159. /**
  160. * Sets if the ES5 build should be generated or not. Stencil generates a modern build without ES5,
  161. * whereas this setting to `true` will also create es5 builds for both dev and prod modes. Setting
  162. * `buildEs5` to `prod` will only build ES5 in prod mode. Basically if the app does not need to run
  163. * on legacy browsers (IE11 and Edge 18 and below), it's safe to not build ES5, which will also speed
  164. * up build times. Defaults to `false`.
  165. */
  166. buildEs5?: boolean | 'prod';
  167. /**
  168. * Sets if the JS browser files are minified or not. Stencil uses `terser` under the hood.
  169. * Defaults to `false` in dev mode and `true` in production mode.
  170. */
  171. minifyJs?: boolean;
  172. /**
  173. * Sets if the CSS is minified or not.
  174. * Defaults to `false` in dev mode and `true` in production mode.
  175. */
  176. minifyCss?: boolean;
  177. /**
  178. * Forces Stencil to run in `dev` mode if the value is `true` and `production` mode
  179. * if it's `false`.
  180. *
  181. * Defaults to `false` (ie. production) unless the `--dev` flag is used in the CLI.
  182. */
  183. devMode?: boolean;
  184. /**
  185. * Object to provide a custom logger. By default a `logger` is already provided for the
  186. * platform the compiler is running on, such as NodeJS or a browser.
  187. */
  188. logger?: Logger;
  189. /**
  190. * Config to add extra runtime for DOM features that require more polyfills. Note
  191. * that not all DOM APIs are fully polyfilled when using the slot polyfill. These
  192. * are opt-in since not all users will require the additional runtime.
  193. */
  194. extras?: ConfigExtras;
  195. /**
  196. * The hydrated flag identifies if a component and all of its child components
  197. * have finished hydrating. This helps prevent any flash of unstyled content (FOUC)
  198. * as various components are asynchronously downloaded and rendered. By default it
  199. * will add the `hydrated` CSS class to the element. The `hydratedFlag` config can be used
  200. * to change the name of the CSS class, change it to an attribute, or change which
  201. * type of CSS properties and values are assigned before and after hydrating. This config
  202. * can also be used to not include the hydrated flag at all by setting it to `null`.
  203. */
  204. hydratedFlag?: HydratedFlag | null;
  205. /**
  206. * Ionic prefers to hide all components prior to hydration with a style tag appended
  207. * to the head of the document containing some `visibility: hidden;` css rules.
  208. *
  209. * Disabling this will remove the style tag that sets `visibility: hidden;` on all
  210. * un-hydrated web components. This more closely follows the HTML spec, and allows
  211. * you to set your own fallback content.
  212. *
  213. */
  214. invisiblePrehydration?: boolean;
  215. /**
  216. * Sets the task queue used by stencil's runtime. The task queue schedules DOM read and writes
  217. * across the frames to efficiently render and reduce layout thrashing. By default,
  218. * `async` is used. It's recommended to also try each setting to decide which works
  219. * best for your use-case. In all cases, if your app has many CPU intensive tasks causing the
  220. * main thread to periodically lock-up, it's always recommended to try
  221. * [Web Workers](https://stenciljs.com/docs/web-workers) for those tasks.
  222. *
  223. * - `async`: DOM read and writes are scheduled in the next frame to prevent layout thrashing.
  224. * During intensive CPU tasks it will not reschedule rendering to happen in the next frame.
  225. * `async` is ideal for most apps, and if the app has many intensive tasks causing the main
  226. * thread to lock-up, it's recommended to try [Web Workers](https://stenciljs.com/docs/web-workers)
  227. * rather than the congestion async queue.
  228. *
  229. * - `congestionAsync`: DOM reads and writes are scheduled in the next frame to prevent layout
  230. * thrashing. When the app is heavily tasked and the queue becomes congested it will then
  231. * split the work across multiple frames to prevent blocking the main thread. However, it can
  232. * also introduce unnecessary reflows in some cases, especially during startup. `congestionAsync`
  233. * is ideal for apps running animations while also simultaneously executing intensive tasks
  234. * which may lock-up the main thread.
  235. *
  236. * - `immediate`: Makes writeTask() and readTask() callbacks to be executed synchronously. Tasks
  237. * are not scheduled to run in the next frame, but do note there is at least one microtask.
  238. * The `immediate` setting is ideal for apps that do not provide long running and smooth
  239. * animations. Like the async setting, if the app has intensive tasks causing the main thread
  240. * to lock-up, it's recommended to try [Web Workers](https://stenciljs.com/docs/web-workers).
  241. */
  242. taskQueue?: 'async' | 'immediate' | 'congestionAsync';
  243. /**
  244. * Provide a object of key/values accessible within the app, using the `Env` object.
  245. */
  246. env?: {
  247. [prop: string]: string | undefined;
  248. };
  249. globalScript?: string;
  250. srcIndexHtml?: string;
  251. watch?: boolean;
  252. testing?: TestingConfig;
  253. maxConcurrentWorkers?: number;
  254. preamble?: string;
  255. rollupPlugins?: {
  256. before?: any[];
  257. after?: any[];
  258. };
  259. entryComponentsHint?: string[];
  260. /**
  261. * Sets whether Stencil will write files to `dist/` during the build or not.
  262. *
  263. * By default this value is set to the opposite value of {@link devMode},
  264. * i.e. it will be `true` when building for production and `false` when
  265. * building for development.
  266. */
  267. buildDist?: boolean;
  268. buildLogFilePath?: string;
  269. devInspector?: boolean;
  270. devServer?: StencilDevServerConfig;
  271. sys?: CompilerSystem;
  272. tsconfig?: string;
  273. validateTypes?: boolean;
  274. /**
  275. * An array of RegExp patterns that are matched against all source files before adding
  276. * to the watch list in watch mode. If the file path matches any of the patterns, when it
  277. * is updated, it will not trigger a re-run of tests.
  278. */
  279. watchIgnoredRegex?: RegExp | RegExp[];
  280. /**
  281. * Set whether unused dependencies should be excluded from the built output.
  282. */
  283. excludeUnusedDependencies?: boolean;
  284. stencilCoreResolvedId?: string;
  285. }
  286. interface ConfigExtrasBase {
  287. /**
  288. * Experimental flag. Projects that use a Stencil library built using the `dist` output target may have trouble lazily
  289. * loading components when using a bundler such as Vite or Parcel. Setting this flag to `true` will change how Stencil
  290. * lazily loads components in a way that works with additional bundlers. Setting this flag to `true` will increase
  291. * the size of the compiled output. Defaults to `false`.
  292. * @deprecated This flag has been deprecated in favor of `enableImportInjection`, which provides the same
  293. * functionality. `experimentalImportInjection` will be removed in a future major version of Stencil.
  294. */
  295. experimentalImportInjection?: boolean;
  296. /**
  297. * Projects that use a Stencil library built using the `dist` output target may have trouble lazily
  298. * loading components when using a bundler such as Vite or Parcel. Setting this flag to `true` will change how Stencil
  299. * lazily loads components in a way that works with additional bundlers. Setting this flag to `true` will increase
  300. * the size of the compiled output. Defaults to `false`.
  301. */
  302. enableImportInjection?: boolean;
  303. /**
  304. * Dispatches component lifecycle events. Mainly used for testing. Defaults to `false`.
  305. */
  306. lifecycleDOMEvents?: boolean;
  307. /**
  308. * It is possible to assign data to the actual `<script>` element's `data-opts` property,
  309. * which then gets passed to Stencil's initial bootstrap. This feature is only required
  310. * for very special cases and rarely needed. Defaults to `false`.
  311. * @deprecated This option has been deprecated and will be removed in a future major version of Stencil.
  312. */
  313. scriptDataOpts?: boolean;
  314. /**
  315. * When a component is first attached to the DOM, this setting will wait a single tick before
  316. * rendering. This works around an Angular issue, where Angular attaches the elements before
  317. * settings their initial state, leading to double renders and unnecessary event dispatches.
  318. * Defaults to `false`.
  319. */
  320. initializeNextTick?: boolean;
  321. /**
  322. * Enables the tagNameTransform option of `defineCustomElements()`, so the component tagName
  323. * can be customized at runtime. Defaults to `false`.
  324. */
  325. tagNameTransform?: boolean;
  326. /**
  327. * Experimental flag.
  328. * Updates the behavior of scoped components to align more closely with the behavior of the native
  329. * Shadow DOM when using `slot`s.
  330. *
  331. * Defaults to `false`.
  332. */
  333. experimentalScopedSlotChanges?: boolean;
  334. }
  335. type ConfigExtrasSlotFixes<ExperimentalFixesEnabled extends boolean, IndividualFlags extends boolean> = {
  336. /**
  337. * By default, the slot polyfill does not update `appendChild()` so that it appends
  338. * new child nodes into the correct child slot like how shadow dom works. This is an opt-in
  339. * polyfill for those who need it when using `element.appendChild(node)` and expecting the
  340. * child to be appended in the same location shadow dom would. This is not required for
  341. * IE11 or Edge 18, but can be enabled if the app is using `appendChild()`. Defaults to `false`.
  342. */
  343. appendChildSlotFix?: IndividualFlags;
  344. /**
  345. * By default, the runtime does not polyfill `cloneNode()` when cloning a component
  346. * that uses the slot polyfill. This is an opt-in polyfill for those who need it.
  347. * This is not required for IE11 or Edge 18, but can be enabled if the app is using
  348. * `cloneNode()` and unexpected node are being cloned due to the slot polyfill
  349. * simulating shadow dom. Defaults to `false`.
  350. */
  351. cloneNodeFix?: IndividualFlags;
  352. /**
  353. * Experimental flag to align the behavior of invoking `textContent` on a scoped component to act more like a
  354. * component that uses the shadow DOM. Defaults to `false`
  355. */
  356. scopedSlotTextContentFix?: IndividualFlags;
  357. /**
  358. * For browsers that do not support shadow dom (IE11 and Edge 18 and below), slot is polyfilled
  359. * to simulate the same behavior. However, the host element's `childNodes` and `children`
  360. * getters are not patched to only show the child nodes and elements of the default slot.
  361. * Defaults to `false`.
  362. */
  363. slotChildNodesFix?: IndividualFlags;
  364. /**
  365. * Enables all slot-related fixes such as {@link slotChildNodesFix}, and
  366. * {@link scopedSlotTextContentFix}.
  367. */
  368. experimentalSlotFixes?: ExperimentalFixesEnabled;
  369. };
  370. export type ConfigExtras = ConfigExtrasBase & (ConfigExtrasSlotFixes<true, true> | ConfigExtrasSlotFixes<false, boolean>);
  371. export interface Config extends StencilConfig {
  372. buildAppCore?: boolean;
  373. buildDocs?: boolean;
  374. configPath?: string;
  375. writeLog?: boolean;
  376. devServer?: DevServerConfig;
  377. flags?: ConfigFlags;
  378. fsNamespace?: string;
  379. logLevel?: LogLevel;
  380. rootDir?: string;
  381. packageJsonFilePath?: string;
  382. suppressLogs?: boolean;
  383. profile?: boolean;
  384. tsCompilerOptions?: any;
  385. tsWatchOptions?: any;
  386. _isValidated?: boolean;
  387. _isTesting?: boolean;
  388. }
  389. /**
  390. * A 'loose' type useful for wrapping an incomplete / possible malformed
  391. * object as we work on getting it comply with a particular Interface T.
  392. *
  393. * Example:
  394. *
  395. * ```ts
  396. * interface Foo {
  397. * bar: string
  398. * }
  399. *
  400. * function validateFoo(foo: Loose<Foo>): Foo {
  401. * let validatedFoo = {
  402. * ...foo,
  403. * bar: foo.bar || DEFAULT_BAR
  404. * }
  405. *
  406. * return validatedFoo
  407. * }
  408. * ```
  409. *
  410. * Use this when you need to take user input or something from some other part
  411. * of the world that we don't control and transform it into something
  412. * conforming to a given interface. For best results, pair with a validation
  413. * function as shown in the example.
  414. */
  415. type Loose<T extends Object> = Record<string, any> & Partial<T>;
  416. /**
  417. * A Loose version of the Config interface. This is intended to let us load a partial config
  418. * and have type information carry though as we construct an object which is a valid `Config`.
  419. */
  420. export type UnvalidatedConfig = Loose<Config>;
  421. /**
  422. * Helper type to strip optional markers from keys in a type, while preserving other type information for the key.
  423. * This type takes a union of keys, K, in type T to allow for the type T to be gradually updated.
  424. *
  425. * ```typescript
  426. * type Foo { bar?: number, baz?: string }
  427. * type ReqFieldFoo = RequireFields<Foo, 'bar'>; // { bar: number, baz?: string }
  428. * ```
  429. */
  430. type RequireFields<T, K extends keyof T> = T & {
  431. [P in K]-?: T[P];
  432. };
  433. /**
  434. * Fields in {@link Config} to make required for {@link ValidatedConfig}
  435. */
  436. type StrictConfigFields = keyof Pick<Config, 'buildEs5' | 'cacheDir' | 'devMode' | 'devServer' | 'extras' | 'flags' | 'fsNamespace' | 'hashFileNames' | 'hashedFileNameLength' | 'hydratedFlag' | 'logLevel' | 'logger' | 'minifyCss' | 'minifyJs' | 'namespace' | 'outputTargets' | 'packageJsonFilePath' | 'rollupConfig' | 'rootDir' | 'srcDir' | 'srcIndexHtml' | 'sys' | 'testing' | 'transformAliasedImportPaths' | 'validatePrimaryPackageOutputTarget'>;
  437. /**
  438. * A version of {@link Config} that makes certain fields required. This type represents a valid configuration entity.
  439. * When a configuration is received by the user, it is a bag of unverified data. In order to make stricter guarantees
  440. * about the data from a type-safety perspective, this type is intended to be used throughout the codebase once
  441. * validations have occurred at runtime.
  442. */
  443. export type ValidatedConfig = RequireFields<Config, StrictConfigFields>;
  444. export interface HydratedFlag {
  445. /**
  446. * Defaults to `hydrated`.
  447. */
  448. name?: string;
  449. /**
  450. * Can be either `class` or `attribute`. Defaults to `class`.
  451. */
  452. selector?: 'class' | 'attribute';
  453. /**
  454. * The CSS property used to show and hide components. Defaults to use the CSS `visibility`
  455. * property. Other commonly used CSS properties would be `display` with the `initialValue`
  456. * setting as `none`, or `opacity` with the `initialValue` as `0`. Defaults to `visibility`
  457. * and the default `initialValue` is `hidden`.
  458. */
  459. property?: string;
  460. /**
  461. * This is the CSS value to give all components before it has been hydrated.
  462. * Defaults to `hidden`.
  463. */
  464. initialValue?: string;
  465. /**
  466. * This is the CSS value to assign once a component has finished hydrating.
  467. * This is the CSS value that'll allow the component to show. Defaults to `inherit`.
  468. */
  469. hydratedValue?: string;
  470. }
  471. export interface StencilDevServerConfig {
  472. /**
  473. * IP address used by the dev server. The default is `0.0.0.0`, which points to all IPv4 addresses
  474. * on the local machine, such as `localhost`.
  475. */
  476. address?: string;
  477. /**
  478. * Base path to be used by the server. Defaults to the root pathname.
  479. */
  480. basePath?: string;
  481. /**
  482. * EXPERIMENTAL!
  483. * During development, node modules can be independently requested and bundled, making for
  484. * faster build times. This is only available using the Stencil Dev Server throughout
  485. * development. Production builds and builds with the `es5` flag will override
  486. * this setting to `false`. Default is `false`.
  487. */
  488. experimentalDevModules?: boolean;
  489. /**
  490. * If the dev server should respond with gzip compressed content. Defaults to `true`.
  491. */
  492. gzip?: boolean;
  493. /**
  494. * When set, the dev server will run via https using the SSL certificate and key you provide
  495. * (use `fs` if you want to read them from files).
  496. */
  497. https?: Credentials;
  498. /**
  499. * The URL the dev server should first open to. Defaults to `/`.
  500. */
  501. initialLoadUrl?: string;
  502. /**
  503. * When `true`, every request to the server will be logged within the terminal.
  504. * Defaults to `false`.
  505. */
  506. logRequests?: boolean;
  507. /**
  508. * By default, when dev server is started the local dev URL is opened in your default browser.
  509. * However, to prevent this URL to be opened change this value to `false`. Defaults to `true`.
  510. */
  511. openBrowser?: boolean;
  512. /**
  513. * Sets the server's port. Defaults to `3333`.
  514. */
  515. port?: number;
  516. /**
  517. * When files are watched and updated, by default the dev server will use `hmr` (Hot Module Replacement)
  518. * to update the page without a full page refresh. To have the page do a full refresh use `pageReload`.
  519. * To disable any reloading, use `null`. Defaults to `hmr`.
  520. */
  521. reloadStrategy?: PageReloadStrategy;
  522. /**
  523. * Local path to a NodeJs file with a dev server request listener as the default export.
  524. * The user's request listener is given the first chance to handle every request the dev server
  525. * receives, and can choose to handle it or instead pass it on to the default dev server
  526. * by calling `next()`.
  527. *
  528. * Below is an example of a NodeJs file the `requestListenerPath` config is using.
  529. * The request and response arguments are the same as Node's `http` module and `RequestListener`
  530. * callback. https://nodejs.org/api/http.html#http_http_createserver_options_requestlistener
  531. *
  532. * ```js
  533. * module.exports = function (req, res, next) {
  534. * if (req.url === '/ping') {
  535. * // custom response overriding the dev server
  536. * res.setHeader('Content-Type', 'text/plain');
  537. * res.writeHead(200);
  538. * res.end('pong');
  539. * } else {
  540. * // pass request on to the default dev server
  541. * next();
  542. * }
  543. * };
  544. * ```
  545. */
  546. requestListenerPath?: string;
  547. /**
  548. * The root directory to serve the files from.
  549. */
  550. root?: string;
  551. /**
  552. * If the dev server should Server-Side Render (SSR) each page, meaning it'll dynamically generate
  553. * server-side rendered html on each page load. The `--ssr` flag will most commonly be used with
  554. * the`--dev --watch --serve` flags during development. Note that this is for development purposes
  555. * only, and the built-in dev server should not be used for production. Defaults to `false`.
  556. */
  557. ssr?: boolean;
  558. /**
  559. * If the dev server fails to start up within the given timeout (in milliseconds), the startup will
  560. * be canceled. Set to zero to disable the timeout. Defaults to `15000`.
  561. */
  562. startupTimeout?: number;
  563. /**
  564. * Whether to use the dev server's websocket client or not. Defaults to `true`.
  565. */
  566. websocket?: boolean;
  567. /**
  568. * If the dev server should fork a worker for the server process or not. A singled-threaded dev server
  569. * is slower, however it is useful for debugging http requests and responses. Defaults to `true`.
  570. */
  571. worker?: boolean;
  572. }
  573. export interface DevServerConfig extends StencilDevServerConfig {
  574. browserUrl?: string;
  575. devServerDir?: string;
  576. /**
  577. * A list of glob patterns like `subdir/*.js` to exclude from hot-module
  578. * reloading updates.
  579. */
  580. excludeHmr?: string[];
  581. historyApiFallback?: HistoryApiFallback;
  582. openBrowser?: boolean;
  583. prerenderConfig?: string;
  584. protocol?: 'http' | 'https';
  585. srcIndexHtml?: string;
  586. /**
  587. * Route to be used for the "ping" sub-route of the Stencil dev server.
  588. * This route will return a 200 status code once the Stencil build has finished.
  589. * Setting this to `null` will disable the ping route.
  590. *
  591. * Defaults to `/ping`
  592. */
  593. pingRoute?: string | null;
  594. }
  595. export interface HistoryApiFallback {
  596. index?: string;
  597. disableDotRule?: boolean;
  598. }
  599. export interface DevServerEditor {
  600. id: string;
  601. name?: string;
  602. supported?: boolean;
  603. priority?: number;
  604. }
  605. export type TaskCommand = 'build' | 'docs' | 'generate' | 'g' | 'help' | 'info' | 'prerender' | 'serve' | 'telemetry' | 'test' | 'version';
  606. export type PageReloadStrategy = 'hmr' | 'pageReload' | null;
  607. /**
  608. * The prerender config is used when prerendering a `www` output target.
  609. * Within `stencil.config.ts`, set the path to the prerendering
  610. * config file path using the `prerenderConfig` property, such as:
  611. *
  612. * ```tsx
  613. * import { Config } from '@stencil/core';
  614. * export const config: Config = {
  615. * outputTargets: [
  616. * {
  617. * type: 'www',
  618. * baseUrl: 'https://stenciljs.com/',
  619. * prerenderConfig: './prerender.config.ts',
  620. * }
  621. * ]
  622. * };
  623. * ```
  624. *
  625. * The `prerender.config.ts` should export a `config` object using
  626. * the `PrerenderConfig` interface.
  627. *
  628. * ```tsx
  629. * import { PrerenderConfig } from '@stencil/core';
  630. * export const config: PrerenderConfig = {
  631. * ...
  632. * };
  633. * ```
  634. *
  635. * For more info: https://stenciljs.com/docs/static-site-generation
  636. */
  637. export interface PrerenderConfig {
  638. /**
  639. * Run after each `document` is hydrated, but before it is serialized
  640. * into an HTML string. Hook is passed the `document` and its `URL`.
  641. */
  642. afterHydrate?(document: Document, url: URL, results: PrerenderUrlResults): any | Promise<any>;
  643. /**
  644. * Run before each `document` is hydrated. Hook is passed the `document` it's `URL`.
  645. */
  646. beforeHydrate?(document: Document, url: URL): any | Promise<any>;
  647. /**
  648. * Runs after the template Document object has serialize into an
  649. * HTML formatted string. Returns an HTML string to be used as the
  650. * base template for all prerendered pages.
  651. */
  652. afterSerializeTemplate?(html: string): string | Promise<string>;
  653. /**
  654. * Runs before the template Document object is serialize into an
  655. * HTML formatted string. Returns the Document to be serialized which
  656. * will become the base template html for all prerendered pages.
  657. */
  658. beforeSerializeTemplate?(document: Document): Document | Promise<Document>;
  659. /**
  660. * A hook to be used to generate the canonical `<link>` tag
  661. * which goes in the `<head>` of every prerendered page. Returning `null`
  662. * will not add a canonical url tag to the page.
  663. */
  664. canonicalUrl?(url: URL): string | null;
  665. /**
  666. * While prerendering, crawl same-origin URLs found within `<a href>` elements.
  667. * Defaults to `true`.
  668. */
  669. crawlUrls?: boolean;
  670. /**
  671. * URLs to start the prerendering from. By default the root URL of `/` is used.
  672. */
  673. entryUrls?: string[];
  674. /**
  675. * Return `true` the given `<a>` element should be crawled or not.
  676. */
  677. filterAnchor?(attrs: {
  678. [attrName: string]: string;
  679. }, base?: URL): boolean;
  680. /**
  681. * Return `true` if the given URL should be prerendered or not.
  682. */
  683. filterUrl?(url: URL, base: URL): boolean;
  684. /**
  685. * Returns the file path which the prerendered HTML content
  686. * should be written to.
  687. */
  688. filePath?(url: URL, filePath: string): string;
  689. /**
  690. * Returns the hydrate options to use for each individual prerendered page.
  691. */
  692. hydrateOptions?(url: URL): PrerenderHydrateOptions;
  693. /**
  694. * Returns the template file's content. The template is the base
  695. * HTML used for all prerendered pages.
  696. */
  697. loadTemplate?(filePath: string): string | Promise<string>;
  698. /**
  699. * Used to normalize the page's URL from a given a string and the current
  700. * page's base URL. Largely used when reading an anchor's `href` attribute
  701. * value and normalizing it into a `URL`.
  702. */
  703. normalizeUrl?(href: string, base: URL): URL;
  704. robotsTxt?(opts: RobotsTxtOpts): string | RobotsTxtResults;
  705. sitemapXml?(opts: SitemapXmpOpts): string | SitemapXmpResults;
  706. /**
  707. * Static Site Generated (SSG). Does not include Stencil's client-side
  708. * JavaScript, custom elements or preload modules.
  709. */
  710. staticSite?: boolean;
  711. /**
  712. * If the prerendered URLs should have a trailing "/"" or not. Defaults to `false`.
  713. */
  714. trailingSlash?: boolean;
  715. }
  716. export interface HydrateDocumentOptions {
  717. /**
  718. * Build ID that will be added to `<html data-stencil-build="BUILD_ID">`. By default
  719. * a random ID will be generated
  720. */
  721. buildId?: string;
  722. /**
  723. * Sets the `href` attribute on the `<link rel="canonical">`
  724. * tag within the `<head>`. If the value is not defined it will
  725. * ensure a canonical link tag is no included in the `<head>`.
  726. */
  727. canonicalUrl?: string;
  728. /**
  729. * Include the HTML comments and attributes used by the client-side
  730. * JavaScript to read the structure of the HTML and rebuild each
  731. * component. Defaults to `true`.
  732. */
  733. clientHydrateAnnotations?: boolean;
  734. /**
  735. * Constrain `setTimeout()` to 1ms, but still async. Also
  736. * only allows `setInterval()` to fire once, also constrained to 1ms.
  737. * Defaults to `true`.
  738. */
  739. constrainTimeouts?: boolean;
  740. /**
  741. * Sets `document.cookie`
  742. */
  743. cookie?: string;
  744. /**
  745. * Sets the `dir` attribute on the top level `<html>`.
  746. */
  747. direction?: string;
  748. /**
  749. * Component tag names listed here will not be prerendered, nor will
  750. * hydrated on the client-side. Components listed here will be ignored
  751. * as custom elements and treated no differently than a `<div>`.
  752. */
  753. excludeComponents?: string[];
  754. /**
  755. * Sets the `lang` attribute on the top level `<html>`.
  756. */
  757. language?: string;
  758. /**
  759. * Maximum number of components to hydrate on one page. Defaults to `300`.
  760. */
  761. maxHydrateCount?: number;
  762. /**
  763. * Sets `document.referrer`
  764. */
  765. referrer?: string;
  766. /**
  767. * Removes every `<script>` element found in the `document`. Defaults to `false`.
  768. */
  769. removeScripts?: boolean;
  770. /**
  771. * Removes CSS not used by elements within the `document`. Defaults to `true`.
  772. */
  773. removeUnusedStyles?: boolean;
  774. /**
  775. * The url the runtime uses for the resources, such as the assets directory.
  776. */
  777. resourcesUrl?: string;
  778. /**
  779. * Prints out runtime console logs to the NodeJS process. Defaults to `false`.
  780. */
  781. runtimeLogging?: boolean;
  782. /**
  783. * Component tags listed here will only be prerendered or server-side-rendered
  784. * and will not be client-side hydrated. This is useful for components that
  785. * are not dynamic and do not need to be defined as a custom element within the
  786. * browser. For example, a header or footer component would be a good example that
  787. * may not require any client-side JavaScript.
  788. */
  789. staticComponents?: string[];
  790. /**
  791. * The amount of milliseconds to wait for a page to finish rendering until
  792. * a timeout error is thrown. Defaults to `15000`.
  793. */
  794. timeout?: number;
  795. /**
  796. * Sets `document.title`.
  797. */
  798. title?: string;
  799. /**
  800. * Sets `location.href`
  801. */
  802. url?: string;
  803. /**
  804. * Sets `navigator.userAgent`
  805. */
  806. userAgent?: string;
  807. }
  808. export interface SerializeDocumentOptions extends HydrateDocumentOptions {
  809. /**
  810. * Runs after the `document` has been hydrated.
  811. */
  812. afterHydrate?(document: any): any | Promise<any>;
  813. /**
  814. * Sets an approximate line width the HTML should attempt to stay within.
  815. * Note that this is "approximate", in that HTML may often not be able
  816. * to be split at an exact line width. Additionally, new lines created
  817. * is where HTML naturally already has whitespace, such as before an
  818. * attribute or spaces between words. Defaults to `100`.
  819. */
  820. approximateLineWidth?: number;
  821. /**
  822. * Runs before the `document` has been hydrated.
  823. */
  824. beforeHydrate?(document: any): any | Promise<any>;
  825. /**
  826. * Format the HTML in a nicely indented format.
  827. * Defaults to `false`.
  828. */
  829. prettyHtml?: boolean;
  830. /**
  831. * Remove quotes from attribute values when possible.
  832. * Defaults to `true`.
  833. */
  834. removeAttributeQuotes?: boolean;
  835. /**
  836. * Remove the `=""` from standardized `boolean` attributes,
  837. * such as `hidden` or `checked`. Defaults to `true`.
  838. */
  839. removeBooleanAttributeQuotes?: boolean;
  840. /**
  841. * Remove these standardized attributes when their value is empty:
  842. * `class`, `dir`, `id`, `lang`, and `name`, `title`. Defaults to `true`.
  843. */
  844. removeEmptyAttributes?: boolean;
  845. /**
  846. * Remove HTML comments. Defaults to `true`.
  847. */
  848. removeHtmlComments?: boolean;
  849. /**
  850. * If set to `false` Stencil will ignore the fact that a component has a `shadow: true`
  851. * flag and serializes it as a scoped component. If set to `true` the component will
  852. * be rendered within a Declarative Shadow DOM.
  853. * @default false
  854. */
  855. serializeShadowRoot?: boolean;
  856. /**
  857. * The `fullDocument` flag determines the format of the rendered output. Set it to true to
  858. * generate a complete HTML document, or false to render only the component.
  859. * @default true
  860. */
  861. fullDocument?: boolean;
  862. }
  863. export interface HydrateFactoryOptions extends SerializeDocumentOptions {
  864. serializeToHtml: boolean;
  865. destroyWindow: boolean;
  866. destroyDocument: boolean;
  867. }
  868. export interface PrerenderHydrateOptions extends SerializeDocumentOptions {
  869. /**
  870. * Adds `<link rel="modulepreload">` for modules that will eventually be requested.
  871. * Defaults to `true`.
  872. */
  873. addModulePreloads?: boolean;
  874. /**
  875. * Hash the content of assets, such as images, fonts and css files,
  876. * and add the hashed value as `v` querystring. For example,
  877. * `/assets/image.png?v=abcd1234`. This allows for assets to be
  878. * heavily cached by setting the server's response header with
  879. * `Cache-Control: max-age=31536000, immutable`.
  880. */
  881. hashAssets?: 'querystring';
  882. /**
  883. * External stylesheets from `<link rel="stylesheet">` are instead inlined
  884. * into `<style>` elements. Defaults to `false`.
  885. */
  886. inlineExternalStyleSheets?: boolean;
  887. /**
  888. * Minify CSS content within `<style>` elements. Defaults to `true`.
  889. */
  890. minifyStyleElements?: boolean;
  891. /**
  892. * Minify JavaScript content within `<script>` elements. Defaults to `true`.
  893. */
  894. minifyScriptElements?: boolean;
  895. /**
  896. * Entire `document` should be static. This is useful for specific pages that
  897. * should be static, rather than the entire site. If the whole site should be static,
  898. * use the `staticSite` property on the prerender config instead. If only certain
  899. * components should be static then use `staticComponents` instead.
  900. */
  901. staticDocument?: boolean;
  902. }
  903. export interface RobotsTxtOpts {
  904. urls: string[];
  905. sitemapUrl: string;
  906. baseUrl: string;
  907. dir: string;
  908. }
  909. export interface RobotsTxtResults {
  910. content: string;
  911. filePath: string;
  912. url: string;
  913. }
  914. export interface SitemapXmpOpts {
  915. urls: string[];
  916. baseUrl: string;
  917. dir: string;
  918. }
  919. export interface SitemapXmpResults {
  920. content: string;
  921. filePath: string;
  922. url: string;
  923. }
  924. /**
  925. * Common system used by the compiler. All file reads, writes, access, etc. will all use
  926. * this system. Additionally, throughout each build, the compiler will use an internal
  927. * in-memory file system as to prevent unnecessary fs reads and writes. At the end of each
  928. * build all actions the in-memory fs performed will be written to disk using this system.
  929. * A NodeJS based system will use APIs such as `fs` and `crypto`, and a web-based system
  930. * will use in-memory Maps and browser APIs. Either way, the compiler itself is unaware
  931. * of the actual platform it's being ran on top of.
  932. */
  933. export interface CompilerSystem {
  934. name: 'node' | 'in-memory';
  935. version: string;
  936. events?: BuildEvents;
  937. details?: SystemDetails;
  938. /**
  939. * Add a callback which will be ran when destroy() is called.
  940. */
  941. addDestroy(cb: () => void): void;
  942. /**
  943. * Always returns a boolean, does not throw.
  944. */
  945. access(p: string): Promise<boolean>;
  946. /**
  947. * SYNC! Always returns a boolean, does not throw.
  948. */
  949. accessSync(p: string): boolean;
  950. applyGlobalPatch?(fromDir: string): Promise<void>;
  951. applyPrerenderGlobalPatch?(opts: {
  952. devServerHostUrl: string;
  953. window: any;
  954. }): void;
  955. cacheStorage?: CacheStorage;
  956. checkVersion?: (logger: Logger, currentVersion: string) => Promise<() => void>;
  957. copy?(copyTasks: Required<CopyTask>[], srcDir: string): Promise<CopyResults>;
  958. /**
  959. * Always returns a boolean if the files were copied or not. Does not throw.
  960. */
  961. copyFile(src: string, dst: string): Promise<boolean>;
  962. /**
  963. * Used to destroy any listeners, file watchers or child processes.
  964. */
  965. destroy(): Promise<void>;
  966. /**
  967. * Does not throw.
  968. */
  969. createDir(p: string, opts?: CompilerSystemCreateDirectoryOptions): Promise<CompilerSystemCreateDirectoryResults>;
  970. /**
  971. * SYNC! Does not throw.
  972. */
  973. createDirSync(p: string, opts?: CompilerSystemCreateDirectoryOptions): CompilerSystemCreateDirectoryResults;
  974. homeDir(): string;
  975. /**
  976. * Used to determine if the current context of the terminal is TTY.
  977. */
  978. isTTY(): boolean;
  979. /**
  980. * Each platform has a different way to dynamically import modules.
  981. */
  982. dynamicImport?(p: string): Promise<any>;
  983. /**
  984. * Creates the worker controller for the current system.
  985. *
  986. * @param maxConcurrentWorkers the max number of concurrent workers to
  987. * support
  988. * @returns a worker controller appropriate for the current platform (node.js)
  989. */
  990. createWorkerController?(maxConcurrentWorkers: number): WorkerMainController;
  991. encodeToBase64(str: string): string;
  992. /**
  993. * @deprecated
  994. */
  995. ensureDependencies?(opts: {
  996. rootDir: string;
  997. logger: Logger;
  998. dependencies: CompilerDependency[];
  999. }): Promise<{
  1000. stencilPath: string;
  1001. diagnostics: Diagnostic[];
  1002. }>;
  1003. /**
  1004. * @deprecated
  1005. */
  1006. ensureResources?(opts: {
  1007. rootDir: string;
  1008. logger: Logger;
  1009. dependencies: CompilerDependency[];
  1010. }): Promise<void>;
  1011. /**
  1012. * process.exit()
  1013. */
  1014. exit(exitCode: number): Promise<void>;
  1015. /**
  1016. * Optionally provide a fetch() function rather than using the built-in fetch().
  1017. * First arg is a url string or Request object (RequestInfo).
  1018. * Second arg is the RequestInit. Returns the Response object
  1019. */
  1020. fetch?(input: string | any, init?: any): Promise<any>;
  1021. /**
  1022. * Generates a sha1 digest encoded as HEX
  1023. */
  1024. generateContentHash?(content: string | any, length?: number): Promise<string>;
  1025. /**
  1026. * Generates a sha1 digest encoded as HEX from a file path
  1027. */
  1028. generateFileHash?(filePath: string | any, length?: number): Promise<string>;
  1029. /**
  1030. * Get the current directory.
  1031. */
  1032. getCurrentDirectory(): string;
  1033. /**
  1034. * The compiler's executing path.
  1035. */
  1036. getCompilerExecutingPath(): string;
  1037. /**
  1038. * The dev server's executing path.
  1039. */
  1040. getDevServerExecutingPath?(): string;
  1041. getEnvironmentVar?(key: string): string;
  1042. /**
  1043. * Gets the absolute file path when for a dependency module.
  1044. */
  1045. getLocalModulePath(opts: {
  1046. rootDir: string;
  1047. moduleId: string;
  1048. path: string;
  1049. }): string;
  1050. /**
  1051. * Gets the full url when requesting a dependency module to fetch from a CDN.
  1052. */
  1053. getRemoteModuleUrl(opts: {
  1054. moduleId: string;
  1055. path?: string;
  1056. version?: string;
  1057. }): string;
  1058. /**
  1059. * Async glob task. Only available in NodeJS compiler system.
  1060. */
  1061. glob?(pattern: string, options: {
  1062. cwd?: string;
  1063. nodir?: boolean;
  1064. [key: string]: any;
  1065. }): Promise<string[]>;
  1066. /**
  1067. * The number of logical processors available to run threads on the user's computer (cpus).
  1068. */
  1069. hardwareConcurrency: number;
  1070. /**
  1071. * Tests if the path is a symbolic link or not. Always resolves a boolean. Does not throw.
  1072. */
  1073. isSymbolicLink(p: string): Promise<boolean>;
  1074. lazyRequire?: LazyRequire;
  1075. nextTick(cb: () => void): void;
  1076. /**
  1077. * Normalize file system path.
  1078. */
  1079. normalizePath(p: string): string;
  1080. onProcessInterrupt?(cb: () => void): void;
  1081. parseYarnLockFile?: (content: string) => {
  1082. type: 'success' | 'merge' | 'conflict';
  1083. object: any;
  1084. };
  1085. platformPath: PlatformPath;
  1086. /**
  1087. * All return paths are full normalized paths, not just the basenames. Always returns an array, does not throw.
  1088. */
  1089. readDir(p: string): Promise<string[]>;
  1090. /**
  1091. * SYNC! All return paths are full normalized paths, not just the basenames. Always returns an array, does not throw.
  1092. */
  1093. readDirSync(p: string): string[];
  1094. /**
  1095. * Returns undefined if file is not found. Does not throw.
  1096. */
  1097. readFile(p: string): Promise<string>;
  1098. readFile(p: string, encoding: 'utf8'): Promise<string>;
  1099. readFile(p: string, encoding: 'binary'): Promise<any>;
  1100. /**
  1101. * SYNC! Returns undefined if file is not found. Does not throw.
  1102. */
  1103. readFileSync(p: string, encoding?: string): string;
  1104. /**
  1105. * Does not throw.
  1106. */
  1107. realpath(p: string): Promise<CompilerSystemRealpathResults>;
  1108. /**
  1109. * SYNC! Does not throw.
  1110. */
  1111. realpathSync(p: string): CompilerSystemRealpathResults;
  1112. /**
  1113. * Remove a callback which will be ran when destroy() is called.
  1114. */
  1115. removeDestroy(cb: () => void): void;
  1116. /**
  1117. * Rename old path to new path. Does not throw.
  1118. */
  1119. rename(oldPath: string, newPath: string): Promise<CompilerSystemRenameResults>;
  1120. resolveModuleId?(opts: ResolveModuleIdOptions): Promise<ResolveModuleIdResults>;
  1121. resolvePath(p: string): string;
  1122. /**
  1123. * Does not throw.
  1124. */
  1125. removeDir(p: string, opts?: CompilerSystemRemoveDirectoryOptions): Promise<CompilerSystemRemoveDirectoryResults>;
  1126. /**
  1127. * SYNC! Does not throw.
  1128. */
  1129. removeDirSync(p: string, opts?: CompilerSystemRemoveDirectoryOptions): CompilerSystemRemoveDirectoryResults;
  1130. /**
  1131. * Does not throw.
  1132. */
  1133. removeFile(p: string): Promise<CompilerSystemRemoveFileResults>;
  1134. /**
  1135. * SYNC! Does not throw.
  1136. */
  1137. removeFileSync(p: string): CompilerSystemRemoveFileResults;
  1138. setupCompiler?: (c: {
  1139. ts: any;
  1140. }) => void;
  1141. /**
  1142. * Always returns an object. Does not throw. Check for "error" property if there's an error.
  1143. */
  1144. stat(p: string): Promise<CompilerFsStats>;
  1145. /**
  1146. * SYNC! Always returns an object. Does not throw. Check for "error" property if there's an error.
  1147. */
  1148. statSync(p: string): CompilerFsStats;
  1149. tmpDirSync(): string;
  1150. watchDirectory?(p: string, callback: CompilerFileWatcherCallback, recursive?: boolean): CompilerFileWatcher;
  1151. /**
  1152. * A `watchFile` implementation in order to hook into the rest of the {@link CompilerSystem} implementation that is
  1153. * used when running Stencil's compiler in "watch mode".
  1154. *
  1155. * It is analogous to TypeScript's `watchFile` implementation.
  1156. *
  1157. * Note, this function may be called for full builds of Stencil projects by the TypeScript compiler. It should not
  1158. * assume that it will only be called in watch mode.
  1159. *
  1160. * This function should not perform any file watcher registration itself. Each `path` provided to it when called
  1161. * should already have been registered as a file to watch.
  1162. *
  1163. * @param path the path to the file that is being watched
  1164. * @param callback a callback to invoke when a file that is being watched has changed in some way
  1165. * @returns an object with a method for unhooking the file watcher from the system
  1166. */
  1167. watchFile?(path: string, callback: CompilerFileWatcherCallback): CompilerFileWatcher;
  1168. /**
  1169. * How many milliseconds to wait after a change before calling watch callbacks.
  1170. */
  1171. watchTimeout?: number;
  1172. /**
  1173. * Does not throw.
  1174. */
  1175. writeFile(p: string, content: string): Promise<CompilerSystemWriteFileResults>;
  1176. /**
  1177. * SYNC! Does not throw.
  1178. */
  1179. writeFileSync(p: string, content: string): CompilerSystemWriteFileResults;
  1180. }
  1181. export interface TranspileOnlyResults {
  1182. diagnostics: Diagnostic[];
  1183. output: string;
  1184. sourceMap: any;
  1185. }
  1186. export interface ParsedPath {
  1187. root: string;
  1188. dir: string;
  1189. base: string;
  1190. ext: string;
  1191. name: string;
  1192. }
  1193. export interface PlatformPath {
  1194. normalize(p: string): string;
  1195. join(...paths: string[]): string;
  1196. resolve(...pathSegments: string[]): string;
  1197. isAbsolute(p: string): boolean;
  1198. relative(from: string, to: string): string;
  1199. dirname(p: string): string;
  1200. basename(p: string, ext?: string): string;
  1201. extname(p: string): string;
  1202. parse(p: string): ParsedPath;
  1203. sep: string;
  1204. delimiter: string;
  1205. posix: any;
  1206. win32: any;
  1207. }
  1208. export interface CompilerDependency {
  1209. name: string;
  1210. version: string;
  1211. main: string;
  1212. resources?: string[];
  1213. }
  1214. export interface ResolveModuleIdOptions {
  1215. moduleId: string;
  1216. containingFile?: string;
  1217. exts?: string[];
  1218. packageFilter?: (pkg: any) => void;
  1219. }
  1220. export interface ResolveModuleIdResults {
  1221. moduleId: string;
  1222. resolveId: string;
  1223. pkgData: {
  1224. name: string;
  1225. version: string;
  1226. [key: string]: any;
  1227. };
  1228. pkgDirPath: string;
  1229. }
  1230. /**
  1231. * A controller which provides for communication and coordination between
  1232. * threaded workers.
  1233. */
  1234. export interface WorkerMainController {
  1235. /**
  1236. * Send a given set of arguments to a worker
  1237. */
  1238. send(...args: any[]): Promise<any>;
  1239. /**
  1240. * Handle a particular method
  1241. *
  1242. * @param name of the method to be passed to a worker
  1243. * @returns a Promise wrapping the results
  1244. */
  1245. handler(name: string): (...args: any[]) => Promise<any>;
  1246. /**
  1247. * Destroy the worker represented by this instance, rejecting all outstanding
  1248. * tasks and killing the child process.
  1249. */
  1250. destroy(): void;
  1251. /**
  1252. * The current setting for the max number of workers
  1253. */
  1254. maxWorkers: number;
  1255. }
  1256. export interface CopyResults {
  1257. diagnostics: Diagnostic[];
  1258. filePaths: string[];
  1259. dirPaths: string[];
  1260. }
  1261. export interface SystemDetails {
  1262. cpuModel: string;
  1263. freemem(): number;
  1264. platform: 'darwin' | 'windows' | 'linux' | '';
  1265. release: string;
  1266. totalmem: number;
  1267. }
  1268. export interface BuildOnEvents {
  1269. on(cb: (eventName: CompilerEventName, data: any) => void): BuildOnEventRemove;
  1270. on(eventName: CompilerEventFileAdd, cb: (path: string) => void): BuildOnEventRemove;
  1271. on(eventName: CompilerEventFileDelete, cb: (path: string) => void): BuildOnEventRemove;
  1272. on(eventName: CompilerEventFileUpdate, cb: (path: string) => void): BuildOnEventRemove;
  1273. on(eventName: CompilerEventDirAdd, cb: (path: string) => void): BuildOnEventRemove;
  1274. on(eventName: CompilerEventDirDelete, cb: (path: string) => void): BuildOnEventRemove;
  1275. on(eventName: CompilerEventBuildStart, cb: (buildStart: CompilerBuildStart) => void): BuildOnEventRemove;
  1276. on(eventName: CompilerEventBuildFinish, cb: (buildResults: CompilerBuildResults) => void): BuildOnEventRemove;
  1277. on(eventName: CompilerEventBuildLog, cb: (buildLog: BuildLog) => void): BuildOnEventRemove;
  1278. on(eventName: CompilerEventBuildNoChange, cb: () => void): BuildOnEventRemove;
  1279. }
  1280. export interface BuildEmitEvents {
  1281. emit(eventName: CompilerEventName, path: string): void;
  1282. emit(eventName: CompilerEventFileAdd, path: string): void;
  1283. emit(eventName: CompilerEventFileDelete, path: string): void;
  1284. emit(eventName: CompilerEventFileUpdate, path: string): void;
  1285. emit(eventName: CompilerEventDirAdd, path: string): void;
  1286. emit(eventName: CompilerEventDirDelete, path: string): void;
  1287. emit(eventName: CompilerEventBuildStart, buildStart: CompilerBuildStart): void;
  1288. emit(eventName: CompilerEventBuildFinish, buildResults: CompilerBuildResults): void;
  1289. emit(eventName: CompilerEventBuildNoChange, buildNoChange: BuildNoChangeResults): void;
  1290. emit(eventName: CompilerEventBuildLog, buildLog: BuildLog): void;
  1291. emit(eventName: CompilerEventFsChange, fsWatchResults: FsWatchResults): void;
  1292. }
  1293. export interface FsWatchResults {
  1294. dirsAdded: string[];
  1295. dirsDeleted: string[];
  1296. filesUpdated: string[];
  1297. filesAdded: string[];
  1298. filesDeleted: string[];
  1299. }
  1300. export interface BuildLog {
  1301. buildId: number;
  1302. messages: string[];
  1303. progress: number;
  1304. }
  1305. export interface BuildNoChangeResults {
  1306. buildId: number;
  1307. noChange: boolean;
  1308. }
  1309. export interface CompilerBuildResults {
  1310. buildId: number;
  1311. componentGraph?: BuildResultsComponentGraph;
  1312. diagnostics: Diagnostic[];
  1313. dirsAdded: string[];
  1314. dirsDeleted: string[];
  1315. duration: number;
  1316. filesAdded: string[];
  1317. filesChanged: string[];
  1318. filesDeleted: string[];
  1319. filesUpdated: string[];
  1320. hasError: boolean;
  1321. hasSuccessfulBuild: boolean;
  1322. hmr?: HotModuleReplacement;
  1323. hydrateAppFilePath?: string;
  1324. isRebuild: boolean;
  1325. namespace: string;
  1326. outputs: BuildOutput[];
  1327. rootDir: string;
  1328. srcDir: string;
  1329. timestamp: string;
  1330. }
  1331. export interface BuildResultsComponentGraph {
  1332. [scopeId: string]: string[];
  1333. }
  1334. export interface BuildOutput {
  1335. type: string;
  1336. files: string[];
  1337. }
  1338. export interface HotModuleReplacement {
  1339. componentsUpdated?: string[];
  1340. excludeHmr?: string[];
  1341. externalStylesUpdated?: string[];
  1342. imagesUpdated?: string[];
  1343. indexHtmlUpdated?: boolean;
  1344. inlineStylesUpdated?: HmrStyleUpdate[];
  1345. reloadStrategy: PageReloadStrategy;
  1346. scriptsAdded?: string[];
  1347. scriptsDeleted?: string[];
  1348. serviceWorkerUpdated?: boolean;
  1349. versionId?: string;
  1350. }
  1351. export interface HmrStyleUpdate {
  1352. styleId: string;
  1353. styleTag: string;
  1354. styleText: string;
  1355. }
  1356. export type BuildOnEventRemove = () => boolean;
  1357. export interface BuildEvents extends BuildOnEvents, BuildEmitEvents {
  1358. unsubscribeAll(): void;
  1359. }
  1360. export interface CompilerBuildStart {
  1361. buildId: number;
  1362. timestamp: string;
  1363. }
  1364. /**
  1365. * A type describing a function to call when an event is emitted by a file watcher
  1366. * @param fileName the path of the file tied to event
  1367. * @param eventKind a variant describing the type of event that was emitter (added, edited, etc.)
  1368. */
  1369. export type CompilerFileWatcherCallback = (fileName: string, eventKind: CompilerFileWatcherEvent) => void;
  1370. /**
  1371. * A type describing the different types of events that Stencil expects may happen when a file being watched is altered
  1372. * in some way
  1373. */
  1374. export type CompilerFileWatcherEvent = CompilerEventFileAdd | CompilerEventFileDelete | CompilerEventFileUpdate | CompilerEventDirAdd | CompilerEventDirDelete;
  1375. export type CompilerEventName = CompilerEventFsChange | CompilerEventFileUpdate | CompilerEventFileAdd | CompilerEventFileDelete | CompilerEventDirAdd | CompilerEventDirDelete | CompilerEventBuildStart | CompilerEventBuildFinish | CompilerEventBuildNoChange | CompilerEventBuildLog;
  1376. export type CompilerEventFsChange = 'fsChange';
  1377. export type CompilerEventFileUpdate = 'fileUpdate';
  1378. export type CompilerEventFileAdd = 'fileAdd';
  1379. export type CompilerEventFileDelete = 'fileDelete';
  1380. export type CompilerEventDirAdd = 'dirAdd';
  1381. export type CompilerEventDirDelete = 'dirDelete';
  1382. export type CompilerEventBuildStart = 'buildStart';
  1383. export type CompilerEventBuildFinish = 'buildFinish';
  1384. export type CompilerEventBuildLog = 'buildLog';
  1385. export type CompilerEventBuildNoChange = 'buildNoChange';
  1386. export interface CompilerFileWatcher {
  1387. close(): void | Promise<void>;
  1388. }
  1389. export interface CompilerFsStats {
  1390. /**
  1391. * If it's a directory. `false` if there was an error.
  1392. */
  1393. isDirectory: boolean;
  1394. /**
  1395. * If it's a file. `false` if there was an error.
  1396. */
  1397. isFile: boolean;
  1398. /**
  1399. * If it's a symlink. `false` if there was an error.
  1400. */
  1401. isSymbolicLink: boolean;
  1402. /**
  1403. * The size of the file in bytes. `0` for directories or if there was an error.
  1404. */
  1405. size: number;
  1406. /**
  1407. * The timestamp indicating the last time this file was modified expressed in milliseconds since the POSIX Epoch.
  1408. */
  1409. mtimeMs?: number;
  1410. /**
  1411. * Error if there was one, otherwise `null`. `stat` and `statSync` do not throw errors but always returns this interface.
  1412. */
  1413. error: any;
  1414. }
  1415. export interface CompilerSystemCreateDirectoryOptions {
  1416. /**
  1417. * Indicates whether parent directories should be created.
  1418. * @default false
  1419. */
  1420. recursive?: boolean;
  1421. /**
  1422. * A file mode. If a string is passed, it is parsed as an octal integer. If not specified
  1423. * @default 0o777.
  1424. */
  1425. mode?: number;
  1426. }
  1427. export interface CompilerSystemCreateDirectoryResults {
  1428. basename: string;
  1429. dirname: string;
  1430. path: string;
  1431. newDirs: string[];
  1432. error: any;
  1433. }
  1434. export interface CompilerSystemRemoveDirectoryOptions {
  1435. /**
  1436. * Indicates whether child files and subdirectories should be removed.
  1437. * @default false
  1438. */
  1439. recursive?: boolean;
  1440. }
  1441. export interface CompilerSystemRemoveDirectoryResults {
  1442. basename: string;
  1443. dirname: string;
  1444. path: string;
  1445. removedDirs: string[];
  1446. removedFiles: string[];
  1447. error: any;
  1448. }
  1449. export interface CompilerSystemRenameResults extends CompilerSystemRenamedPath {
  1450. renamed: CompilerSystemRenamedPath[];
  1451. oldDirs: string[];
  1452. oldFiles: string[];
  1453. newDirs: string[];
  1454. newFiles: string[];
  1455. error: any;
  1456. }
  1457. export interface CompilerSystemRenamedPath {
  1458. oldPath: string;
  1459. newPath: string;
  1460. isFile: boolean;
  1461. isDirectory: boolean;
  1462. }
  1463. export interface CompilerSystemRealpathResults {
  1464. path: string;
  1465. error: any;
  1466. }
  1467. export interface CompilerSystemRemoveFileResults {
  1468. basename: string;
  1469. dirname: string;
  1470. path: string;
  1471. error: any;
  1472. }
  1473. export interface CompilerSystemWriteFileResults {
  1474. path: string;
  1475. error: any;
  1476. }
  1477. export interface Credentials {
  1478. key: string;
  1479. cert: string;
  1480. }
  1481. export interface ConfigBundle {
  1482. components: string[];
  1483. }
  1484. /**
  1485. * A file and/or directory copy operation that may be specified as part of
  1486. * certain output targets for Stencil (in particular `dist`,
  1487. * `dist-custom-elements`, and `www`).
  1488. */
  1489. export interface CopyTask {
  1490. /**
  1491. * The source file path for a copy operation. This may be an absolute or
  1492. * relative path to a directory or a file, and may also include a glob
  1493. * pattern.
  1494. *
  1495. * If the path is a relative path it will be treated as relative to
  1496. * `Config.srcDir`.
  1497. */
  1498. src: string;
  1499. /**
  1500. * An optional destination file path for a copy operation. This may be an
  1501. * absolute or relative path.
  1502. *
  1503. * If relative, this will be treated as relative to the output directory for
  1504. * the output target for which this copy operation is configured.
  1505. */
  1506. dest?: string;
  1507. /**
  1508. * Whether or not Stencil should issue warnings if it cannot find the
  1509. * specified source files or directories. Defaults to `false`.
  1510. *
  1511. * To receive warnings if a copy task source can't be found set this to
  1512. * `true`.
  1513. */
  1514. warn?: boolean;
  1515. /**
  1516. * Whether or not directory structure should be preserved when copying files
  1517. * from a source directory. Defaults to `true` if no `dest` path is supplied,
  1518. * else it defaults to `false`.
  1519. *
  1520. * If this is set to `false`, all the files from a source directory will be
  1521. * copied directly to the destination directory, but if it's set to `true` they
  1522. * will be copied to a new directory inside the destination directory with
  1523. * the same name as their original source directory.
  1524. *
  1525. * So if, for instance, `src` is set to `"images"` and `keepDirStructure` is
  1526. * set to `true` the copy task will then produce the following directory
  1527. * structure:
  1528. *
  1529. * ```
  1530. * images
  1531. * └── foo.png
  1532. * dist
  1533. * └── images
  1534. * └── foo.png
  1535. * ```
  1536. *
  1537. * Conversely if `keepDirStructure` is set to `false` then files in `images/`
  1538. * will be copied to `dist` without first creating a new subdirectory,
  1539. * resulting in the following directory structure:
  1540. *
  1541. * ```
  1542. * images
  1543. * └── foo.png
  1544. * dist
  1545. * └── foo.png
  1546. * ```
  1547. *
  1548. * If a `dest` path is supplied then `keepDirStructure`
  1549. * will default to `false`, so that Stencil will write the
  1550. * copied files directly into the `dest` directory without creating a new
  1551. * subdirectory. This behavior can be overridden by setting
  1552. * `keepDirStructure` to `true`.
  1553. */
  1554. keepDirStructure?: boolean;
  1555. }
  1556. export interface BundlingConfig {
  1557. /**
  1558. * @deprecated the `namedExports` field is no longer honored by `@rollup/plugin-commonjs` and is not used by Stencil.
  1559. * This field can be safely removed from your Stencil configuration file.
  1560. */
  1561. namedExports?: {
  1562. [key: string]: string[];
  1563. };
  1564. }
  1565. export interface NodeResolveConfig {
  1566. module?: boolean;
  1567. jsnext?: boolean;
  1568. main?: boolean;
  1569. browser?: boolean;
  1570. extensions?: string[];
  1571. preferBuiltins?: boolean;
  1572. jail?: string;
  1573. only?: Array<string | RegExp>;
  1574. modulesOnly?: boolean;
  1575. /**
  1576. * @see https://github.com/browserify/resolve#resolveid-opts-cb
  1577. * @deprecated the `customResolveOptions` field is no longer honored in future versions of
  1578. * `@rollup/plugin-node-resolve`. If you are currently using it, please open a new issue in the Stencil repo to
  1579. * describe your use case & provide input (https://github.com/ionic-team/stencil/issues/new/choose)
  1580. */
  1581. customResolveOptions?: {
  1582. basedir?: string;
  1583. package?: string;
  1584. extensions?: string[];
  1585. readFile?: Function;
  1586. isFile?: Function;
  1587. isDirectory?: Function;
  1588. packageFilter?: Function;
  1589. pathFilter?: Function;
  1590. paths?: Function | string[];
  1591. moduleDirectory?: string | string[];
  1592. preserveSymlinks?: boolean;
  1593. };
  1594. }
  1595. export interface RollupConfig {
  1596. inputOptions?: RollupInputOptions;
  1597. outputOptions?: RollupOutputOptions;
  1598. }
  1599. export interface RollupInputOptions {
  1600. context?: string;
  1601. moduleContext?: ((id: string) => string) | {
  1602. [id: string]: string;
  1603. };
  1604. treeshake?: boolean;
  1605. external?: (string | RegExp)[] | string | RegExp | ((source: string, importer: string | undefined, isResolved: boolean) => boolean | null | undefined);
  1606. }
  1607. export interface RollupOutputOptions {
  1608. globals?: {
  1609. [name: string]: string;
  1610. } | ((name: string) => string);
  1611. }
  1612. export interface Testing {
  1613. run(opts: TestingRunOptions): Promise<boolean>;
  1614. destroy(): Promise<void>;
  1615. }
  1616. export declare type Path = string;
  1617. export declare type TransformerConfig = [string, Record<string, unknown>];
  1618. /**
  1619. * Options for initiating a run of Stencil tests (spec and/or end-to-end)
  1620. */
  1621. export interface TestingRunOptions {
  1622. /**
  1623. * If true, run end-to-end tests
  1624. */
  1625. e2e?: boolean;
  1626. /**
  1627. * If true, run screenshot tests
  1628. */
  1629. screenshot?: boolean;
  1630. /**
  1631. * If true, run spec tests
  1632. */
  1633. spec?: boolean;
  1634. /**
  1635. * If true, update 'golden' screenshots. Otherwise, compare against priori.
  1636. */
  1637. updateScreenshot?: boolean;
  1638. }
  1639. export interface JestConfig {
  1640. /**
  1641. * This option tells Jest that all imported modules in your tests should be mocked automatically.
  1642. * All modules used in your tests will have a replacement implementation, keeping the API surface. Default: false
  1643. */
  1644. automock?: boolean;
  1645. /**
  1646. * By default, Jest runs all tests and produces all errors into the console upon completion.
  1647. * The bail config option can be used here to have Jest stop running tests after the first failure. Default: false
  1648. */
  1649. bail?: boolean | number;
  1650. /**
  1651. * The directory where Jest should store its cached dependency information. Jest attempts to scan your dependency tree once (up-front)
  1652. * and cache it in order to ease some of the filesystem raking that needs to happen while running tests. This config option lets you
  1653. * customize where Jest stores that cache data on disk. Default: "/tmp/<path>"
  1654. */
  1655. cacheDirectory?: string;
  1656. /**
  1657. * Automatically clear mock calls and instances between every test. Equivalent to calling jest.clearAllMocks()
  1658. * between each test. This does not remove any mock implementation that may have been provided. Default: false
  1659. */
  1660. clearMocks?: boolean;
  1661. /**
  1662. * Indicates whether the coverage information should be collected while executing the test. Because this retrofits all
  1663. * executed files with coverage collection statements, it may significantly slow down your tests. Default: false
  1664. */
  1665. collectCoverage?: boolean;
  1666. /**
  1667. * An array of glob patterns indicating a set of files for which coverage information should be collected.
  1668. * If a file matches the specified glob pattern, coverage information will be collected for it even if no tests exist
  1669. * for this file and it's never required in the test suite. Default: undefined
  1670. */
  1671. collectCoverageFrom?: any[];
  1672. /**
  1673. * The directory where Jest should output its coverage files. Default: undefined
  1674. */
  1675. coverageDirectory?: string;
  1676. /**
  1677. * An array of regexp pattern strings that are matched against all file paths before executing the test. If the file path matches
  1678. * any of the patterns, coverage information will be skipped. These pattern strings match against the full path.
  1679. * Use the <rootDir> string token to include the path to your project's root directory to prevent it from accidentally
  1680. * ignoring all of your files in different environments that may have different root directories.
  1681. * Example: ["<rootDir>/build/", "<rootDir>/node_modules/"]. Default: ["/node_modules/"]
  1682. */
  1683. coveragePathIgnorePatterns?: any[];
  1684. /**
  1685. * A list of reporter names that Jest uses when writing coverage reports. Any istanbul reporter can be used.
  1686. * Default: `["json", "lcov", "text"]`
  1687. */
  1688. coverageReporters?: any[];
  1689. /**
  1690. * This will be used to configure minimum threshold enforcement for coverage results. Thresholds can be specified as global,
  1691. * as a glob, and as a directory or file path. If thresholds aren't met, jest will fail. Thresholds specified as a positive
  1692. * number are taken to be the minimum percentage required. Thresholds specified as a negative number represent the maximum
  1693. * number of uncovered entities allowed. Default: undefined
  1694. */
  1695. coverageThreshold?: any;
  1696. errorOnDeprecated?: boolean;
  1697. forceCoverageMatch?: any[];
  1698. globals?: any;
  1699. globalSetup?: string;
  1700. globalTeardown?: string;
  1701. /**
  1702. * An array of directory names to be searched recursively up from the requiring module's location. Setting this option will
  1703. * override the default, if you wish to still search node_modules for packages include it along with any other
  1704. * options: ["node_modules", "bower_components"]. Default: ["node_modules"]
  1705. */
  1706. moduleDirectories?: string[];
  1707. /**
  1708. * An array of file extensions your modules use. If you require modules without specifying a file extension,
  1709. * these are the extensions Jest will look for. Default: ['ts', 'tsx', 'js', 'json']
  1710. */
  1711. moduleFileExtensions?: string[];
  1712. moduleNameMapper?: any;
  1713. modulePaths?: any[];
  1714. modulePathIgnorePatterns?: any[];
  1715. notify?: boolean;
  1716. notifyMode?: string;
  1717. preset?: string;
  1718. prettierPath?: string;
  1719. projects?: any;
  1720. reporters?: any;
  1721. resetMocks?: boolean;
  1722. resetModules?: boolean;
  1723. resolver?: Path | null;
  1724. restoreMocks?: boolean;
  1725. rootDir?: string;
  1726. roots?: any[];
  1727. runner?: string;
  1728. /**
  1729. * The paths to modules that run some code to configure or set up the testing environment before each test.
  1730. * Since every test runs in its own environment, these scripts will be executed in the testing environment
  1731. * immediately before executing the test code itself. Default: []
  1732. */
  1733. setupFiles?: string[];
  1734. setupFilesAfterEnv?: string[];
  1735. snapshotSerializers?: any[];
  1736. testEnvironment?: string;
  1737. testEnvironmentOptions?: any;
  1738. testMatch?: string[];
  1739. testPathIgnorePatterns?: string[];
  1740. testPreset?: string;
  1741. testRegex?: string[];
  1742. testResultsProcessor?: string;
  1743. testRunner?: string;
  1744. testURL?: string;
  1745. timers?: string;
  1746. transform?: {
  1747. [regex: string]: Path | TransformerConfig;
  1748. };
  1749. transformIgnorePatterns?: any[];
  1750. unmockedModulePathPatterns?: any[];
  1751. verbose?: boolean;
  1752. watchPathIgnorePatterns?: any[];
  1753. }
  1754. export interface TestingConfig extends JestConfig {
  1755. /**
  1756. * The `allowableMismatchedPixels` value is used to determine an acceptable
  1757. * number of pixels that can be mismatched before the image is considered
  1758. * to have changes. Realistically, two screenshots representing the same
  1759. * content may have a small number of pixels that are not identical due to
  1760. * anti-aliasing, which is perfectly normal. If the `allowableMismatchedRatio`
  1761. * is provided it will take precedence, otherwise `allowableMismatchedPixels`
  1762. * will be used.
  1763. */
  1764. allowableMismatchedPixels?: number;
  1765. /**
  1766. * The `allowableMismatchedRatio` ranges from `0` to `1` and is used to
  1767. * determine an acceptable ratio of pixels that can be mismatched before
  1768. * the image is considered to have changes. Realistically, two screenshots
  1769. * representing the same content may have a small number of pixels that
  1770. * are not identical due to anti-aliasing, which is perfectly normal. The
  1771. * `allowableMismatchedRatio` is the number of pixels that were mismatched,
  1772. * divided by the total number of pixels in the screenshot. For example,
  1773. * a ratio value of `0.06` means 6% of the pixels can be mismatched before
  1774. * the image is considered to have changes. If the `allowableMismatchedRatio`
  1775. * is provided it will take precedence, otherwise `allowableMismatchedPixels`
  1776. * will be used.
  1777. */
  1778. allowableMismatchedRatio?: number;
  1779. /**
  1780. * Matching threshold while comparing two screenshots. Value ranges from `0` to `1`.
  1781. * Smaller values make the comparison more sensitive. The `pixelmatchThreshold`
  1782. * value helps to ignore anti-aliasing. Default: `0.1`
  1783. */
  1784. pixelmatchThreshold?: number;
  1785. /**
  1786. * Additional arguments to pass to the browser instance.
  1787. */
  1788. browserArgs?: string[];
  1789. /**
  1790. * Path to a Chromium or Chrome executable to run instead of the bundled Chromium.
  1791. */
  1792. browserExecutablePath?: string;
  1793. /**
  1794. * Url of remote Chrome instance to use instead of local Chrome.
  1795. */
  1796. browserWSEndpoint?: string;
  1797. /**
  1798. * Whether to run browser e2e tests in headless mode.
  1799. *
  1800. * Starting with Chrome v112, a new headless mode was introduced.
  1801. * The new headless mode unifies the "headful" and "headless" code paths in the Chrome distributable.
  1802. *
  1803. * To enable the "new" headless mode, a string value of "new" must be provided.
  1804. * To use the "old" headless mode, a boolean value of `true` must be provided.
  1805. * To use "headful" mode, a boolean value of `false` must be provided.
  1806. *
  1807. * Defaults to true.
  1808. */
  1809. browserHeadless?: boolean | 'new';
  1810. /**
  1811. * Slows down e2e browser operations by the specified amount of milliseconds.
  1812. * Useful so that you can see what is going on.
  1813. */
  1814. browserSlowMo?: number;
  1815. /**
  1816. * By default, all E2E pages wait until the "load" event, this global setting can be used
  1817. * to change the default `waitUntil` behavior.
  1818. */
  1819. browserWaitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
  1820. /**
  1821. * Whether to auto-open a DevTools panel for each tab.
  1822. * If this option is true, the headless option will be set false
  1823. */
  1824. browserDevtools?: boolean;
  1825. /**
  1826. * Array of browser emulations to be used during _screenshot_ tests. A full screenshot
  1827. * test is ran for each emulation.
  1828. *
  1829. * To emulate a device display for your e2e tests, use the `setViewport` method on a test's E2E page.
  1830. * An example can be found in [the Stencil docs](https://stenciljs.com/docs/end-to-end-testing#emulate-a-display).
  1831. */
  1832. emulate?: EmulateConfig[];
  1833. /**
  1834. * Path to the Screenshot Connector module.
  1835. */
  1836. screenshotConnector?: string;
  1837. /**
  1838. * Timeout for the pixelmatch worker to resolve (in ms).
  1839. * @default 2500
  1840. */
  1841. screenshotTimeout?: number | null;
  1842. /**
  1843. * Amount of time in milliseconds to wait before a screenshot is taken.
  1844. */
  1845. waitBeforeScreenshot?: number;
  1846. }
  1847. export interface EmulateConfig {
  1848. /**
  1849. * Predefined device descriptor name, such as "iPhone X" or "Nexus 10".
  1850. * For a complete list please see: https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts
  1851. */
  1852. device?: string;
  1853. /**
  1854. * User-Agent to be used. Defaults to the user-agent of the installed Puppeteer version.
  1855. */
  1856. userAgent?: string;
  1857. viewport?: EmulateViewport;
  1858. }
  1859. export interface EmulateViewport {
  1860. /**
  1861. * Page width in pixels.
  1862. */
  1863. width: number;
  1864. /**
  1865. * page height in pixels.
  1866. */
  1867. height: number;
  1868. /**
  1869. * Specify device scale factor (can be thought of as dpr). Defaults to 1.
  1870. */
  1871. deviceScaleFactor?: number;
  1872. /**
  1873. * Whether the meta viewport tag is taken into account. Defaults to false.
  1874. */
  1875. isMobile?: boolean;
  1876. /**
  1877. * Specifies if viewport supports touch events. Defaults to false
  1878. */
  1879. hasTouch?: boolean;
  1880. /**
  1881. * Specifies if viewport is in landscape mode. Defaults to false.
  1882. */
  1883. isLandscape?: boolean;
  1884. }
  1885. /**
  1886. * This sets the log level hierarchy for our terminal logger, ranging from
  1887. * most to least verbose.
  1888. *
  1889. * Ordering the levels like this lets us easily check whether we should log a
  1890. * message at a given time. For instance, if the log level is set to `'warn'`,
  1891. * then anything passed to the logger with level `'warn'` or `'error'` should
  1892. * be logged, but we should _not_ log anything with level `'info'` or `'debug'`.
  1893. *
  1894. * If we have a current log level `currentLevel` and a message with level
  1895. * `msgLevel` is passed to the logger, we can determine whether or not we should
  1896. * log it by checking if the log level on the message is further up or at the
  1897. * same level in the hierarchy than `currentLevel`, like so:
  1898. *
  1899. * ```ts
  1900. * LOG_LEVELS.indexOf(msgLevel) >= LOG_LEVELS.indexOf(currentLevel)
  1901. * ```
  1902. *
  1903. * NOTE: for the reasons described above, do not change the order of the entries
  1904. * in this array without good reason!
  1905. */
  1906. export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
  1907. export type LogLevel = (typeof LOG_LEVELS)[number];
  1908. /**
  1909. * Abstract interface representing a logger with the capability to accept log
  1910. * messages at various levels (debug, info, warn, and error), set colors, log
  1911. * time spans, print diagnostic messages, and more.
  1912. *
  1913. * A Node.js-specific implementation of this interface is used when Stencil is
  1914. * building and compiling a project.
  1915. */
  1916. export interface Logger {
  1917. enableColors: (useColors: boolean) => void;
  1918. setLevel: (level: LogLevel) => void;
  1919. getLevel: () => LogLevel;
  1920. debug: (...msg: any[]) => void;
  1921. info: (...msg: any[]) => void;
  1922. warn: (...msg: any[]) => void;
  1923. error: (...msg: any[]) => void;
  1924. createTimeSpan: (startMsg: string, debug?: boolean, appendTo?: string[]) => LoggerTimeSpan;
  1925. printDiagnostics: (diagnostics: Diagnostic[], cwd?: string) => void;
  1926. red: (msg: string) => string;
  1927. green: (msg: string) => string;
  1928. yellow: (msg: string) => string;
  1929. blue: (msg: string) => string;
  1930. magenta: (msg: string) => string;
  1931. cyan: (msg: string) => string;
  1932. gray: (msg: string) => string;
  1933. bold: (msg: string) => string;
  1934. dim: (msg: string) => string;
  1935. bgRed: (msg: string) => string;
  1936. emoji: (e: string) => string;
  1937. setLogFilePath?: (p: string) => void;
  1938. writeLogs?: (append: boolean) => void;
  1939. createLineUpdater?: () => Promise<LoggerLineUpdater>;
  1940. }
  1941. export interface LoggerLineUpdater {
  1942. update(text: string): Promise<void>;
  1943. stop(): Promise<void>;
  1944. }
  1945. export interface LoggerTimeSpan {
  1946. duration(): number;
  1947. finish(finishedMsg: string, color?: string, bold?: boolean, newLineSuffix?: boolean): number;
  1948. }
  1949. export interface OutputTargetDist extends OutputTargetValidationConfig {
  1950. type: 'dist';
  1951. buildDir?: string;
  1952. collectionDir?: string | null;
  1953. /**
  1954. * When `true` this flag will transform aliased import paths defined in
  1955. * a project's `tsconfig.json` to relative import paths in the compiled output's
  1956. * `dist-collection` bundle if it is generated (i.e. `collectionDir` is set).
  1957. *
  1958. * Paths will be left in aliased format if `false`.
  1959. *
  1960. * @example
  1961. * // tsconfig.json
  1962. * {
  1963. * paths: {
  1964. * "@utils/*": ['/src/utils/*']
  1965. * }
  1966. * }
  1967. *
  1968. * // Source file
  1969. * import * as dateUtils from '@utils/date-utils';
  1970. * // Output file
  1971. * import * as dateUtils from '../utils/date-utils';
  1972. */
  1973. transformAliasedImportPathsInCollection?: boolean | null;
  1974. typesDir?: string;
  1975. /**
  1976. * Provide a custom path for the ESM loader directory, containing files you can import
  1977. * in an initiation script within your application to register all your components for
  1978. * lazy loading.
  1979. *
  1980. * @default /dist/loader
  1981. */
  1982. esmLoaderPath?: string;
  1983. copy?: CopyTask[];
  1984. polyfills?: boolean;
  1985. empty?: boolean;
  1986. }
  1987. export interface OutputTargetDistCollection extends OutputTargetValidationConfig {
  1988. type: 'dist-collection';
  1989. empty?: boolean;
  1990. dir: string;
  1991. collectionDir: string;
  1992. /**
  1993. * When `true` this flag will transform aliased import paths defined in
  1994. * a project's `tsconfig.json` to relative import paths in the compiled output.
  1995. *
  1996. * Paths will be left in aliased format if `false` or `undefined`.
  1997. *
  1998. * @example
  1999. * // tsconfig.json
  2000. * {
  2001. * paths: {
  2002. * "@utils/*": ['/src/utils/*']
  2003. * }
  2004. * }
  2005. *
  2006. * // Source file
  2007. * import * as dateUtils from '@utils/date-utils';
  2008. * // Output file
  2009. * import * as dateUtils from '../utils/date-utils';
  2010. */
  2011. transformAliasedImportPaths?: boolean | null;
  2012. }
  2013. export interface OutputTargetDistTypes extends OutputTargetValidationConfig {
  2014. type: 'dist-types';
  2015. dir: string;
  2016. typesDir: string;
  2017. }
  2018. export interface OutputTargetDistLazy extends OutputTargetBase {
  2019. type: 'dist-lazy';
  2020. dir?: string;
  2021. esmDir?: string;
  2022. esmEs5Dir?: string;
  2023. systemDir?: string;
  2024. cjsDir?: string;
  2025. polyfills?: boolean;
  2026. isBrowserBuild?: boolean;
  2027. esmIndexFile?: string;
  2028. cjsIndexFile?: string;
  2029. systemLoaderFile?: string;
  2030. legacyLoaderFile?: string;
  2031. empty?: boolean;
  2032. }
  2033. export interface OutputTargetDistGlobalStyles extends OutputTargetBase {
  2034. type: 'dist-global-styles';
  2035. file: string;
  2036. }
  2037. export interface OutputTargetDistLazyLoader extends OutputTargetBase {
  2038. type: 'dist-lazy-loader';
  2039. dir: string;
  2040. esmDir: string;
  2041. esmEs5Dir?: string;
  2042. cjsDir: string;
  2043. componentDts: string;
  2044. empty: boolean;
  2045. }
  2046. export interface OutputTargetHydrate extends OutputTargetBase {
  2047. type: 'dist-hydrate-script';
  2048. dir?: string;
  2049. /**
  2050. * Module IDs that should not be bundled into the script.
  2051. * By default, all node builtin's, such as `fs` or `path`
  2052. * will be considered "external" and not bundled.
  2053. */
  2054. external?: string[];
  2055. empty?: boolean;
  2056. }
  2057. export interface OutputTargetCustom extends OutputTargetBase {
  2058. type: 'custom';
  2059. name: string;
  2060. /**
  2061. * Indicate when the output target should be executed.
  2062. *
  2063. * - `"onBuildOnly"`: Executed only when `stencil build` is called without `--watch`.
  2064. * - `"always"`: Executed on every build, including in `watch` mode.
  2065. *
  2066. * Defaults to "always".
  2067. */
  2068. taskShouldRun?: 'onBuildOnly' | 'always';
  2069. validate?: (config: Config, diagnostics: Diagnostic[]) => void;
  2070. generator: (config: Config, compilerCtx: CompilerCtx, buildCtx: BuildCtx, docs: JsonDocs) => Promise<void>;
  2071. copy?: CopyTask[];
  2072. }
  2073. /**
  2074. * Output target for generating [custom data](https://github.com/microsoft/vscode-custom-data) for VS Code as a JSON
  2075. * file.
  2076. */
  2077. export interface OutputTargetDocsVscode extends OutputTargetBase {
  2078. /**
  2079. * Designates this output target to be used for generating VS Code custom data.
  2080. * @see OutputTargetBase#type
  2081. */
  2082. type: 'docs-vscode';
  2083. /**
  2084. * The location on disk to write the JSON file.
  2085. */
  2086. file: string;
  2087. /**
  2088. * A base URL to find the source code of the component(s) described in the JSON file.
  2089. */
  2090. sourceCodeBaseUrl?: string;
  2091. }
  2092. export interface OutputTargetDocsReadme extends OutputTargetBase {
  2093. type: 'docs-readme';
  2094. /**
  2095. * The root directory where README files should be written
  2096. *
  2097. * defaults to {@link Config.srcDir}
  2098. */
  2099. dir?: string;
  2100. dependencies?: boolean;
  2101. footer?: string;
  2102. strict?: boolean;
  2103. }
  2104. export interface OutputTargetDocsJson extends OutputTargetBase {
  2105. type: 'docs-json';
  2106. file: string;
  2107. /**
  2108. * Set an optional file path where Stencil should write a `d.ts` file to disk
  2109. * at build-time containing type declarations for {@link JsonDocs} and related
  2110. * interfaces. If this is omitted or set to `null` Stencil will not write such
  2111. * a file.
  2112. */
  2113. typesFile?: string | null;
  2114. strict?: boolean;
  2115. /**
  2116. * An optional file path pointing to a public type library which should be
  2117. * included and documented in the same way as other types which are included
  2118. * in this output target.
  2119. *
  2120. * This could be useful if, for instance, there are some important interfaces
  2121. * used in a few places in a Stencil project which don't form part of the
  2122. * public API for any of the project's components. Such interfaces will not
  2123. * be included in the `docs-json` output by default, but if they're declared
  2124. * and exported from a 'supplemental' file designated with this property then
  2125. * they'll be included in the output, facilitating their documentation.
  2126. */
  2127. supplementalPublicTypes?: string;
  2128. }
  2129. export interface OutputTargetDocsCustom extends OutputTargetBase {
  2130. type: 'docs-custom';
  2131. generator: (docs: JsonDocs, config: Config) => void | Promise<void>;
  2132. strict?: boolean;
  2133. }
  2134. export interface OutputTargetStats extends OutputTargetBase {
  2135. type: 'stats';
  2136. file?: string;
  2137. }
  2138. export interface OutputTargetBaseNext {
  2139. type: string;
  2140. dir?: string;
  2141. }
  2142. /**
  2143. * The collection of valid export behaviors.
  2144. * Used to generate a type for typed configs as well as output target validation
  2145. * for the `dist-custom-elements` output target.
  2146. *
  2147. * Adding a value to this const array will automatically add it as a valid option on the
  2148. * output target configuration for `customElementsExportBehavior`.
  2149. *
  2150. * - `default`: No additional export or definition behavior will happen.
  2151. * - `auto-define-custom-elements`: Enables the auto-definition of a component and its children (recursively) in the custom elements registry. This
  2152. * functionality allows consumers to bypass the explicit call to define a component, its children, its children's
  2153. * children, etc. Users of this flag should be aware that enabling this functionality may increase bundle size.
  2154. * - `bundle`: A `defineCustomElements` function will be exported from the distribution directory. This behavior was added to allow easy migration
  2155. * from `dist-custom-elements-bundle` to `dist-custom-elements`.
  2156. * - `single-export-module`: All components will be re-exported from the specified directory's root `index.js` file.
  2157. */
  2158. export declare const CustomElementsExportBehaviorOptions: readonly ["default", "auto-define-custom-elements", "bundle", "single-export-module"];
  2159. /**
  2160. * This type is auto-generated based on the values in `CustomElementsExportBehaviorOptions` array.
  2161. * This is used on the output target config for intellisense in typed configs.
  2162. */
  2163. export type CustomElementsExportBehavior = (typeof CustomElementsExportBehaviorOptions)[number];
  2164. export interface OutputTargetDistCustomElements extends OutputTargetValidationConfig {
  2165. type: 'dist-custom-elements';
  2166. empty?: boolean;
  2167. /**
  2168. * Triggers the following behaviors when enabled:
  2169. * 1. All `@stencil/core/*` module references are treated as external during bundling.
  2170. * 2. File names are not hashed.
  2171. * 3. File minification will follow the behavior defined at the root of the Stencil config.
  2172. */
  2173. externalRuntime?: boolean;
  2174. copy?: CopyTask[];
  2175. includeGlobalScripts?: boolean;
  2176. minify?: boolean;
  2177. /**
  2178. * Enables the generation of type definition files for the output target.
  2179. */
  2180. generateTypeDeclarations?: boolean;
  2181. /**
  2182. * Define the export/definition behavior for the output target's generated output.
  2183. * This controls if/how custom elements will be defined or where components will be exported from.
  2184. * If omitted, no auto-definition behavior or re-exporting will happen.
  2185. */
  2186. customElementsExportBehavior?: CustomElementsExportBehavior;
  2187. }
  2188. /**
  2189. * The base type for output targets. All output targets should extend this base type.
  2190. */
  2191. export interface OutputTargetBase {
  2192. /**
  2193. * A unique string to differentiate one output target from another
  2194. */
  2195. type: string;
  2196. }
  2197. /**
  2198. * Output targets that can have validation for common `package.json` field values
  2199. * (module, types, etc.). This allows them to be marked for validation in a project's Stencil config.
  2200. */
  2201. interface OutputTargetValidationConfig extends OutputTargetBaseNext {
  2202. isPrimaryPackageOutputTarget?: boolean;
  2203. }
  2204. export type EligiblePrimaryPackageOutputTarget = OutputTargetDist | OutputTargetDistCustomElements | OutputTargetDistCollection | OutputTargetDistTypes;
  2205. export type OutputTargetBuild = OutputTargetDistCollection | OutputTargetDistLazy;
  2206. export interface OutputTargetCopy extends OutputTargetBase {
  2207. type: 'copy';
  2208. dir: string;
  2209. copy?: CopyTask[];
  2210. copyAssets?: 'collection' | 'dist';
  2211. }
  2212. export interface OutputTargetWww extends OutputTargetBase {
  2213. /**
  2214. * Webapp output target.
  2215. */
  2216. type: 'www';
  2217. /**
  2218. * The directory to write the app's JavaScript and CSS build
  2219. * files to. The default is to place this directory as a child
  2220. * to the `dir` config. Default: `build`
  2221. */
  2222. buildDir?: string;
  2223. /**
  2224. * The directory to write the entire application to.
  2225. * Note, the `buildDir` is where the app's JavaScript and CSS build
  2226. * files are written. Default: `www`
  2227. */
  2228. dir?: string;
  2229. /**
  2230. * Empty the build directory of all files and directories on first build.
  2231. * Default: `true`
  2232. */
  2233. empty?: boolean;
  2234. /**
  2235. * The default index html file of the app, commonly found at the
  2236. * root of the `src` directory.
  2237. * Default: `index.html`
  2238. */
  2239. indexHtml?: string;
  2240. /**
  2241. * The copy config is an array of objects that defines any files or folders that should
  2242. * be copied over to the build directory.
  2243. *
  2244. * Each object in the array must include a src property which can be either an absolute path,
  2245. * a relative path or a glob pattern. The config can also provide an optional dest property
  2246. * which can be either an absolute path or a path relative to the build directory.
  2247. * Also note that any files within src/assets are automatically copied to www/assets for convenience.
  2248. *
  2249. * In the copy config below, it will copy the entire directory from src/docs-content over to www/docs-content.
  2250. */
  2251. copy?: CopyTask[];
  2252. /**
  2253. * The base url of the app, it's required during prerendering to be the absolute path
  2254. * of your app, such as: `https://my.app.com/app`.
  2255. *
  2256. * Default: `/`
  2257. */
  2258. baseUrl?: string;
  2259. /**
  2260. * By default, stencil will include all the polyfills required by legacy browsers in the ES5 build.
  2261. * If it's `false`, stencil will not emit this polyfills anymore and it's your responsibility to provide them before
  2262. * stencil initializes.
  2263. */
  2264. polyfills?: boolean;
  2265. /**
  2266. * Path to an external node module which has exports of the prerender config object.
  2267. * ```
  2268. * module.exports = {
  2269. * afterHydrate(document, url) {
  2270. * document.title = `URL: ${url.href}`;
  2271. * }
  2272. * }
  2273. * ```
  2274. */
  2275. prerenderConfig?: string;
  2276. /**
  2277. * Service worker config for production builds. During development builds
  2278. * service worker script will be injected to automatically deregister existing
  2279. * service workers. When set to `false` neither a service worker registration
  2280. * or deregistration will be added to the index.html.
  2281. */
  2282. serviceWorker?: ServiceWorkerConfig | null | false;
  2283. appDir?: string;
  2284. }
  2285. export type OutputTarget = OutputTargetCopy | OutputTargetCustom | OutputTargetDist | OutputTargetDistCollection | OutputTargetDistCustomElements | OutputTargetDistLazy | OutputTargetDistGlobalStyles | OutputTargetDistLazyLoader | OutputTargetDocsJson | OutputTargetDocsCustom | OutputTargetDocsReadme | OutputTargetDocsVscode | OutputTargetWww | OutputTargetHydrate | OutputTargetStats | OutputTargetDistTypes;
  2286. /**
  2287. * Our custom configuration interface for generated caching Service Workers
  2288. * using the Workbox library (see https://developer.chrome.com/docs/workbox/).
  2289. *
  2290. * Although we are using Workbox we are unfortunately unable to depend on the
  2291. * published types for the library because they must be compiled using the
  2292. * `webworker` lib for TypeScript, which cannot be used at the same time as
  2293. * the `dom` lib. So as a workaround we maintain our own interface here. See
  2294. * here to refer to the published version:
  2295. * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/c7b4dadae5b320ad1311a8f82242b8f2f41b7b8c/types/workbox-build/generate-sw.d.ts#L3
  2296. */
  2297. export interface ServiceWorkerConfig {
  2298. unregister?: boolean;
  2299. swDest?: string;
  2300. swSrc?: string;
  2301. globPatterns?: string[];
  2302. globDirectory?: string | string[];
  2303. globIgnores?: string | string[];
  2304. templatedUrls?: any;
  2305. maximumFileSizeToCacheInBytes?: number;
  2306. manifestTransforms?: any;
  2307. modifyUrlPrefix?: any;
  2308. dontCacheBustURLsMatching?: RegExp;
  2309. navigateFallback?: string;
  2310. navigateFallbackWhitelist?: RegExp[];
  2311. navigateFallbackBlacklist?: RegExp[];
  2312. cacheId?: string;
  2313. skipWaiting?: boolean;
  2314. clientsClaim?: boolean;
  2315. directoryIndex?: string;
  2316. runtimeCaching?: any[];
  2317. ignoreUrlParametersMatching?: any[];
  2318. handleFetch?: boolean;
  2319. }
  2320. export interface LoadConfigInit {
  2321. /**
  2322. * User config object to merge into default config and
  2323. * config loaded from a file path.
  2324. */
  2325. config?: UnvalidatedConfig;
  2326. /**
  2327. * Absolute path to a Stencil config file. This path cannot be
  2328. * relative and it does not resolve config files within a directory.
  2329. */
  2330. configPath?: string;
  2331. logger?: Logger;
  2332. sys?: CompilerSystem;
  2333. /**
  2334. * When set to true, if the "tsconfig.json" file is not found
  2335. * it'll automatically generate and save a default tsconfig
  2336. * within the root directory.
  2337. */
  2338. initTsConfig?: boolean;
  2339. }
  2340. /**
  2341. * Results from an attempt to load a config. The values on this interface
  2342. * have not yet been validated and are not ready to be used for arbitrary
  2343. * operations around the codebase.
  2344. */
  2345. export interface LoadConfigResults {
  2346. config: ValidatedConfig;
  2347. diagnostics: Diagnostic[];
  2348. tsconfig: {
  2349. path: string;
  2350. compilerOptions: any;
  2351. files: string[];
  2352. include: string[];
  2353. exclude: string[];
  2354. extends: string;
  2355. };
  2356. }
  2357. export interface Diagnostic {
  2358. absFilePath?: string | undefined;
  2359. code?: string;
  2360. columnNumber?: number | undefined;
  2361. debugText?: string;
  2362. header?: string;
  2363. language?: string;
  2364. level: 'error' | 'warn' | 'info' | 'log' | 'debug';
  2365. lineNumber?: number | undefined;
  2366. lines: PrintLine[];
  2367. messageText: string;
  2368. relFilePath?: string | undefined;
  2369. type: string;
  2370. }
  2371. export interface CacheStorage {
  2372. get(key: string): Promise<any>;
  2373. set(key: string, value: any): Promise<void>;
  2374. }
  2375. export interface WorkerOptions {
  2376. maxConcurrentWorkers?: number;
  2377. maxConcurrentTasksPerWorker?: number;
  2378. logger?: Logger;
  2379. }
  2380. export interface RollupInterface {
  2381. rollup: {
  2382. (config: any): Promise<any>;
  2383. };
  2384. plugins: {
  2385. nodeResolve(opts: any): any;
  2386. replace(opts: any): any;
  2387. commonjs(opts: any): any;
  2388. json(): any;
  2389. };
  2390. }
  2391. export interface ResolveModuleOptions {
  2392. manuallyResolve?: boolean;
  2393. packageJson?: boolean;
  2394. }
  2395. export interface PrerenderStartOptions {
  2396. buildId?: string;
  2397. hydrateAppFilePath?: string;
  2398. componentGraph?: BuildResultsComponentGraph;
  2399. srcIndexHtmlPath?: string;
  2400. }
  2401. export interface PrerenderResults {
  2402. buildId: string;
  2403. diagnostics: Diagnostic[];
  2404. urls: number;
  2405. duration: number;
  2406. average: number;
  2407. }
  2408. /**
  2409. * Input for CSS optimization functions, including the input CSS
  2410. * string and a few boolean options which turn on or off various
  2411. * optimizations.
  2412. */
  2413. export interface OptimizeCssInput {
  2414. input: string;
  2415. filePath?: string;
  2416. autoprefixer?: boolean | null | AutoprefixerOptions;
  2417. minify?: boolean;
  2418. sourceMap?: boolean;
  2419. resolveUrl?: (url: string) => Promise<string> | string;
  2420. }
  2421. /**
  2422. * This is not a real interface describing the options which can
  2423. * be passed to autoprefixer, for that see the docs, here:
  2424. * https://github.com/postcss/autoprefixer#options
  2425. *
  2426. * Instead, this basically just serves as a label type to track
  2427. * that arguments are being passed consistently.
  2428. */
  2429. export type AutoprefixerOptions = Object;
  2430. /**
  2431. * Output from CSS optimization functions, wrapping up optimized
  2432. * CSS and any diagnostics produced during optimization.
  2433. */
  2434. export interface OptimizeCssOutput {
  2435. output: string;
  2436. diagnostics: Diagnostic[];
  2437. }
  2438. export interface OptimizeJsInput {
  2439. input: string;
  2440. filePath?: string;
  2441. target?: 'es5' | 'latest';
  2442. pretty?: boolean;
  2443. sourceMap?: boolean;
  2444. }
  2445. export interface OptimizeJsOutput {
  2446. output: string;
  2447. sourceMap: any;
  2448. diagnostics: Diagnostic[];
  2449. }
  2450. export interface LazyRequire {
  2451. ensure(fromDir: string, moduleIds: string[]): Promise<Diagnostic[]>;
  2452. require(fromDir: string, moduleId: string): any;
  2453. getModulePath(fromDir: string, moduleId: string): string;
  2454. }
  2455. /**
  2456. * @deprecated This interface is no longer used by Stencil
  2457. * TODO(STENCIL-743): Remove this interface
  2458. */
  2459. export interface FsWatcherItem {
  2460. close(): void;
  2461. }
  2462. /**
  2463. * @deprecated This interface is no longer used by Stencil
  2464. * TODO(STENCIL-743): Remove this interface
  2465. */
  2466. export interface MakeDirectoryOptions {
  2467. /**
  2468. * Indicates whether parent folders should be created.
  2469. * @default false
  2470. */
  2471. recursive?: boolean;
  2472. /**
  2473. * A file mode. If a string is passed, it is parsed as an octal integer. If not specified
  2474. * @default 0o777.
  2475. */
  2476. mode?: number;
  2477. }
  2478. /**
  2479. * @deprecated This interface is no longer used by Stencil
  2480. * TODO(STENCIL-743): Remove this interface
  2481. */
  2482. export interface FsStats {
  2483. isFile(): boolean;
  2484. isDirectory(): boolean;
  2485. isBlockDevice(): boolean;
  2486. isCharacterDevice(): boolean;
  2487. isSymbolicLink(): boolean;
  2488. isFIFO(): boolean;
  2489. isSocket(): boolean;
  2490. dev: number;
  2491. ino: number;
  2492. mode: number;
  2493. nlink: number;
  2494. uid: number;
  2495. gid: number;
  2496. rdev: number;
  2497. size: number;
  2498. blksize: number;
  2499. blocks: number;
  2500. atime: Date;
  2501. mtime: Date;
  2502. ctime: Date;
  2503. birthtime: Date;
  2504. }
  2505. export interface Compiler {
  2506. build(): Promise<CompilerBuildResults>;
  2507. createWatcher(): Promise<CompilerWatcher>;
  2508. destroy(): Promise<void>;
  2509. sys: CompilerSystem;
  2510. }
  2511. export interface CompilerWatcher extends BuildOnEvents {
  2512. start: () => Promise<WatcherCloseResults>;
  2513. close: () => Promise<WatcherCloseResults>;
  2514. request: (data: CompilerRequest) => Promise<CompilerRequestResponse>;
  2515. }
  2516. export interface CompilerRequest {
  2517. path?: string;
  2518. }
  2519. export interface WatcherCloseResults {
  2520. exitCode: number;
  2521. }
  2522. export interface CompilerRequestResponse {
  2523. path: string;
  2524. nodeModuleId: string;
  2525. nodeModuleVersion: string;
  2526. nodeResolvedPath: string;
  2527. cachePath: string;
  2528. cacheHit: boolean;
  2529. content: string;
  2530. status: number;
  2531. }
  2532. /**
  2533. * Options for Stencil's string-to-string transpiler
  2534. */
  2535. export interface TranspileOptions {
  2536. /**
  2537. * A component can be defined as a custom element by using `customelement`, or the
  2538. * component class can be exported by using `module`. Default is `customelement`.
  2539. */
  2540. componentExport?: 'customelement' | 'module' | string | undefined;
  2541. /**
  2542. * Sets how and if component metadata should be assigned on the compiled
  2543. * component output. The `compilerstatic` value will set the metadata to
  2544. * a static `COMPILER_META` getter on the component class. This option
  2545. * is useful for unit testing preprocessors. Default is `null`.
  2546. */
  2547. componentMetadata?: 'runtimestatic' | 'compilerstatic' | string | undefined;
  2548. /**
  2549. * The actual internal import path for any `@stencil/core` imports.
  2550. * Default is `@stencil/core/internal/client`.
  2551. */
  2552. coreImportPath?: string;
  2553. /**
  2554. * The current working directory. Default is `/`.
  2555. */
  2556. currentDirectory?: string;
  2557. /**
  2558. * The filename of the code being compiled. Default is `module.tsx`.
  2559. */
  2560. file?: string;
  2561. /**
  2562. * Module format to use for the compiled code output, which can be either `esm` or `cjs`.
  2563. * Default is `esm`.
  2564. */
  2565. module?: 'cjs' | 'esm' | string;
  2566. /**
  2567. * Sets how and if any properties, methods and events are proxied on the
  2568. * component class. The `defineproperty` value sets the getters and setters
  2569. * using Object.defineProperty. Default is `defineproperty`.
  2570. */
  2571. proxy?: 'defineproperty' | string | undefined;
  2572. /**
  2573. * How component styles should be associated to the component. The `static`
  2574. * setting will assign the styles as a static getter on the component class.
  2575. */
  2576. style?: 'static' | string | undefined;
  2577. /**
  2578. * How style data should be added for imports. For example, the `queryparams` value
  2579. * adds the component's tagname and encapsulation info as querystring parameter
  2580. * to the style's import, such as `style.css?tag=my-tag&encapsulation=shadow`. This
  2581. * style data can be used by bundlers to further optimize each component's css.
  2582. * Set to `null` to not include the querystring parameters. Default is `queryparams`.
  2583. */
  2584. styleImportData?: 'queryparams' | string | undefined;
  2585. /**
  2586. * The JavaScript source target TypeScript should to transpile to. Values can be
  2587. * `latest`, `esnext`, `es2017`, `es2015`, or `es5`. Defaults to `latest`.
  2588. */
  2589. target?: CompileTarget;
  2590. /**
  2591. * Create a source map. Using `inline` will inline the source map into the
  2592. * code, otherwise the source map will be in the returned `map` property.
  2593. * Default is `true`.
  2594. */
  2595. sourceMap?: boolean | 'inline';
  2596. /**
  2597. * Base directory to resolve non-relative module names. Same as the `baseUrl`
  2598. * TypeScript compiler option: https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping
  2599. */
  2600. baseUrl?: string;
  2601. /**
  2602. * List of path mapping entries for module names to locations relative to the `baseUrl`.
  2603. * Same as the `paths` TypeScript compiler option:
  2604. * https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping
  2605. */
  2606. paths?: {
  2607. [key: string]: string[];
  2608. };
  2609. /**
  2610. * Passed in Stencil Compiler System, otherwise falls back to the internal in-memory only system.
  2611. */
  2612. sys?: CompilerSystem;
  2613. /**
  2614. * This option enables the same behavior as {@link Config.transformAliasedImportPaths}, transforming paths aliased in
  2615. * `tsconfig.json` to relative paths.
  2616. */
  2617. transformAliasedImportPaths?: boolean;
  2618. }
  2619. export type CompileTarget = 'latest' | 'esnext' | 'es2020' | 'es2019' | 'es2018' | 'es2017' | 'es2015' | 'es5' | string | undefined;
  2620. export interface TranspileResults {
  2621. code: string;
  2622. data?: any[];
  2623. diagnostics: Diagnostic[];
  2624. imports?: {
  2625. path: string;
  2626. }[];
  2627. inputFileExtension: string;
  2628. inputFilePath: string;
  2629. map: any;
  2630. outputFilePath: string;
  2631. }
  2632. export interface TransformOptions {
  2633. coreImportPath: string;
  2634. componentExport: 'lazy' | 'module' | 'customelement' | null;
  2635. componentMetadata: 'runtimestatic' | 'compilerstatic' | null;
  2636. currentDirectory: string;
  2637. file?: string;
  2638. isolatedModules?: boolean;
  2639. module?: 'cjs' | 'esm';
  2640. proxy: 'defineproperty' | null;
  2641. style: 'static' | null;
  2642. styleImportData: 'queryparams' | null;
  2643. target?: string;
  2644. }
  2645. export interface CompileScriptMinifyOptions {
  2646. target?: CompileTarget;
  2647. pretty?: boolean;
  2648. }
  2649. export interface DevServer extends BuildEmitEvents {
  2650. address: string;
  2651. basePath: string;
  2652. browserUrl: string;
  2653. protocol: string;
  2654. port: number;
  2655. root: string;
  2656. close(): Promise<void>;
  2657. }
  2658. export interface CliInitOptions {
  2659. args: string[];
  2660. logger: Logger;
  2661. sys: CompilerSystem;
  2662. }