diff --git a/.github/workflows/check-markdown.yml b/.github/workflows/check-markdown.yml
index b7d2e954a..c7754b461 100644
--- a/.github/workflows/check-markdown.yml
+++ b/.github/workflows/check-markdown.yml
@@ -9,10 +9,10 @@ jobs:
markdown-link-check:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4.1.3
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Use Node from Volta
- uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+ uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
with:
node-version-file: 'package.json'
cache: 'npm'
@@ -26,10 +26,10 @@ jobs:
markdown-spelling-check:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4.1.3
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: Use Node from Volta
- uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+ uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
with:
node-version-file: 'package.json'
cache: 'npm'
diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml
index b99937c3f..554ee637f 100644
--- a/.github/workflows/format.yml
+++ b/.github/workflows/format.yml
@@ -11,13 +11,13 @@ jobs:
runs-on: 'ubuntu-latest'
steps:
- name: Checkout Code
- uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4.1.3
+ uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
# this overrides previous versions of the node runtime that was set.
# jobs that need a different version of the Node runtime should explicitly
# set their node version after running this step
- name: Use Node Version from Volta
- uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+ uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
with:
node-version-file: './package.json'
cache: 'npm'
diff --git a/cspell-wordlist.txt b/cspell-wordlist.txt
index 785969053..090262807 100644
--- a/cspell-wordlist.txt
+++ b/cspell-wordlist.txt
@@ -30,6 +30,7 @@ prerenders
proxied
pseudocode
runtimes
+shadowrootmode
sourcemaps
templating
transpiles
diff --git a/docs/components/api.md b/docs/components/api.md
index 174f446d2..6051e207b 100644
--- a/docs/components/api.md
+++ b/docs/components/api.md
@@ -152,6 +152,15 @@ The following primitives can be imported from the `@stencil/core` package and us
}
```
+- **setAssetPath()**: Sets the path for Stencil to resolve local assets. Refer to the [Assets](../guides/assets.md#setassetpath) page for usage info.
+
+ __Type:__ `(path: string) => string`
+ __Example:__
+ ```ts
+ import { setAssetPath } from '@stencil/core';
+ setAssetPath(`{window.location.origin}/`);
+ ```
+
- **setMode()**: Sets the style mode of a component. Refer to the [Styling](./styling.md#style-modes) page for usage info.
__Type:__ `(ref: HTMLElement) => string`
diff --git a/docs/components/component-lifecycle.md b/docs/components/component-lifecycle.md
index 377dd6530..72609e476 100644
--- a/docs/components/component-lifecycle.md
+++ b/docs/components/component-lifecycle.md
@@ -131,7 +131,7 @@ Even if some components may or may not be already loaded, the entire component h
## Async Lifecycle Methods
-Lifecycle methods can also return promises which allows the method to asynchronously retrieve data or perform any async tasks. A great example of this is fetching data to be rendered in a component. For example, this very site you're reading first fetches content data before rendering. But because `fetch()` is async, it's important that `componentWillLoad()` returns a `Promise` to ensure its parent component isn't considered "loaded" until all of its content has rendered.
+Some lifecycle methods, e.g. `componentWillRender`, `componentWillLoad` and `componentWillUpdate`, can also return promises which allows the method to asynchronously retrieve data or perform any async tasks. A great example of this is fetching data to be rendered in a component. For example, this very site you're reading first fetches content data before rendering. But because `fetch()` is async, it's important that `componentWillLoad()` returns a `Promise` to ensure its parent component isn't considered "loaded" until all of its content has rendered.
Below is a quick example showing how `componentWillLoad()` is able to have its parent component wait on it to finish loading its data.
@@ -145,7 +145,6 @@ componentWillLoad() {
}
```
-
## Example
This simple example shows a clock and updates the current time every second. The timer is started when the component is added to the DOM. Once it's removed from the DOM, the timer is stopped.
diff --git a/docs/config/01-overview.md b/docs/config/01-overview.md
index 8d35ca59b..46e7caa33 100644
--- a/docs/config/01-overview.md
+++ b/docs/config/01-overview.md
@@ -108,6 +108,47 @@ enableCache: true
Please see the [Extras docs](./extras.md).
+## env
+
+*default: `{}`*
+
+An object that can hold environment variables for your components to import and use. These variables can hold data objects depending on the environment you compile the components for. For example, let's say we want to provide an URL to our API based on a specific environment, we could provide it as such:
+
+```ts title="stencil.config.ts"
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+ ...,
+ env: {
+ API_BASE_URL: process.env.API_BASE_URL
+ }
+}
+```
+
+Now when you build your components with this environment variable set, you can import it in your component as follows:
+
+```ts
+import { Component, h, Env, Host } from '@stencil/core';
+
+@Component({
+ tag: 'api-component',
+})
+export class APIComponent {
+ async connectedCallback () {
+ const res = await fetch(Env.API_BASE_URL)
+ // ...
+ }
+}
+```
+
+## generateExportMaps
+
+*default: `false`*
+
+Stencil will generate [export maps](https://nodejs.org/api/packages.html#packages_exports) that correspond with various output target outputs. This includes the root
+entry point based on the [primary output target](../output-targets/01-overview.md#primary-package-output-target-validation) (or first eligible output target if not specified),
+the entry point for the lazy-loader (if using the `dist` output target), and entry points for each component (if using `dist-custom-elements`).
+
## globalScript
The global script config option takes a file path as a string.
@@ -470,3 +511,37 @@ export declare function util(arg: UtilInterface): void;
When `true`, validation for common `package.json` fields will occur based on setting an output target's `isPrimaryPackageOutputTarget` flag.
For more information on package validation, please see the [output target docs](../output-targets/01-overview.md#primary-package-output-target-validation).
+
+## rollupConfig
+
+Passes custom configuration down to rollup itself. The following options can be overwritten:
+
+- `inputOptions`: [`context`](https://rollupjs.org/configuration-options/#context), [`external`](https://rollupjs.org/configuration-options/#external), [`moduleContext`](https://rollupjs.org/configuration-options/#modulecontext) [`treeshake`](https://rollupjs.org/configuration-options/#treeshake)
+- `outputOptions`: [`globals`](https://rollupjs.org/configuration-options/#output-globals)
+
+*default: `{}`*
+
+## watchIgnoredRegex
+
+*default: `[]`*
+
+*type: `RegExp | RegExp[]`*
+
+A regular expression (or array of regular expressions) that can be used to omit files from triggering a rebuild in watch mode. During compile-time, each file in the Stencil
+project will be tested against each regular expression to determine if changes to the file (or directory) should trigger a project rebuild.
+
+:::note
+If you want to ignore TS files such as `.ts`/`.js` or `.tsx`/`.jsx` extensions, these files will also need to be specified in your project's tsconfig's
+[`watchOptions`](https://www.typescriptlang.org/docs/handbook/configuring-watch.html#configuring-file-watching-using-a-tsconfigjson) _in addition_ to the
+`watchIgnoredRegex` option. For instance, if we wanted to ignore the `my-component.tsx` file, we'd specify:
+
+```json title="tsconfig.json"
+{
+ ...,
+ "watchOptions": {
+ "excludeFiles": ["src/components/my-component/my-component.tsx"]
+ }
+}
+```
+
+:::
diff --git a/docs/config/extras.md b/docs/config/extras.md
index e73e05eae..bfed8bfac 100644
--- a/docs/config/extras.md
+++ b/docs/config/extras.md
@@ -130,6 +130,10 @@ An experimental flag that when set to `true`, aligns the behavior of invoking th
### scriptDataOpts
+:::caution
+This option has been deprecated and will be removed in the next major Stencil release.
+:::
+
It is possible to assign data to the actual `
+
+
+
+
+
+