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.
While migrating from Stencil One, 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
- 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. An advantage of this is less runtime within your builds. See the config.extras docs for more info.
- 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.
- 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().
- taskQueue: set "async" taskQueue as default (f3bb121)
Update taskQueue default to "async". Stencil 1 default was "congestionAsync". See config.taskQueue for more info.
export const config: Config = {
buildEs5: 'prod',
extras: {
cssVarsShim: true,
dynamicImportShim: true,
safari10: true,
shadowDomShim: true,
},
};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.
- 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.
Most of the updates for the 1.0.0 release involve removing custom APIs, and continuing to leverage web-standards in order to generate future-proof components that scale.
Additionally, these updates allow Stencil to further improve its tooling, with a focus on great developer experience for teams maintaining codebases across large organizations.
A common issue with JSX is each separate project's use of global JSX types. Many of the required changes are in order to avoid global types, which often cause issues for apps which import from numerous packages. The other change is having each component import its renderer, such as JSX's h() function.
In order to render JSX in Stencil apps, the h() function must be imported from @stencil/core:
+ import { h } from '@stencil/core';
function app() {
return <ion-app></ion-app>
}The h stands for "hyperscript", which is what JSX elements are transformed into (it's the actual function executed when rendering within the runtime). Stencil's h import is an equivalent to React's React.createElement. This also explains why the app's tsconfig.json sets the { "jsxFactory": "h" } config, which is detailed further in TypeScript's JSX Factory Function Docs.
You might think that h will be marked as "unused" by linters, but it's not! Any JSX syntax you write, is equivalent to using h directly, and the typescript's tooling is aware of that.
const jsx = <ion-button>;is the same as:
const jsx = h('ion-button', null, null);Stencil used to generate a loader .js file that automatically decided which entry-point to load based in the browser's capabilities. In Stencil 1.0 we have decided to completely remove the overhead of this loader by directly loading the core using the web-standard type="module" script attribute. Less runtime and preferring native browser features. Win Win. For more for info, please see Using JavaScript modules on the web.
- <script src="/build/app.js"></script>
+ <script type="module" src="/build/app.esm.js"></script>
+ <script nomodule src="/build/app.js"></script>Stencil One has changed the internal folder structure of the dist folder, and some entry-points are located in different location:
- "module":
dist/esm/index.js=>dist/index.mjs - "jsnext:main":
dist/esm/es2017/index.js=>dist/esm/index.mjs
Make sure you update the package.json in the root of your project, like this:
{
"main": "dist/index.js",
- "module": "dist/esm/index.js",
+ "module": "dist/index.mjs",
- "es2015": "dist/esm/es2017/index.js",
- "es2017": "dist/esm/es2017/index.js",
- "jsnext:main": "dist/esm/es2017/index.js",
+ "es2015": "dist/esm/index.mjs",
+ "es2017": "dist/esm/index.mjs",
+ "jsnext:main": "dist/esm/index.mjs",
}Some packages, specially the ones from the Stencil and Ionic core teams used some private APIs of Stencil, that's why if your collection depends of @ionic/core, @stencil/router or @stencil/state-tunnel, you might need to update your package.json to point these dependencies to the "one" tag.
"@ionic/core": "one",
"@stencil/router": "^1.0.0",
"@stencil/state-tunnel": "^1.0.0",
"@stencil/sass": "^1.0.0",
"@stencil/less": "^1.0.0",
"@stencil/stylus": "^1.0.0",
"@stencil/postcss": "^1.0.0",
Stencil will not read/write to the browser's global window anymore. So things like window.App or window.Ionic are gone, and should be provided by the user's code if need be.
@Prop() mode used to be the way to define and read the current mode of a component. This API was removed since it was very local to the use case of Ionic.
Instead, the mode can be read by using the getMode() method from @stencil/core.
For all the same reasons for now importing h, in order to prevent type collision in the future, we have moved to local scoped JSX namespaces. Unfortunately, this means JSX is no longer global and it needs to be imported from @stencil/core. Also, note that while the below example has the render function with a return type of JSX.Element, we recommend to not have a return type at all:
import { JSX, h } from '@stencil/core';
render(): JSX.Element {
return <ion-button></ion-button>
}HTMLAttributesmight not be available as a globalJSX
HTMLAttributes used to be exposed as a global interface, just like the JSX namespace, but that caused type conflicts when mixing different versions of stencil in the same project.
Now HTMLAttributes is part of JSXBase, exposed in @stencil/core:
import { JSXBase } from '@stencil/core';
JSXBase.HTMLAttributesThe global type for HTMLStencilElement has been removed. Instead, it's better is to use the exact type of your component, such as HTMLIonButtonElement. The HTML types are automatically generated within the components.d.ts file.
The global type StencilIntrinsicElement has been removed. It can be replaced by importing the JSX namespace from @stencil/core:
import { JSX } from '@stencil/core';
export type StencilIntrinsicElement = JSX.IntrinsicElement;It's no longer possible to use the event.KEY syntax in the @Listen decorator in order to only listen for specific key strokes.
Instead, the browser already implements easy-to-use APIs:
BEFORE:
@Listen('keydown.enter')
onEnter() {
console.log('enter pressed');
}AFTER:
@Listen('keydown')
onEnter(ev: KeyboardEvent) {
if (ev.key === 'Enter') {
console.log('enter pressed');
}
}It's not possible to programmatically enable/disable an event listener defined using the @Listen() decorator. Please use the DOM API directly (addEventListener / removeEventListener).
The event name should be provided excl
This feature was deprecated a long time ago, and it is being removed definitely from Stencil.
The mockDocument() and mockWindow() functions previously in @stencil/core/mock-dom has been moved to:
@stencil/core/testing:
- import { mockDocument, mockWindow } from '@stencil/core/mock-dom';
+ import { mockDocument, mockWindow } from '@stencil/core/testing';The output target "docs" has been renamed to "docs-readme":
In your stencil.config.ts file:
export const config = {
outputTargets: [
{
- type: 'docs',
+ type: 'docs-readme',
}
]
};hostData() usage has been replaced by the new Host exposed in @stencil/core. The <Host> JSX element represents the "host" element of the component, and simplifies being able to add attributes and CSS classes to the host element:
+ import { Host } from '@stencil/core';
- hostData() {
- return {
- 'class': {
- 'my-class': true,
- 'disabled': this.isDisabled
- },
- attr: this.attrValue
- };
- }
render() {
return (
+ <Host
+ class={{
+ 'my-class': true,
+ 'disabled': this.isDisabled
+ }}
+ attr={this.attrValue}
+ />
);
}Until Stencil 1.0, public component methods decorated with @Method() could only return Promise<...> or void.
Now, only the async methods are supported, meaning that retuning void is not valid.
@Method()
- doSomething() {
+ async doSomething() {
console.log('hello');
}This change was motivated by the fact that Stencil's 1.0 runtime will be able to proxy all component method calls! That means, developers will be able to call component methods safely without using componentOnReady()! even if the actual component has not been downloaded yet.
@Component(...)
export class Cmp {
@Method()
async doSomething() {
console.log('called');
}
}BEFORE:
// Calling `componentOnReady()` was required in order to make sure the "component"
// was properly lazy loaded and the methods are available.
await element.componentOnReady()
element.doSomething();AFTER:
// Stencil One will automatically proxy the method call (like an RPC),
// and it's safe to call any method without using `componentOnReady()`.
await element.doSomething();The first argument of the @Listen() decorator is now only the event name, such as click or resize. Previously you could set the target of the listener by prefixing the event name with something like window:resize. Instead, the target is now set using the options.
- @Listen('window:event')
+ @Listen('event’, { target: 'window' })
- @Listen('document:event')
+ @Listen('event’, { target: 'document' })
- @Listen('body:event’)
+ @Listen('event’, { target: 'body’ })
- @Listen('parent:event’)
+ @Listen('event’, { target: 'parent’ })This change was motivated by the fact that body:event is a valid DOM event name.
In addition, the new syntax allows for strong typing, since the {target} only accepts the following string values ('window', 'document', 'body', 'parent').
Using the @Prop decorator with the context has been deprecated and their usage is highly unrecommended. Here's how update each case:
Accessing window using Prop({context: 'window'}) was previously required because of Server-side-rendering requirements, fortunately this is no longer needed, and developers can use global window directly.
Prop({context: 'window'})becomeswindow
- @Prop({context: 'window'}) win!: Window;
method() {
// print window
- console.log(this.win);
+ console.log(window);
}Accessing document using Prop({context: 'document'}) was previously required because of Server-side-rendering requirements, fortunately this is no longer needed, and developers can use global document directly.
Prop({context: 'document'})becomesdocument
- @Prop({context: 'document'}) doc!: Document;
method() {
// print document
- console.log(this.doc);
+ console.log(document);
}In order to determine if the your component is being rendered in the browser or the server as part of some prerendering/ssr process, stencil exposes a compiler-time constant through the Build object, exposed in @stencil/core:
Prop({context: 'isServer'})becomes!Build.isBrowser
+ import { Build } from '@stencil/core';
[...]
- @Prop({context: 'isServer'}) isServer!: boolean;
method() {
- if (!this.isServer) {
+ if (Build.isBrowser) {
console.log('only log in the browser');
}
}It will not be recommended to use @Prop(connect) in order to lazily load components. Instead it's recommended to use ES Modules and/or dynamic imports to load code lazily.
@Component({
- assetsDir: 'resource',
+ assetsDirs: ['resource']
})The root copy property in stencil.config.ts has been deprecated in favor of local copy tasks per output-target, ie. now the copy tasks are specific under the context of each output-target.
const copy =
export const config = {
outputTargets: [
{
type: 'www',
+ copy: [
+ {
+ src: 'index-module.html',
+ dest: 'index-module.html'
+ }
+ ]
}
],
- copy: [
- {
- src: 'index-module.html',
- dest: 'index-module.html'
- }
- ]
};This change has been motivated by the confusing semantics of the root copy task, currently the copy tasks are executed multiple times within different working-directories for each output-target.
Take this example:
export const config = {
outputTargets: [
{ type: 'dist' },
{ type: 'dist', dir: 'dist-app' },
{ type: 'www' }
],
copy: [
{ src: 'main.html' }
]
};In the example above, the main.html file is actually copied into 5 different places!!
- dist/collection/main.html
- dist/app/main.html
- dist-app/collection/main.html
- dist-app/app/main.html
- www/main.html
If the old behavior is still desired, the config can be refactored to:
const copy = [
{ src: 'main.html' }
];
export const config = {
outputTargets: [
{ type: 'dist', copy },
{ type: 'dist', dir: 'dist-app', copy },
{ type: 'www', copy }
]
};A new testing utility has been created to make it easier to unit test components. Its API is similar to newE2EPage() for consistency, but internally newSpecPage() does not use Puppeteer, but rather runs on top of a pure Node environment. Additionally, user code should not have to be written with legacy CommonJS, and code can safely use global browser variables such as window and document. In the example below, a mock CmpA component was created in the test, but it could have also imported numerous existing components and registered them into the test using the components config. The returned page variable also has a root property, which is convenience property to get the top-level component found in the test.
import { Component, Prop } from '@stencil/core';
import { newSpecPage } from '@stencil/core/testing';
it('override default values from attribute', async () => {
@Component({
tag: 'cmp-a'
})
class CmpA {
@Prop() someProp = '';
render() {
return `${this.someProp}`;
}
}
const page = await newSpecPage({
components: [CmpA],
html: `<cmp-a some-prop="value"></cmp-a>`,
});
// "root" is a convenience property which is the
// the top level component found in the test
expect(page.root).toEqualHtml(`
<cmp-a some-prop="value">
value
</cmp-a>
`);
expect(page.root.someProp).toBe('value');
});Traditionally, when a component is serialized to a string its shadow-root is ignored and not include within the HTML output. However, when building web components and using Shadow DOM, the nodes generated within the components are just as important as any other nodes to be tested. For this reason, both spec and e2e tests will serialize the shadow-root content into a mocked <mock:shadow-root> element. Note that this serialized shadow-root is simply for testing and comparing values, and is not used at browser runtime.
import { Component } from '@stencil/core';
import { newSpecPage } from '@stencil/core/testing';
it('test shadow root innerHTML', async () => {
@Component({
tag: 'cmp-a',
shadow: true
})
class CmpA {
render() {
return (
<div>Shadow Content</div>
);
}
}
const page = await newSpecPage({
components: [CmpA],
html: `
<cmp-a>
Light Content
</cmp-a>
`,
});
expect(page.root).toEqualHtml(`
<cmp-a>
<mock:shadow-root>
<div>
Shadow Content
</div>
</mock:shadow-root>
Light Content
</cmp-a>
`);
});When running Jest directly, previously most of Jest had to be manually configured within each app's package.json, and required the transform config to be manually wired up to Stencil's jest.preprocessor.js. With the latest changes, most of the Jest config can be replaced with just "preset": "@stencil/core/testing". You can still override the preset defaults, but it's best to start with the defaults first. Also note, the Jest config can be avoided entirely by using the stencil test --spec command rather than calling Jest directly.
"jest": {
+ "preset": "@stencil/core/testing"
- "transform": {
- "^.+\\.(ts|tsx)$": "<rootDir>/node_modules/@stencil/core/testing/jest.preprocessor.js"
- },
- "testRegex": "(/__tests__/.*|\\.(test|spec))\\.(tsx?|jsx?)$",
- "moduleFileExtensions": [
- "ts",
- "tsx",
- "js",
- "json",
- "jsx"
- ]
}Stencil v3.0.0 is in development at this time and has not been released. The list below is not final and is subject to change. Further details on each of these items will be included prior to the release.