Skip to content

Commit 04bdeaa

Browse files
rwaskiewiczrwaskiewicz
committed
docs(v3): add initial migration guide to stencil v3
this commit adds the initial migration steps for stencil v3. it is not finalized at this time (i.e. we are not "feature complete"). rather this is a backfill of existing work that has been commited to the existing `v3.0.0-dev` branch in the stencil core repository.
1 parent 88dda69 commit 04bdeaa

File tree

3 files changed

+199
-0
lines changed

3 files changed

+199
-0
lines changed

‎src/assets/docs-structure.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@
77
"filePath": "/assets/docs/introduction/overview.json",
88
"url": "/docs/introduction"
99
},
10+
{
11+
"text": "Upgrading to Stencil v3",
12+
"filePath": "/assets/docs/introduction/upgrading-to-stencil-three.json",
13+
"url": "/docs/upgrading-to-stencil-3"
14+
},
1015
{
1116
"text": "Goals and Objectives",
1217
"filePath": "/assets/docs/introduction/goals-and-objectives.json",

‎src/docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
* Introduction
44
* [Overview](introduction/overview.md)
5+
* [Upgrading to Stencil v3](introduction/upgrading-to-stencil-three.md)
56
* [Goals and Objectives](introduction/goals-and-objectives.md)
67
* [Getting Started](introduction/getting-started.md)
78
* [My First Component](introduction/my-first-component.md)

‎src/docs/introduction/upgrading-to-stencil-three.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: Upgrading to Stencil v3.0.0
3+
description: Upgrading to Stencil v3.0.0
4+
url: /docs/upgrading-to-stencil-3
5+
contributors:
6+
- rwaskiewicz
7+
---
8+
9+
# Upgrading to Stencil v3.0.0
10+
11+
## Getting Started
12+
13+
It's recommended that your projects start their upgrade from Stencil v2.
14+
Projects using Stencil v0 or Stencil v1 should upgrade to Stencil v2 before proceeding with this guide.
15+
For breaking changes introduced in previous major versions of the library, see:
16+
- [Stencil v2 Breaking Changes](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-two)
17+
- [Stencil v1 Breaking Changes](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-one)
18+
19+
For projects that are on Stencil v2, install the latest version of Stencil v3:
20+
```bash
21+
npm install @stencil/core@3
22+
```
23+
24+
## Updating Your Code
25+
26+
### New Configuration Defaults
27+
Starting with Stencil v3.0.0, the default configuration values have changed for a few properties.
28+
29+
#### SourceMaps
30+
Sourcemaps are generated by default for all builds.
31+
Previously, sourcemaps had to be explicitly enabled by setting the `sourceMap` flag to `true`.
32+
To restore the old behavior, set the `sourceMap` flag to `false` in your project's `stencil.config.ts`:
33+
```ts
34+
// stencil.config.ts
35+
import { Config } from '@stencil/core';
36+
37+
export const config: Config = {
38+
sourceMap: false,
39+
// ...
40+
};
41+
```
42+
43+
#### `dist-custom-elements` Type Declarations
44+
Type declaration files (`.d.ts` files) are now generated by default for the [`dist-custom-elements` output target](/docs/custom-elements).
45+
If your project is using `dist-custom-elements` and you wish to not generate type declarations, the old behavior can be achieved by setting `generateTypeDeclarations` to `false` in your project's `stencil.config.ts`:
46+
```ts
47+
// stencil.config.ts
48+
import { Config } from '@stencil/core';
49+
50+
export const config: Config = {
51+
outputTargets: [
52+
{
53+
type: 'dist-custom-elements',
54+
generateTypeDeclarations: false,
55+
// ...
56+
},
57+
// ...
58+
],
59+
// ...
60+
};
61+
```
62+
63+
### Deprecated `assetsDir` Removed from `@Component()` decorator
64+
The `assetsDir` field was [deprecated in Stencil v2.0.0](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#componentassetsdir), but some backwards compatibility was retained with a warning message.
65+
It has been fully removed in Stencil v3.0.0 in favor of `assetsDirs`.
66+
To migrate from existing usages of `assetsDir`, update the property name and wrap its value in an array:
67+
```diff
68+
@Component({
69+
tag: 'my-component',
70+
- assetsDir: 'assets',
71+
+ assetsDirs: ['assets'],
72+
})
73+
```
74+
For more information on the `assetsDirs` field, please see the [Stencil Documentation on `assetsDirs`](/docs/assets#assetsdirs)
75+
76+
### Drop Node 12 Support
77+
Stencil no longer supports Node 12.
78+
Please upgrade local development machines, continuous integration pipelines, etc. to use Node v14 or higher.
79+
80+
### Strongly Typed Inputs
81+
`onInput` and `onInputCapture` events have had their interface's updated to accept an argument of `InputEvent` over `Event`:
82+
```diff
83+
- onInput?: (event: Event) => void;
84+
+ onInput?: (event: InputEvent) => void;
85+
- onInputCapture?: (event: Event) => void;
86+
+ onInputCapture?: (event: InputEvent) => void;
87+
```
88+
`event` arguments to either callback should be updated to take this narrower typing into account
89+
90+
## Output Targets
91+
92+
### `dist-custom-elements` Output Target
93+
#### Add `customElementsExportBehavior` to Control Export Behavior
94+
`customElementsExportBehavior` is a new configuration option for the output target.
95+
It allows users to configure the export behavior of components that are compiled using the output target.
96+
By default, this output target will behave exactly as it did in Stencil v2.0.0.
97+
For more information on how to configure it, please see the [documentation for the field](/docs/custom-elements#customelementsexportbehavior).
98+
99+
#### Move `autoDefineCustomElements` Configuration
100+
`autoDefineCustomElements` was a configuration option to define a component and its children automatically with the CustomElementRegistry when the component's module is imported.
101+
This behavior has been merged into the [`customElementsExportBehavior` configuration field](#add-customelementsexportbehavior-to-control-export-behavior).
102+
To continue to use this behavior, replace `autoDefineCustomElements` in your project's `stencil.config.ts` with the following:
103+
```diff
104+
// stencil.config.ts
105+
import { Config } from '@stencil/core';
106+
107+
export const config: Config = {
108+
outputTargets: [
109+
{
110+
type: 'dist-custom-elements',
111+
- autoDefineCustomElements: true,
112+
+ customElementsExportBehavior: 'auto-define-custom-elements',
113+
// ...
114+
},
115+
// ...
116+
],
117+
// ...
118+
};
119+
```
120+
121+
### `dist-custom-elements-bundle` Output Target
122+
The `dist-custom-elements-bundle` has been removed starting with Stencil v3.0.0, following the [RFC process](https://github.com/ionic-team/stencil/issues/3136).
123+
Users of this output target should migrate to the `dist-custom-elements` output target.
124+
125+
By default, `dist-custom-elements` does not automatically define all a project's component's with the CustomElementsRegistry.
126+
This allows for better treeshaking and smaller bundle sizes.
127+
128+
For teams that need to migrate quickly to `dist-custom-elements`, the following configuration should be close to a drop-in replacement for `dist-custom-elements-bundle`:
129+
```diff
130+
// stencil.config.ts
131+
import { Config } from '@stencil/core';
132+
133+
export const config: Config = {
134+
outputTargets: [
135+
- {
136+
- type: 'dist-custom-elements-bundle',
137+
- // additional configuration
138+
- },
139+
+ {
140+
+ type: 'dist-custom-elements',
141+
+ customElementsExportBehavior: 'bundle'
142+
+ },
143+
// ...
144+
],
145+
// ...
146+
};
147+
```
148+
However, it does not necessarily improve treeshaking/bundle size.
149+
For more information on configuring this output target, please see the [`dist-custom-elements` documentation](/docs/custom-elements)
150+
151+
## Legacy Angular Output Target
152+
Prior to the creation of the [`@stencil/angular-output-target`](https://github.com/ionic-team/stencil-ds-output-targets/blob/main/packages/angular-output-target/README.md), the `'angular'` output target was the original means of connecting a Stencil component to an Angular application.
153+
This output target has been removed in favor of `@stencil/angular-output-target`.
154+
Please migrate to `@stencil/angular-output-target` and remove the `'angular'` output target from your `stencil.config.ts` file.
155+
Instructions for doing so can be found [in the Angular Framework Integration section](/docs/angular#setup) of this site.
156+
157+
## Stencil APIs
158+
Stencil exposes Node APIs for programmatically invoking the compiler.
159+
Most users do not use these APIs directly.
160+
Unless your project calls these APIs, no action is required for this section.
161+
162+
### Flag Parsing, `parseFlags()`
163+
Stencil exposes an API for parsing flags that it receives from the command line.
164+
Previously, it accepted an optional `CompilerSystem` argument that was never properly used.
165+
The flag has been removed as of Stencil v3.0.0.
166+
To migrate, remove the argument from any calls to `parseFlags` imported from the Stencil CLI package.
167+
```diff
168+
import { parseFlags } from '@stencil/core/cli';
169+
- parseFlags(flags, compilerSystem);
170+
+ parseFlags(flags);
171+
```
172+
173+
### Destroy Callback, `addDestroy()`, `removeDestroy()`
174+
The Stencil `CompilerSystem` interface has a pair of methods, `addDestroy` and `removeDestroy` that were previously misspelled.
175+
If your codebase explicitly calls these methods, they need to be updated.
176+
Replace all instances of `addDestory` with `addDestroy` and all instances of `removeDestory` with `removeDestroy`
177+
The functionality of these methods remains the same.
178+
179+
## End-to-End Testing
180+
### Puppeteer v10 Required
181+
Versions of Puppeteer prior to Puppeteer version 10 are no longer supported.
182+
In newer versions of Puppeteer, the library provides its own types, making `@types/puppeteer` no longer necessary.
183+
Ensure that Puppeteer v10 is installed, and that its typings are not:
184+
```bash
185+
$ npm install puppeteer@10
186+
$ npm uninstall @types/puppeteer
187+
```
188+
189+
## Need Help Upgrading?
190+
191+
Be sure to look at the Stencil [v3.0.0 Breaking Changes Guide](https://github.com/ionic-team/stencil/blob/main/BREAKING_CHANGES.md#stencil-v300).
192+
193+
If you need help upgrading, please post a thread on the [Stencil Forum](https://forum.ionicframework.com/).

0 commit comments

Comments
 (0)
⚡