Skip to content

Commit

Permalink
added links to top of readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jthoms1
jthoms1 committed Oct 11, 2019
1 parent 3afc92f commit bfe69e3
Showing 1 changed file with 37 additions and 26 deletions.
63 changes: 37 additions & 26 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,22 @@
| Project | Package | Version | License |
| --------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------- | ---------------------------------------------------------- |
| React Output Target | [`@stencil/react-output-target`](https://www.npmjs.com/package/@stencil/react-output-target) | [![npm][npm-badge-react]][npm-badge-react-url] | [![license][npm-license-react]][npm-license-react-url] |
| Angular Output Target | [`@stencil/angular-output-target`](https://www.npmjs.com/package/@stencil/angular-output-target) | [![npm][npm-badge-angular]][npm-badge-angular-url] | [![license][npm-license-angular]][npm-license-angular-url] |

# Introduction

Unfortunately the experience of integrating web components into existing applications can be tricky at times. More about this can be read at https://custom-elements-everywhere.com/. In order to accommodate the various issues the Stencil team has created new output target plugins to make the process simpler.

The plugins add additional output targets for each framework binding that is included.

## Angular
Angular has a pretty good story for integration with web components but there are a few issues with the developer experience. If you want to know what the story is without the bindings go here: /docs/angular.

With bindings the web components get wrapped in an Angular component and then immediately become available as Angular Components. Some of the advantages of doing this are that you get types for your components and you also get the ability to use ngmodel on inputs. Your developers then consuming your web components from Angular applications import an actual Angular Library and to them it feels as though they are interacting with Angular components.
Angular has a pretty good story for integration with web components but there are a few issues with the developer experience. If you want to know what the story is without the bindings go here: /docs/angular.

With bindings the web components get wrapped in an Angular component and then immediately become available as Angular Components. Some of the advantages of doing this are that you get types for your components and you also get the ability to use ngmodel on inputs. Your developers then consuming your web components from Angular applications import an actual Angular Library and to them it feels as though they are interacting with Angular components.

### Stencil Config setup

To make use of the AngularOutputPlugin first import it into your stencil.config.ts file. Then add it as an OutputTarget.

```ts
Expand All @@ -19,36 +25,34 @@ import { angularOutputTarget, ValueAccessorConfig } from '@ionic-enterprise/angu

export const config: Config = {
namespace: 'demo',
outputTargets:[
outputTargets: [
angularOutputTarget({
componentCorePackage: "component-library",
componentCorePackage: 'component-library',
directivesProxyFile: '../component-library-angular/src/directives/proxies.ts',
valueAccessorConfigs: angularValueAccessorBindings,
}),
{
type: 'dist',
}
]
}
},
],
};
```

#### componentCorePackage

This is the NPM package name of your core stencil package. In the case of Ionic we chose ‘@ionic/core’. This is the package that gets published that contains just your web components. This package is then used by the Angular package as a dependency
This is the NPM package name of your core stencil package. In the case of Ionic we chose ‘@ionic/core’. This is the package that gets published that contains just your web components. This package is then used by the Angular package as a dependency

#### proxiesFile

This is the output file that gets generated by the outputTarget. This file should be referencing a different package location. In the example case we are choosing a sibling directory’s src directory. We will then create an Angular package that exports all components defined in this file.

This is the output file that gets generated by the outputTarget. This file should be referencing a different package location. In the example case we are choosing a sibling directory’s src directory. We will then create an Angular package that exports all components defined in this file.

#### valueAccessorConfigs

In order for ngmodel to work on input components we need to define certain pieces of information about the input components. Unfortunately the Stencil compiler cannot infer the intent of components because this is a very conceptual idea.

### Setup of Angular Component Library

There is an example component library package available on Github so that you can get started. This repo will likely live as a sibling to your Stencil component library. https://github.com/ionic-team/stencil-ds-angular-template

There is an example component library package available on Github so that you can get started. This repo will likely live as a sibling to your Stencil component library. https://github.com/ionic-team/stencil-ds-angular-template

### Usage

Expand All @@ -65,12 +69,11 @@ import { ComponentLibraryModule } from 'component-library-angular';
export class AppModule { }
```


## React

React has a difficult story with web components. Their documentation shows the simplest possible example but more than likely you will want to pass more than strings to your component. If you want to know what the story is without the bindings go here: /docs/react.
React has a difficult story with web components. Their documentation shows the simplest possible example but more than likely you will want to pass more than strings to your component. If you want to know what the story is without the bindings go here: /docs/react.

With bindings the web components get wrapped in a React component and then immediately become available as React Components. Some of the advantages of doing this are that you get types for your components. One of the main issues with React is that react does not propertly pass properties to web components. Out of the box React can only pass strings and numbers to components and it cannot listen to custom events. With the bindings the components appear as though they are React components and all properties get passed correctly including functions, objects, and arrays. The bindings also account for custom events by creating a prop called ‘on<EventName>’. These allow React developers to interact with the web components as though they are React components.
With bindings the web components get wrapped in a React component and then immediately become available as React Components. Some of the advantages of doing this are that you get types for your components. One of the main issues with React is that react does not propertly pass properties to web components. Out of the box React can only pass strings and numbers to components and it cannot listen to custom events. With the bindings the components appear as though they are React components and all properties get passed correctly including functions, objects, and arrays. The bindings also account for custom events by creating a prop called ‘on<EventName>’. These allow React developers to interact with the web components as though they are React components.

### Stencil Config setup

Expand All @@ -80,33 +83,41 @@ import { reactOutputTarget } from '@ionic-enterprise/react-output-plugin';

export const config: Config = {
namespace: 'demo',
outputTargets:[
outputTargets: [
reactOutputTarget({
componentCorePackage: "component-library",
proxiesFile: '../component-library-react/src/components.ts'
componentCorePackage: 'component-library',
proxiesFile: '../component-library-react/src/components.ts',
}),
{
type: 'dist',
}
]
}
},
],
};
```

#### componentCorePackage

This is the NPM package name of your core stencil package. In the case of Ionic we chose ‘@ionic/core’. This is the package that gets published that contains just your web components. This package is then used by the React package as a dependency
This is the NPM package name of your core stencil package. In the case of Ionic we chose ‘@ionic/core’. This is the package that gets published that contains just your web components. This package is then used by the React package as a dependency

#### proxiesFile

This is the output file that gets generated by the outputTarget. This file should be referencing a different package location. In the example case we are choosing a sibling directory’s src directory. We will then create a React package that exports all components defined in this file.

This is the output file that gets generated by the outputTarget. This file should be referencing a different package location. In the example case we are choosing a sibling directory’s src directory. We will then create a React package that exports all components defined in this file.

### Setup of React Component Library

There is an example component library package available on Github so that you can get started. This repo will likely live as a sibling to your Stencil component library. https://github.com/ionic-team/stencil-ds-react-template

There is an example component library package available on Github so that you can get started. This repo will likely live as a sibling to your Stencil component library. https://github.com/ionic-team/stencil-ds-react-template

### Usage

```ts
import { DemoComponent } from 'component-library-react';
```

[npm-badge-react]: https://img.shields.io/npm/v/@stencil/react-output-target.svg
[npm-badge-react-url]: https://www.npmjs.com/package/@stencil/react-output-target
[npm-badge-angular]: https://img.shields.io/npm/v/@stencil/angular-output-target.svg
[npm-badge-angular-url]: https://www.npmjs.com/package/@stencil/angular-output-target
[npm-license-react ]: https://img.shields.io/npm/l/@stencil/react-output-target.svg
[npm-license-react-url]: https://github.com/ionic-team/stencil-ds-plugins/blob/master/packages/react-output-target/LICENSE
[npm-license-angular ]: https://img.shields.io/npm/l/@stencil/angular-output-target.svg
[npm-license-angular-url]: https://github.com/ionic-team/stencil-ds-plugins/blob/master/packages/angular-output-target/LICENSE

0 comments on commit bfe69e3

Please sign in to comment.