In keeping with Semver, Stencil 2.0.0 was released due to changes in the API (mainly from some updates to the config API). But even though this is a new major version, there are few breaking changes, and any changes will be flagged and described by the compiler during development. For the most part, most of the changes are removal of deprecated APIs that have been printing out warning logs for quite some time now.

Opt-in for IE11, Edge 16-18 and Safari 10 Builds

• config: update config extra defaults to not build IE11, Edge 16-18 and Safari 10 by default (363bf59)

A change in Stencil 2 is that the IE11, Edge 16-18 and Safari 10 builds will not be enabled by default. However, the ability to opt-in is still available, and can be enabled by setting each extras config flag to true. And advantages of this is less runtime within your builds. See the config.extras docs for more info.

Opt-in for ES5 and SystemJS Builds

• config: do not build es5 by default (fa67d97)

Just like having to opt-in for IE11, the same goes for opting-in for ES5 and SystemJS builds. For a production build in Stencil 1, it would build both ES2017/ESM files, and ES5/SystemJS files. As of Stencil 2, both dev and prod builds do not create ES5/SystemJS builds. An advantage of this is having faster production builds by not having to also downlevel to es5. See the buildEs5 for more info.

Use disconnectedCallback() instead of componentDidUnload()

• componentDidUnload: use disconnectedCallback instead of componentDidUnload (4e45862)

When Stencil is used within other frameworks, DOM elements may be reused, making it impossible for componentDidUnload() to be accurate 100% of the time if it is disconnected, then re-connected, and disconnected again. Instead, disconnectedCallback() is the preferred way to always know if a component was disconnected from the DOM.

Note that the runtime still works for any collections that have been built with componentDidUnload(). However, updates to Stencil 2 will require it's changed to disconnectedCallback().

Default to async task queue

• taskQueue: set "async" taskQueue as default (f3bb121)

Update taskQueue default to "async". Stencil 1 default was "congestionAsync". See config.taskQueue for more info.

Restore Stencil 1 defaults

export const config: Config = {
  buildEs5: 'prod',
  extras: {
    cssVarsShim: true,
    dynamicImportShim: true,
    safari10: true,
    shadowDomShim: true,
  }
};

dist package.json

