improve documentation and onboarding

[Tomamusi]

Hello,

Thank you for this awesome project—I truly appreciate the work that went into building it!

I had a somewhat frustrating first experience and wanted to share some honest feedback along with suggestions for improvement.

The CLI tool works wonderfully; within minutes, I was tinkering with my components and enjoying instant updates via hot reload. That part is excellent.

However, my main goal with Stencil is to build reusable Web Components that I can import and use in other projects—not just within a Stencil-scaffolded application. Specifically, I wanted to build a standard Web Component and include it in a standalone index.html file from another web app. After an afternoon of fails and errors, I still havn't found a solution.

I was surprised that the “how to build and import your project” steps aren’t included on the Getting Started page, considering they are central to Stencil’s purpose. I had to search deep in the documentation under the “Guide → Publishing” and “Guide → Bundling” sections to find the relevant information, but even after reading them, I was not able to a simple WC import.

My usual approach for using Web Components is pretty simple, and I was expecting the same level of complexity: I write them from scratch in a plain JavaScript file and import them either locally:

<!-- on my-site.com -->
<script type="module" src="./my-component.js"></script>
<my-component></my-component>

or externally:

<!-- on my-site.com -->
<script type="module" src="http://wc-provider.com/my-component.js"></script>
<my-component></my-component>

I was hoping to apply a similar flow to a simple hello-world test component built with Stencil, but couldn’t find a straightforward method. The documentation only discusses publishing through NPM, which seems like overkill when I just want to test a simple component.

Furthermore, the dist folder contains many files, and it was unclear which file to import. After trying several, I consistently encountered the error:

export declarations may only appear at top level of a module

After spending an afternoon on this, I’m still unable to easily import a Stencil-created Web Component into my web app.

Thank you for considering my feedback. I hope these suggestions help improve the experience for users who want to quickly try stencil out, just for fun, without reading through all the documentation. I struggled getting the quick win I needed to dig more into it.

I hope I can come back soon to give it another try !

[johnjenkins]

Thanks so much for the constructive feedback @Tomamusi !

It really helps to have new eyes / perspective on something like this.

Stencil is pretty old and has accrued quite a bit of baggage over time; docs get left behind and unloved pretty quickly.

Can’t promise I’ll have time to do anything soon - but having an issue will help remind us.

Feel free to reach out on Discord in the meantime - someone will help out there

[zzy-life]

I feel the same way. I just want to test a "hello-world" component on js, vue, and react.
But the documentation doesn't allow me to find the steps or template code

[zzy-life]

I can't even find an explanation for the project structure generated by npm init stencil