|
| 1 | + |
| 2 | + |
| 3 | +# Stencil Component Starter |
| 4 | + |
| 5 | +This is a starter project for building a standalone Web Component using Stencil. |
| 6 | + |
| 7 | +Stencil is also great for building entire apps. For that, use the [stencil-app-starter](https://github.com/ionic-team/stencil-app-starter) instead. |
| 8 | + |
| 9 | +# Stencil |
| 10 | + |
| 11 | +Stencil is a compiler for building fast web apps using Web Components. |
| 12 | + |
| 13 | +Stencil combines the best concepts of the most popular frontend frameworks into a compile-time rather than run-time tool. Stencil takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and generates 100% standards-based Web Components that run in any browser supporting the Custom Elements v1 spec. |
| 14 | + |
| 15 | +Stencil components are just Web Components, so they work in any major framework or with no framework at all. |
| 16 | + |
| 17 | +## Getting Started |
| 18 | + |
| 19 | +To start building a new web component using Stencil, clone this repo to a new directory: |
| 20 | + |
| 21 | +```bash |
| 22 | +git clone https://github.com/ionic-team/stencil-component-starter.git my-component |
| 23 | +cd my-component |
| 24 | +git remote rm origin |
| 25 | +``` |
| 26 | + |
| 27 | +and run: |
| 28 | + |
| 29 | +```bash |
| 30 | +npm install |
| 31 | +npm start |
| 32 | +``` |
| 33 | + |
| 34 | +To build the component for production, run: |
| 35 | + |
| 36 | +```bash |
| 37 | +npm run build |
| 38 | +``` |
| 39 | + |
| 40 | +To run the unit tests for the components, run: |
| 41 | + |
| 42 | +```bash |
| 43 | +npm test |
| 44 | +``` |
| 45 | + |
| 46 | +Need help? Check out our docs [here](https://stenciljs.com/docs/my-first-component). |
| 47 | + |
| 48 | + |
| 49 | +## Naming Components |
| 50 | + |
| 51 | +When creating new component tags, we recommend _not_ using `stencil` in the component name (ex: `<stencil-datepicker>`). This is because the generated component has little to nothing to do with Stencil; it's just a web component! |
| 52 | + |
| 53 | +Instead, use a prefix that fits your company or any name for a group of related components. For example, all of the Ionic generated web components use the prefix `ion`. |
| 54 | + |
| 55 | + |
| 56 | +## Using this component |
| 57 | + |
| 58 | +There are three strategies we recommend for using web components built with Stencil. |
| 59 | + |
| 60 | +The first step for all three of these strategies is to [publish to NPM](https://docs.npmjs.com/getting-started/publishing-npm-packages). |
| 61 | + |
| 62 | +### Script tag |
| 63 | + |
| 64 | +- Put a script tag similar to this `<script src='https://unpkg.com/[email protected]/dist/mycomponent.js'></script>` in the head of your index.html |
| 65 | +- Then you can use the element anywhere in your template, JSX, html etc |
| 66 | + |
| 67 | +### Node Modules |
| 68 | +- Run `npm install my-component --save` |
| 69 | +- Put a script tag similar to this `<script src='node_modules/my-component/dist/mycomponent.js'></script>` in the head of your index.html |
| 70 | +- Then you can use the element anywhere in your template, JSX, html etc |
| 71 | + |
| 72 | +### In a stencil-starter app |
| 73 | +- Run `npm install my-component --save` |
| 74 | +- Add an import to the npm packages `import my-component;` |
| 75 | +- Then you can use the element anywhere in your template, JSX, html etc |
0 commit comments