To ensure the extensions are built for the future and work with today's bundlers, we've found it best to use .cjs.js extension for CommonJS files, and .js for ESM files, with the idea that cjs files will no longer be needed some day, and the ESM files are the standard. (We were using .mjs files, but not all of today's tooling and bundlers work well with that extension).

If you're using the dist output target, update the package.json in the root of your project, like this:

  {
-    "main": "dist/index.js",
+    "main": "dist/index.cjs.js",

-    "module": "dist/index.mjs",
+    "module": "dist/index.js",

-    "es2015": "dist/esm/index.mjs",
+    "es2015": "dist/esm/index.js",

-    "es2017": "dist/esm/index.mjs",
+    "es2017": "dist/esm/index.js",

-    "jsnext:main": "dist/esm/index.mjs",
+    "jsnext:main": "dist/esm/index.js",
  }

Additionally the dist/loader output directory has renamed its extensions too, but since its dist/loader/package.json file is auto-generated, the entries were renamed too. So unless you were referencing the loader files directly you will not have to do external updates.

See the Output Folder Structure Defaults for more info.

NodeJS Update

• node: minimum of Node 12.10.0, recommend 14.5.0 or greater (55331be)

With the major release, now's a good time to update the minimum and recommended version of NodeJS.

• Node Releases
• node.green

TypeScript 4

• typescript: bundle typescript (1973032)
• typescript: update to typescript 4.0.0-beta (a274e11)
• typescript: update to typescript 4.0.1-rc (def2e6b)
• typescript: update to typescript 4.0.2 (f55f0bf)

The other change is the update to TypeScript 4. With Stencil 2, TypeScript will no longer be a dependency, but instead included within the Stencil compiler. There are a few advantages to this we'll be experimenting with:

• Faster compiler startup times and overall smaller install size.
• The custom elements build should have a dependency of @stencil/core, so not having TypeScript as a dependency of @stencil/core simplifies the dependency graph for end-users and libraries.
• Drastically simplifies the Stencil compiler by not having to dynamically import TypeScript, which quickly gets complicated since the compiler can work within Node, Deno, web workers and the browser's main thread. By bundling internally many of the complexities are no longer an issue.
• Stencil compiler guaranteed to run with the exact version of TypeScript it was designed with.
• Easier to adjust to breaking changes. For example, TypeScript 4 introduced a few breaking changes, but with this update it made it easier for the compiler to adjust internally.

Removal of Deprecated APIs

• assetsDir: remove deprecated component assetsDir (b5cba6a)
• attr: remove deprecated prop attr/reflectToAttr (133dd49)
• collection: remove deprecated collection parsing (1a94d1e)
• compiler: remove deprecated compile/compileSync (58a27d2)
• config: remove deprecated includeSrc/excludeSrc (c18cb1f)
• context: remove deprecated prop context/connect (a87b738)
• copy: remove deprecated copy config (6cf3134)
• docs: remove deprecated 'docs' type (043e2d8)
• experimental-dist-module: remove deprecated experimental-dist-module (41189a6)
• forceUpdate: remove deprecated elm.forceUpdate() (dfc1e59)
• legacyLoader: remove deprecated legacy loader (7480f92)
• listen: remove Listen target: 'parent' option (ed63707)
• listen: remove deprecated listen target (1a3b519)
• reflectToAttr: remove deprecated prop reflectToAttr (6eae6f8)
• prerender: use internal typescript (8f0bb51)
• test: do not require typescript for tests (43c5d98)
• test: remove deprecated testing configs (fb8a02b)
• transpile: remove deprecated "script" option (75dfebb)
• watch: remove deprecated PropWillChange/PropDidChange (fa2b400)

Removal of Context

The Context object was originally added in the 0.x.x versions of Stencil, before ES Modules were widely adopted. Since then we've deprecated it in Stencil 1, and have ported any external libraries off of it. The remaining one was @stencil/redux, and we've released 0.2.0 to be used with Stencil 2 (and can also work with Stencil 1). Additionally, now might be a good time to look into using @stencil/store instead.

Bug Fixes

• assetsDirs: allow same destination asset dir copy task (b6379b3), closes #2615
• compiler: normalizePath result from fs.realpathSync (#2625) (df83c83)
• dist: ensure src dts files not emitted still get shipped in dist (dea56be), closes #1797
• dist: export Components, JSX types from custom-elements build (abae5d1)
• Fragment: fix tsconfig Fragment (ba0ea8d)
• exit: ensure all node processes are destroyed on exit (73a04c2)
• exit: sys.exit() returns a promise (208ef8c)
• export: export client runtime from @stencil/core (4c6cb60)
• hmr: fix dev server hmr (fa480b6)
• hydrate: ensure all timers are cleared (db1d747)
• monorepos: do not lazy require missing dependencies (7f739a0)
• parse: parse decorator shorthand property assignment (6b9e035)
• plugin: ensure external plugin css do not require physical file (b5a2536), closes #2622
• prerender: flatten hAsync children to resolve promises (363d258)
• prerender: hAsync only returns promise if it has to (25a547a)
• safari: fix safari10 builds (63f02f8)
• sys: set ts.getExecutingFilePath() from stencil sys (2b21f2d)
• taskQueue: fix "immediate" rendering (#2630) (62ea511)
• testing: add collectCoverageFrom jest parameter (#2613) (370a701)
• treeshaking: move environment helpers out of utils (c9306b9)
• ts: update ts lib default local module path (16f30bc)
• watch: fix rebuild components on e2e w/ watch (7cd28ca), closes #2642
• watch: hmr scss _partial reload on file change (4ffbe4a), closes #2205
• worker: error passing (03864f2)

Features

• buildEs5: add "prod" as an option for config.buildEs5 (1af30a2)
• dev-server: single-threaded dev-server for debugging (cf335e3)
• runtime: add jsx Fragment (#2647) (f3abee7)
• jest: update to jest 26.4.0 (9e3a6a8)
• prerendering: async h() function (d6eabb9)
• rollup: update to rollup 2.26.6 (6424254)
• terser: update to terser 5.1.0 and use its esm build (4b67c5a)
• terser: update to terser 5.2.1 (7582974)