docs(publishing): update general docs on publishing #1359
Conversation
christian-bromann
requested review from
rwaskiewicz and
alicewriteswrongs
and removed request for
a team
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
Thanks for the feedback. I applied the updates accordingly. |
| // or extend custom element via | ||
| class MyCustomComponent extends MyComponent { | ||
| // ... |
There was a problem hiding this comment.
Is this a use case we support? Extending a component built by Stencil?
There was a problem hiding this comment.
Yes, for example, let's say we publish a create-stencil component, you can change functionality by extending the class and overwriting component methods, e.g.:
<script type="module">
import { MyComponent } from 'https://unpkg.com/[email protected]/dist/components/index.js'
class ChangedComponent extends MyComponent {
getText() {
return 'a new component!';
}
}
customElements.define('my-component', ChangedComponent);
customElements.define('my-component-orig', MyComponent);
</script>
<my-component first="foo" last="bar"></my-component>
<my-component-orig first="foo" last="bar"></my-component-orig>This will result in:
There was a problem hiding this comment.
wow I didn't know that worked! I guess I hadn't tried it
There was a problem hiding this comment.
Yeah extending the compiled class output will work, but obviously wouldn't be able to add any additional reactivity (states, props, watchers, etc.) at this time.
| @@ -128,32 +128,6 @@ _default: `false`_ | |||
|
|
|||
| Setting this flag to `true` will cause file minification to follow what is specified in the [Stencil config](../config/01-overview.md#minifyjs). _However_, if [`externalRuntime`](#externalruntime) is enabled, it will override this option and always result in minification being disabled. | |||
|
|
|||
| ## Consuming Custom Elements | |||
|
|
|||
| By default, the custom elements files will be written to `dist/components/`. This directory can be configured using the output target's [`dir`](#dir) config. | |||
There was a problem hiding this comment.
I feel like we lost some of this information in the transition, can we integrate this back into the docs?
There was a problem hiding this comment.
I added some sections back in Publishing > Use Cases > Standalone
| // or extend custom element via | ||
| class MyCustomComponent extends MyComponent { | ||
| // ... |
There was a problem hiding this comment.
wow I didn't know that worked! I guess I hadn't tried it
| "exports": { | ||
| ".": { | ||
| "import": "./dist/components/index.js", | ||
| "types": "./dist/components/index.d.ts" | ||
| }, | ||
| "./my-component": { | ||
| "import": "./dist/components/my-component.js", | ||
| "types": "./dist/components/my-component.d.ts" | ||
| } | ||
| }, |
There was a problem hiding this comment.
not something we should do now, but it would be nice for supporting this usage of exports with DCE if we could auto-generate a JSON blob for all the components, so that users didn't have to automatically keep it in sync - imagine the nightmare of doing that if you had 200 components or something like that
There was a problem hiding this comment.
Yeah, sounds like a great idea!
| :::note | ||
| If you are distributing both the `dist` and `dist-custom-elements`, then it's best to pick one of them as the main entry depending on which use case is more prominent. | ||
| ::: |
There was a problem hiding this comment.
By this you mean the file path in the main field in package.json? There's a main field shown above for dist but it doesn't show one for DCE, might be helpful to have that more explanation of what setting the main field would look like for DCE
(possible I'm also misunderstanding something here haha)
There was a problem hiding this comment.
I left this out intentionally as I don't know if it is a good idea to define a main entry point DCE. main is usually only used for CJS environments. We don't export DCE as CJS module. I am sure this can be configured but don't think anyone would want to import CJS to then re-transpile back to ESM which is what is supported in the browser.
There was a problem hiding this comment.
Ok that sounds fine, I guess if the user is going to distribute both then we can rely on them a bit to figure out how to do that correctly
Co-authored-by: Ryan Waskiewicz <[email protected]>
Co-authored-by: Alice Pote <[email protected]>
christian-bromann
force-pushed
the
cb/update-publishing-docs
branch
from
dee02b5 to
3b98c01
Compare
christian-bromann
requested review from
tanner-reits
and removed request for
rwaskiewicz
| // or extend custom element via | ||
| class MyCustomComponent extends MyComponent { | ||
| // ... |
There was a problem hiding this comment.
Yeah extending the compiled class output will work, but obviously wouldn't be able to add any additional reactivity (states, props, watchers, etc.) at this time.
Currently our documentation around publishing docs in not very well structured and content is scattered among different pages. This caused confusions in the ecosystem. This patch attempts to clean up our docs by restructuring the content and put an emphasis on the distribution use cases: lazy loading and standalone Stencil modules. To summarize the changeset:
package.jsonexports based on the use case