Skip to content

docs(output-target): custom elements auto-define export behavior #916

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rwaskiewicz merged 4 commits into from
Sep 19, 2022
Merged

docs(output-target): custom elements auto-define export behavior #916

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b8e2ae0
docs(output-target): custom elements auto-define export behavior
Sep 15, 2022
c7adba4
misc(docs): order custom elements export options
Sep 19, 2022
5e17a89
misc(docs): order custom elements export options
Sep 19, 2022
37645ed
docs(output-targets): update custom elements export behavior type def
Sep 19, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 5 additions & 16 deletions src/docs/output-targets/custom-elements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,22 +69,11 @@ export const config: Config = {
};
```

| Option | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | No additional re-export or auto-definition behavior will be performed.<br><br>This value will be used if no explicit value is set in the config, or if a given value is not a valid option. |
| `single-export-module` | All component and custom element definition helper functions will be exported from the `index.js` file in the output directory (see [Defining Exported Custom Elements](#defining-exported-custom-elements) for more information on this file's purpose). This file can be used as the root module when distributing your component library, see [below](#distributing-custom-elements) for more details. |

<!-- TODO(STENCIL-457): Move this info to the appropriate option on `customElementsExportBehavior` -->

### autoDefineCustomElements

By default, consumers of the `dist-custom-elements` output target need to
register each Stencil component that they want to use in the bundle manually.
Setting this flag to `true` will define a component automatically with the
`CustomElementRegistry` when the component's module is imported. Note that this
will also automatically recursively define any child components as well.

This flag defaults to `false` when omitted from a Stencil configuration file.
| Option | Description |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | No additional re-export or auto-definition behavior will be performed.<br><br>This value will be used if no explicit value is set in the config, or if a given value is not a valid option. |
| `single-export-module` | All component and custom element definition helper functions will be exported from the `index.js` file in the output directory (see [Defining Exported Custom Elements](#defining-exported-custom-elements) for more information on this file's purpose). This file can be used as the root module when distributing your component library, see [below](#distributing-custom-elements) for more details. |
| `auto-define-custom-elements` | A component and its children will be automatically defined with the `CustomElementRegistry` when the component's module is imported. |
Copy link
Copy Markdown
Member

@rwaskiewicz rwaskiewicz Sep 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it make sense for us to order this alphabetically? I'm kind of on the fence here, since "default" is kind of a special value and I don't know if I'd prefer to differentiate it here by having it at the top. I suppose that doesn't prevent us from doing something like

  • default
  • auto-define-custom-elements
  • single-export-module

At the same time, there's really nothing wrong with

  • auto-define-custom-elements
  • default
  • single-export-module

either. Thoughts?

Copy link
Copy Markdown
Contributor Author

@tanner-reits tanner-reits Sep 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like keeping default at the top, but alphabetizing the others makes sense.


> Note: At this time, components created not using JSX may not be automatically
> defined. This is a known limitation of the API and users should be aware of
Expand Down
⚡