Forem: Philippe Riand

LWC: A sample fetch data accessor

Philippe Riand — Sun, 15 Mar 2020 20:13:00 +0000

What would an LWC application be if it does not fetch data from a server? The browser now made this easy, particularly with the fetch function, or its polyfill for older browsers. The general pattern with LWC/Web Components is to fetch data in connectedCallback(), once the component is added to the DOM. If this can be achieved with simple code, let see how we can make it even easier with wire adapters. In particular, we like to do the following:

Have a simple syntax for calling the services.
Do not hard code the full URL in the components, so we can easily, and globally, switch the endpoint (dev, staging, prod...), or even mock the server for test purposes.
Use URL variable parts, or query parameters.
Be able to re-fetch the data when needed, in particular when the variable values change. The code that illustrates this post is available as part of the LWC essentials: https://github.com/LWC-Essentials/wire-adapters/tree/master/packages/fetch. Feel free to check it out and submit enhancements. or suggestions! You can also consume the NPM package @lwce/fetch.

Using the fetch wire adapter

The syntax is straightforward:

@wire(useFetch, options) myproperty;

Let see an an example showing the wire adapter in action. This one calls a user service with query parameters:

export default class UserList extends LightningElement {  
   @track queryParams = {  
        offset: 0,  
        limit: 10  
    }  
    @wire(useFetch, {  
        url: '/users',  
        queryParams: '$queryParams'  
    }) users;

When the component is initialized, the fetch request is executed and the users variables get the result.

Requests can also be executed explicitly. Obviously, this is useful for update requests, but also for on demand GET requests:

export default class Users extends LightningElement {  
    @track variables = {  
        userId: 'xyz'  
    }  
    @wire(useFetch, {  
        url: '/users/{userId}',  
        lazy: true,  
        variables: '$variables'  
    }) userById;  

    handleUserClick(event) {  
        const idx = this.\_findUserIdx(event);  
        if(idx!==undefined) {  
            const userId = this.users.data.users[idx].email;  
            this.userById.fetch( {variables:{userId} ).then( ()=>{  
                alert(JSON.stringify(this.userById.data));  
            });  
        }  
    }

The result property exposes a fetch() method that can be called programmatically, while the lazy parameter of the wire adapter prevent the automatic execution when the component is initialized.

There are several other options, but I don't want to go too much into the use of the adapter, as the README.md file already does that pretty extensively.

Let's rather dive into the implementation details.

Implementation details

The fetch wire adapter implementation is fairly straightforward, but there are a few traps that we should be aware of.

Duplicating the result object

The current result object is kept in a variable within the wire adapter closure, and new values are simply assigned to this object before it is sent to the component. This makes it easier from an implementation standpoint, for example setting the invariant values, like the fetchClient instance, or the fetch() method.

But has a drawback: the component will only detect a change, and thus redraw, when a new object is sent by the wire adapter. So the object kept by the adapter can't be sent as is to the component. Rather, the update() function duplicates it and send the copy to the component.

Concurrent requests

The result from a fetch() call is by definition retrieved asynchronously, which means that we do not control when that result will be available. Moreover, if multiple requests are sent sequentially by the same wire adapter, there is no guarantee that the respective results will come in the same order than the requests were emitted. Imagine a UI featuring a button that triggers a change in the wire adapter. If a user frenziedly clicks that button, it is likely that new requests will be emitted by the wire adapter before the results of the previous ones come back, with no guarantee that the results will be retrieved in order. This is well known issue in JavaScript based UI, generally hard to detect and debug.

Wire adapters, if not designed appropriately, are no exception. I created a code snippet to showcase the issue: https://developer.salesforce.com/docs/component-library/tools/playground/8peP8wto/12/edit.

Alright, now that we are aware of this issue, here is a set of potential solutions:

Prevent a new request from being emitted while one is still pending
Ignore the oldest ones when their result comes back and only process the latest one

If 1. is easy to implement, it does not provide the best user experience because the UI is frozen until the current request's result comes back. On the other hand, it can also be implement at the application level, for example by disabling the button until the request comes back.

The fetch wire adapter implements the second one by default. It actually associates a unique index to each request, keeps it in the closure of response handler (fetchIndex), and also globally keeps the index of the latest request (fetchCurrent). When a result comes back, it only processes it if it corresponds to the latest request. All other results are simply ignored.

As a conclusion...

Basic wire adapters are easy to implement, while providing a unified way to expose data to component developers. Jump over the fence, and start to create yours! Or extend the one we are providing as part of the LWC-Essentials/wire-adapters project. I'd love to grow this repo with your contributions.

LWC: Accessing GraphQL data with the Apollo client

Philippe Riand — Mon, 10 Feb 2020 17:29:00 +0000

If you're a front-end developer calling GraphQL endpoints from your UI, you must have heard about the JavaScript Apollo Client library. This library is a state management library that let developers execute GraphQL queries against GraphQL servers as well as a local store. It handles caching, change notifications and features interesting capabilities like optimistic UI.

The flagship implementation from the Apollo team is dedicated to React but, fortunately, the implementation is split in two layers:

A pure JavaScript Apollo Client library This library is not related to any client technology. It implements all the necessary plumbing to support GraphQL queries in JavaScript.
View integrations Provided on top of the aforementioned library, these integrations make it easier to consume the Apollo client with your technology of choice (React, Angular, Vue, Svelte, Ember, ...). If the React and Angular integrations are done by the Apollo team, the others are provided by third party contributors.

Integrating LWC

There is a Web Component integration available, which can work with LWC as well. Actually, the LWC adapter code on top of this library would be minimal. On the other hand, it won't take advantage of the LWC specific features, in particular the wire adapters. So the idea is to create a new integration specifically for LWC, leveraging wire adapters similarly to hooks in the React integration.

For the impatient, the integration is available here: apollo-client. It provides a sample application that shows CRUD operations on a server, in memory list of books.

GraphQL Queries

A GraphQL query in the React integration uses a hook named useQuery. Here is an example:

  const { loading, error, data } = useQuery(MY_QUERY);

A very similar syntax can be achieved with LWC wire adapters. We even keep the same name, useQuery, for the wire adapter:

  @wire(useQuery, { query: MY_QUERY }) results;

The results property features the following sub properties, similarly to the React hook:

  { loading, error, data }

Any of these sub properties is available at any time, so the component template can display appropriate content, with pseudo code like:

  <template if:true={results.loading}>  
    <img src="loading.gif"/>Loading...   
  </template>  
  <template if:true={results.error}>  
    Man, there is an error {results.error}   
  </template>  
  <template if:true={results.data}>  
    Here is the data: {results.data}   
  </template>

The results property also features even more sub properties. In particular, it offers a fetch() method that re-fetches the query.

Finally, a wire adapter has more options than just the query: it can use a specific Apollo client, defer the query execution with lazy, use variables and any other standard options used by the Apollo client watchQuery(). See README.md for a more exhaustive list of options.

Here is a example of a query using variables for pagination, assuming that the query supports offset and limit parameters:

  const BOOK_LIST = gql`  
      query($offset: Int!, $limit: Int!) {  
          books(offset: $offset, limit: $limit) {  
            id,  
            title  
            author  
          }  
      }`;  

  class Booklist extends LightningElement {  

    variables = {  
        offset: 0,  
        limit: 10  
    }  

    @wire(useQuery, {  
        query: BOOK_LIST,  
        variables: '$variables'  
    }) books;

A more complete example is available in the project sample application.

Because wire adapters options can only observe changes to root properties, we created the variables property to hold the query variables. Then, when we want to update one of its value (ex: offset), then we have to assign a brand new object to that property:

    handleFirst() {  
        this.variables = {  
            ...this.variables,  
            offset: 0  
        }  
    }

Finally, if it is possible to use the query inline, it is better to declare it as a constant (BOOK_LIST in the example). This is because the current wire adapter implementation will repeat that value multiple times in the generated code.

GraphQL Mutations

Mutations are also provided using wire adapters, although they should be executed on demand as opposed to when the component is connected. The wire adapter provides a mutate method that can be called anytime to execute the mutation.

Bellow is a simple sample that creates a book:

  // Define the mutation query   
  const BOOK_CREATE = gql`  
    mutation createBook($book: BookInput!) {  
        createBook(book: $book) {  
            id  
            title  
            author  
            genre  
            publisher  
        }  
    }  
  `;  

  // Mutation adapter use in the component class   
  @wire(useMutation, {mutation: BOOK_CREATE}) bookCreate;  
  onCreateBook() {   
    const newBookValues = {  
      book: {  
        title: "A book",  
        author: "John Doe",  
        genre: "Novel",  
        publisher: "MyBook"  
      }  
    };  
    this.bookCreate.mutate({  
      newBookValues  
    });  
  }

The sample app coming with the project shows all the CRUD operations on books: Create, Read, Update and Delete.

And What's Next?

Well this project is a first shot. A lot more has to be done, but this is a good start, isn't it? It needs your contributions to be on par with the React implementation. Please feel free to submit your ideas, code or examples.

LWC Reactive State Manager

Philippe Riand — Wed, 05 Feb 2020 18:07:00 +0000

If you started to create LWC applications, you might have found that managing the state of a component is trivial, thanks to the reactive properties and the @track decorator. You do not have to deal with a specific state property, or explicitly ask the component to render when its state changed.

Now, when your application gets more complex, you often want this state to be shared with other components. This is when state managers, like Redux or MobX, come into play. As these libraries are technology agnostic, you can obviously use them with LWC components. To make it easier, you can even create a few helpers, typically wire adapters.

But can we create a store manager that is closer to LWC, leveraging the core LWC capabilities to provide global state management?

Towards a Reactive LWC Store

First, the code described bellow is available as a library published here: https://www.npmjs.com/package/@lwce/store. The source code is on Github: https://github.com/LWC-Essentials/wire-adapters/tree/master/packages/store.

The idea is simple: we can have a global object, the "store", that holds [key:value] entries. Then, we'll use a wire adapter that lets a component access any entry in the store using a key:

  @wire(useStore, {key: 'user'}) user;

That's it. The user property is "reactive" so any change to its content will be tracked by the component. Multiple components can share the same entry coming from the store, by using the same key. Even pure JavaScript code can access an entry programmatically:

  const u = getEntry('user')

To make all the entries reactive, we need the global store object, holding all these entries, to be itself reactive. The LWC component reactivity is provided by a specific membrane, called the reactive membrane, which is private to the runtime. The solution is then to create an invisible component that holds the whole store object as a reactive property. This component is silently created when we initialize the store using:

  initStore(content?: object)

The content parameter is optional, just in case we want to initialize the store with initial values. It can be useful, for example, when the store is pre-populated from server side rendering results.

Adding Entries to the Store

Accessing a store value using the @wire or the API is simple, but how do we add an entry to that store? Well, the answer is straightforward: lazily, when we need it. In other words, an entry is created in the store the first time it is requested by key. And, right after being created, it gets initialized. For this, the developer can register initializers that will be invoked during this step:

  registerInitializer(  
    (key) => {  
        if(key==='user') {  
            return {name: 'Doe', first: 'John'};  
        }  
        return undefined; // not for this entry  
    }  
  );

If the initialization data is not immediately available, for example because the data comes from a network request, an initializer can return a Promise. The store will consume the value when the promise will be resolved. By the meantime, the consumer can check some boolean values to understand the status of the entry, see bellow.

Rich Entry Content

Entries in the store are actually not just exposing the raw data, but an object with the following properties:

  {  
    data: any  
    error: string  
    loading: boolean  
    initialized: boolean  
  }

So in our example above, the user content have to be accessed through the data property:

   const u = getEntry('user').data

Similarly in a component template:

  <p>{user.data.firstName} {user.data.lastName}</p>

Because an entry contains {error, loading, initialized}, a consumer can also check if:

An error happened during initialization. error will then contain the error message.
The data is still being loaded
The data has already be initialized once The difference between loading and initialized is subtle: as a store entry can be reloaded, loading can happen while data has already been loaded once. In that case, the developer can choose to provide a slightly different UI (ex: the previous data is still displayed with a loading icon while the entry is being reloaded).

Putting the Store in Action

The sample-app accompanying the library on Github shows a commerce cart built using this library: https://github.com/LWC-Essentials/wire-adapters/tree/master/packages/sample-app

All the components (cart, checkout, basket icon) are sharing the same 'cart' store entry. They all update when cart changes:

As all the store entries are reactive, simply changing some values within the cart makes all the components re-render.

LWC Wire Adapters #2 - Producing Data Streams

Philippe Riand — Fri, 31 Jan 2020 22:02:00 +0000

We saw in the previous post that wire adapters are a very elegant and efficient way to consume data streams. Let's see now how we can produce these data streams. If it seems magic, it is actually a pretty easy API.

*Disclaimers*

#1 - This post talks about the original wire adapter API, as described here. There is an upcoming new implementation that keeps the same consumer interface, but where the provider API is a bit different, see wire-reform. This blog post talks about the former, and will be updated when the later will be released.

#2 - Custom wire adapters are currently only available to the Open Source version of LWC, not to LWC running in Salesforce Core.

Our First Wire Adapter

To introduce the wire adapter API, let's implement a stopWatch component that behind the scene uses a wire adapter streaming the time elapsed. This wire adapter offers some callbacks to start, stop and reset the timer:

For the impatient, the source code is provided through the LWC playground:
https://developer.salesforce.com/docs/component-library/tools/playground/8peP8wto/8/edit

Wire Adapters Registry

LWC maintains a global registry of wire adapters, so each wire adapter has to be registered before it can be consumed by a component. It is uniquely identified by a key, which can be a Symbol or a Function. As a good practice, this key is exported from the wire adapter JavaScript module. The registration is done through the register method:

  register(key, myAdapterFunction);

The current implementation also requires a global, LWC provided, "wire service" to be registered before any wire adapter can be used. The main file of an application is generally a good place for it.

  import { register } from "lwc";  
  // The wire service has to be registered once  
  import { registerWireService } from 'wire-service';  
  registerWireService(register);

Note that the example above does not have to do this, as the Playground does it automatically for any code snippet.

Wire Adapter Implementation

A wire adapter is defined by a function that is called once when the wire adapter is initialized. It has a unique parameter, eventTarget, which represents the consumer of this wire adapter.

To get started, here is how our simple wire adapter skeleton stopWatch looks like:

  // Define the Symbol identifying the wire adapter  
  export const stopWatch = Symbol('stop-watch');  

  // Register the wire adapter implementation  
  register(stopWatch, eventTarget => {  
      // wire adapter implementation

      // ...  
  });

stopWatch This is the wire adapter key, exported so components can reference it.
eventTarget The context passed by the engine, see bellow.

Initialization

The wire adapter API is event based: it receives notifications when it has to take an action. In fact it can register handlers for the following 3 different events:

connect This event is emitted when the component owning the wire adapter is connected to the DOM. At that time, it is safe for the wire adapter to send data to the component.
disconnect This event is emitted when the component owning the wire adapter is disconnected from the DOM. When the component is disconnected, the wire adapter can cleanup its internal data. For example, if it was observing a data stream, it can disconnect from it. Once a component is disconnected, the wire adapter should no longer send it data, until it connects again.
config This is emitted once initially, and thereafter when the wire adapter options have different values ("reactive options"). The options value are passed as an argument to the handler. To handle these events, the wire adapter has to register handlers to the eventTarget:

  register(stopWatch, eventTarget => {  

    function handleConfig(options) {

      // Do something with the config  
    }  

    function handleConnect() {        
      // The component is connected, send it some values!   
    }  

    function handleDisconnect() {

      // The component is disconnected, cleanup the adapter  
    }  

    // Connect the wire adapter  
    eventTarget.addEventListener('config', handleConfig);  
    eventTarget.addEventListener('connect', handleConnect);  
    eventTarget.addEventListener('disconnect', handleDisconnect);  
  })

Sending data to the component

Once the wire adapter receives the connect event, it can send data to the component. For this, it dispatches a ValueChangedEvent to the component with the new value as an argument:

  const result = ...  
  eventTarget.dispatchEvent(new ValueChangedEvent(result));

Once connected, the wire adapter can send new data to the component at anytime. For example, if the component is listening to a websocket, it can update the component when its gets new data from that websocket.

Assembling the pieces

Well, it is assembled in the playground sample code:

stopwatch.js contains the wire adapter code
app.js/.html defines the component.

Note: there are 2 differences between this code running within the playground and a potential standalone application:

The wire service does not have to be registered, the playground does it
The wire adapter in the playground imports wire-service, while it should be @lwc/wire-service in an app using LWC Open Source.

A few implementation details

The wire adapter uses a configuration option to set the refresh interval. In the example, the value is passed through a reactive property. This makes the handleConfig() handler called with a new value when this property changes:

  @track interval = 50;  
  @wire(timeWatch,{interval:'$interval'}) stopWatch;

The data sent by the wire adapter to the component contains both the timer values (hour, mins, ...) as well as some callback functions to interact with the stopwatch adapter. Here is a mock of that object:

 {  
    // Timer values  
    hour: '00',  
    mins: '00',  
    secs: '00',  
    mils: '000',  
    // Callback functions  
    start: function() {...},  
    stop: function() {...},  
    reset: function() {...},    
}

To make the wire adapter robust, it maintains a connected flag and only sends data to the component when it this flag is true.

This wire adapter implementation creates and sends a copy of the date to the component. Sending the same object instance multiple times to the component does not make the component to re-render, while a copy does.

Finally, wire adapters are simple to implement, aren't they?

LWC Wire Adapters #1 - Consuming Data Streams

Philippe Riand — Fri, 17 Jan 2020 17:07:00 +0000

The previous post talked about LWC reactivity using membranes, which re-render the components when the tracked data is changed, like bellow:

class MyComponent extends LightningElement {  
  @track value;  
}

But how does the data get to the component property, value in the example above? It can come from an external data source like a REST service, and it might even update over time. Think about a stream of data feeding the component with new values when they become available.

Part of the standard web component lifecycle, the connectedCallback() method is called when the component is added to a document connected element. In short, when the custom element is added to the DOM of your page. At that time, it has access to the DOM element with its attributes, so it can call a service using these values. This is the recommended way for developers to connect the component with data sources.

LWC goes further than that, as it makes it simpler, thanks to the "wire adapters". Technically, a wire adapter is a data provider that streams data to a component. The notion of stream is important: it is not only a one time data retrieval, like a Promise, but the data can be continuously updated and the component notified. For the JS experts, it is much like an RxJS Observable.

Wire Adapters from a Consumer Standpoint

Wire adapters are objects instantiated using the @wire decorator. This decorator uses two parameters:

The wire adapter key, that uniquely identifies the adapter to use
A set of options, specific to the wire adapter implementation Let's use a fictitious wire adapter to access a list of books. With the use of a parameter, this wire adapter can even filter the books based on the author. Assigning a list of books to a component property is done with the following syntax:

  class Books extends LightningElement {  
    @wire(BookProvider, {author: 'Mark Twain'}) bookList;   
  }

BookProvider is the wire adapter key. It is generally a Symbol, exported by the module defining the wire adapter.
{author: 'Mark Twain'} is the set of options passed to the wire adapter. This wire adapter only handles one, which is the author filter. When the component is added to the DOM, the wire adapter is connected and executed. Obviously, it will retrieve a list of books and assign it to bookList. The result can be assigned synchronously or asynchronously, depending on the wire adapter implementation. With the later, the component should not assume that the data is available right away, but it can come later.

What the bookList variable contains is up to the wire adapter: it can be raw data, like an array of books, of it can be a richer structure giving more information {data,error,loading, ...}. The later is a good practice. It allows, for example, the component to display an icon while the data is loading asynchronously. Moreover, the property content is not limited to values, but can also contain any kind of JS objects, including callback functions (ex: reload(), fetchMore(), ...). Again, it is up to the wire adapter to define the shape of the data being assigned to the property.

The wired properties are automatically reactive, similarly to properties decorated with @track.

Dynamic Wire Adapters

The wire adapter options can be dynamic. Let's, for example, filter the book list using an author passed as an attribute to the component. This way, we can use the same component multiple times while displaying different lists:

Our Books component becomes:

  class Books extends LightningElement {  
    @api author;   
    @wire(BookProvider, {author: '$author'}) bookList;   
  }

The @api decorator in LWC means that the 'author' property is public: it can be set through an attribute in the markup, or programmatically from outside of the component. The $author value is an LWC convention: it means that the component's author property value should be used instead of a static string value. Note that this only applies to root values. Options like {user: {name:'$name'}} will not be recognized as a reference to a property value, because name is not a root property.

Advanced Wire Adapters

If the value provided by a wire adapter can be assigned to a component property, it can also be streamed to a component method. In this case, the value is passed to the method as an argument.

Let's assume, as an example, that we want to split a book properties into different component tracked properties, we can do something like:

  class Books extends LightningElement {  
    @track title;  
    @track author;   
    @wire(BookByISBN, {ISBN: 'xxxxx'}) book(value) {  
      this.title = value.title;      this.author = value.author;   
    };   
  }

Of course, the code of such a method can do a lot more, like calculation, sending updates, ...

Imperative Access

To be complete, the wire adapter key can be either a Symbol or a Function. When it is a function (a "callable"), it means that it can be called by code, simply by calling that function with parameters. If the parameters could match the wire adapter options, this is not a requirement. Also, the returned value is adapter specific: it can be anything, and does not have to be a Promise. This is reserved to very specific use cases.

The journey continues. Now that we know how to consume a wire adapter, let's figure out how to build one. That will be the topic of the next post.

LWC Reactivity Using Membranes

Philippe Riand — Mon, 13 Jan 2020 13:37:00 +0000

LWC allows you to create reactive components that automatically update their UI when they get new data, or when existing data is modified. At the heart of this reactive capability is the implementation of a pattern called "membrane". Let's dive into that pattern and how it powers LWC.

What is a membrane

Basically a membrane is a thin layer between the consumer of an object and that object. In other words, a membrane exposes consumer facing proxies for any existing object. From a consumer standpoint, accessing the object through the proxy is indistinguisable from intereacting directly with the object. But the membrane can execute business logic ("hooks") whenever the consumer interacts with the object. It can track property access (read/write), method calls, properties enumeration and so on... It can also hide some content to the consumer, or even distort existing content (e.g. change the values being returned). It is a very powerful pattern used for many different purposes, from content isolation to change tracking.

Another important point with a membrane is that any object accessed through a proxy is automatically proxied by the membrane as well. Let's note a proxied object X as P(X).

If A has a property b of type B, then A.b returns a object of type B. But P(A).b returns P(B). The membrane hooked the access to the property b and distorted the result to return a proxy object for b. This is obviously transparent to the consumer:

Because of this, if one starts from a proxied root object and only access the graph from this root object, then it guarantees that all the objects accessed are proxies, and are thus managed by the membrane.

Finally, membranes have another important property: there is a one to one relationship between an object and its proxy for a given membrane. It means that the same P(A) object is returned for a given object A, regardless how it is retrieved. Suppose, for example, that a component has list of child components and a reference to its parent. The equality bellow is true:

         comp.children[0].parent === comp   
That equality is preserved with proxies as well:  
         P(comp).children[0].parent === P(comp)

More detailed information on membranes can be found here: membrane.

Salesforce Membrane Implementation

As said earlier, LWC is using membranes to implement reactivity. But, instead of coding membranes within LWC, Salesforce created a separate general purpose, open source library called observable-membrane. Like other JavaScript implementations, it is based on top of the Proxy API.

With this library, a developer can create a membrane and proxy objects with the simple code bellow:

  const membrane = new ObservableMembrane();  
  ...  
  const o = membrane.getProxy(o);

The membrane object holds a set of functions called when a caller interacts with a proxied object. Thus, the membrane can track when a value is read/updated and eventually distort that value. In short, the ObservableMembrane knows about any property access/change in the graph starting from any proxied object, obtained by calling getProxy().

LWC and Membrane

This is where it becomes interesting: if a membrane can track any change in an object graph, it means that it can re-render a component when it detects a change in the data graph it consumes. This is exactly what the @track property decorator is for:

  class Banner extends LightningElement {
      @track user  

  }

This decorator ensures that any value assigned to the decorated property is actually proxied using the reactiveMembrane. Typically, assigning a value to a tracked property like:

  this.user={ name: 'Paul', ...}

is internally equivalent to:

  this.user=reactiveMembrane.getProxy({name: 'Paul', ...}).

reactiveMembrane is a singleton, defined in the LWC engine library. It tracks the value changes in any object it created proxies for, find the components impacted by the changes and re-render them when necessary. For example, if a component has a onclick event handler like bellow:

  handleClick() {

    this.user.name = 'Bob';

  }

The user name change is detected by the reactiveMembrane and the component is re-rendered without any further work from the developer.

Note that the re-rendering does not happen synchronously when the change is detected. The component is internally tagged as 'dirty' and the rendering will happen later. Thus, sequentially changing multiple tracked values for a component only triggers a single re-rendering.

Multiple components can track changes of the same object. Fortunately, every component will be updated when a change happens to this object, regardless where and how it was updated.

Finally, all the fields in a component are reactive. Adding @track to a component property is only needed for values you'd like to track deeper, like objects or array, not for basic strings, numbers or booleans.

Conclusion

The use of membranes within LWC makes it very easy to track changes and react when they happen. The developers don't have to care about notifying the system when some data is changed, it is "magic". From an implementation standpoint, the use of the Proxy API also makes it very efficient at runtime.

But wait: it reveals all its power when coupled with other LWC technologies. Let's explore that in the next post!

Introducing LWC - Lightning Web Components

Philippe Riand — Wed, 08 Jan 2020 17:57:00 +0000

In the previous post, I talked about Web Components in general. But Salesforce released at TrailheadDX 2019 a new open source technology called Lightning Web Components, aka LWC. Basically, LWC is a set of tools, including a compiler, a runtime engine, some build utilities that you can use to create both reusable components and applications.

Why a tool for creating Web Components?

Actually, Web Components are defined through a set of new browser specifications, so they don't require any framework. There are many examples showing how to create such reusable components just using the bare APIs!

If this is correct, you'll quickly find out that these APIs are very low level. As a result, creating an even moderately complex component requires a bunch of boilerplate code: you need to maintain the synchronization between HTML attributes and JavaScript properties, you need to keep the DOM up-to-date on data changes, ... and many other boring stuff!

That's the reason why several technologies appeared in the past years: they provide you an easier experience with Web Components. They are kind of lightweight frameworks on top of the Web Components APIs. They are often called "invisible" frameworks as, once the components are created, the technology used to create the components is not apparent. As a consumer of the components, you don't really care what has been used behind the scene to create them.

What does LWC bring on the table?

Enterprise ready

LWC is an enterprise ready technology, designed to support Salesforce business in the long term. When I think about it, I can find a lot of similarities between Salesforce and Lotus/IBM: my latest Notes client can still execute applications from the '90, and so Salesforce can execute apps built with older releases (or seamlessly convert them). Such a backward compatibility is critical for businesses! It is even more emphasized with cloud architectures, as the customers are upgraded automatically without the choice to stay on an older release. From an LWC standpoint, it means that every feature added to the tool will have to be supported "forever" and thus is carefully evaluated with a risk assessment. Any new feature has to go through an RFC, see: lwc-rfcs.

ES6+/Typescript

We are in 2020 now, I can't see myself back using ES5 and JQuery. I believe you're on the same boat! LWC eases the use of ES6+, making your code future proof even when staging features like decorators are involved. It is using Babel behind the scene, for which Salesforce Engineering is a proud sponsor.

*Browser support *

If the latest "evergreen" browsers natively support the Web Components specification, older browsers should use polyfills and/or the compiler should generate specific code for these browsers. LWC does a bit of both, including some tailored polyfills to achieve performance goals. @lwc/synthetic-shadow is a good example of such a polyfill.

Templating

LWC provides a template engine that renders markup from an HTML template. Somehow, it is similar to lit-html, except that it is compiled to Javascript at build time, for a faster execution. In that respect, it is similar to the JSX compiler.

Reactivity

If the template syntax supports one-way data binding, the component reactivity comes from observable-membrane, which is another Salesforce open source project. In a nutshell, it allows objects to be observed for changes. Typically, Components are redrawn when at least one of their properties is changed (can be the root property, or another object referenced by that property).

Data Binding

Associated with the above membrane is the notion of wire adapters. Basically, a wire adapter streams data to a component and makes it re-render when needed. It can be used similarly to React hooks. More information here: wire adapters, superseded by the wire-reform.

Performance

Performance is a key characteristic of LWC. It is constantly, and deeply, tuned to provide the best client side performance.

Static analysis

For advanced users, the LWC compiler can be used to extract meta-data from the components. For example, a plugin could extract the data sources being accessed and generate some initialization code.

And several others, like matching attribute and properties, ...: a set of goodies that makes your life easier as a developer!

The flavors of LWC

Well, if there is one LWC technology, there are two deployments:

Salesforce platform The Salesforce platform handles many things for free, like the LWC compilation, so you don't have to manage rollup/webpack builds, nor you have to maintain package.json. On the other hand, it runs within the constraints of the Salesforce platform, including Locker and other differences.
Open source, aka LWC OSS (Github) LWC can be used similarly to any other Javascript technology. To get started, you can use the nice lwc-create-app tools from Rene Winkelmeyer (@muenzpraeger ), that some of you know from our prior IBM life. This is LWC unleashed! The differences are detailed here, thanks again to Rene.

And what next?

Now that I introduced the LWC technology (I hope it got you hooked!), it is time to get our hands dirty. I'm not going to provide any tutorial or getting started document because they already exist. I'll rather focus on some specific aspect of Web Components and LWC.

By the meantime, you can get started here: Introducing Lightning Web Components or here: lwc.dev.

The rise of Web Components

Philippe Riand — Sat, 04 Jan 2020 20:41:00 +0000

It is now been a while since people started to talk about Web Components. But it finally became a reality. As of the beginning of 2020, all the major browsers implement most of the specification. Moreover, the need to support some of the ancient browsers, like the older IEs, is drastically decreasing. Fortunately, there are polyfills to still support IE11 and other not too old generation. So what are web components and should you use them?

Web Components

Web Components is actually a generic term that encompasses several different specifications:

Custom Elements Define new HTML element types (e.g. new HTML tags). They are easily identifiable from the stock HTML elements as their name must include an hyphen '-'. Support: https://caniuse.com/#feat=custom-elementsv1
Shadow DOM Encapsulates the markup and the styles of a component. Basically, the shadow DOM isolates the implementation of your component from the rest of the page. Support: https://caniuse.com/#feat=shadowdomv1
ES6 modules As Web Components heavily rely on JavaScript, ES6 modules define a elegant way to load JavaScript code within the browser. Support: https://caniuse.com/#feat=es6-module
HTML template Used to define fragments of markup that are not rendered by the page, but can be reused later in particular from JavaScript. Support: https://caniuse.com/#feat=template Here is a great introduction to these specifications: https://www.webcomponents.org/introduction

Not that the idea of natively extending the HTML markup and isolating components is not new. There is prior art, like Microsoft HTC or Mozilla XUL. Web Components, instead of being vendor specific, are part of the W3C specification and work similarly on every browser following that spec.

Web components vs Frameworks

Let's put it this way: they do not compete, they rather complement each other. The Web Components specification provides native behaviors implementation, thus helping the frameworks to be simpler and lightweight. On the other hand, the frameworks make it easier to write Web Components. If you were brave enough to write a web component manually, then you know what I'm talking about. What would take a few lines of React code could lead to hundreds using the bare Web Components APIs.

The Web Components specification is an evolving one, that still has gaps to fill. But it reached a state where it provides real value in term of performance and browser compatibility.

How to write Web Components

Ok, let's forget about solely using the raw browser APIs, but let's get help from Frameworks, as they handle a lots of things for us (data binding, event handlers, ...).

Even though existing frameworks came before the Web Components specification, they all have ways to create and consume custom elements. On the other hand, they generally do not (yet?) properly handle advanced capabilities like Shadow DOM:

React React Components are actually fairly different from Web Components. That being said, a React application can both consume custom elements and expose its components as custom elements, see: https://reactjs.org/docs/web-components.html.
Angular Angular, if not built on top of the Web Components specification, is actually closer than React. The Angular team came with Angular Elements, which let's you package your components as custom elements.
Vue.JS Similarly, Vue has its own library to expose custom element: @vue/web-component-wrapper. If using these well known technologies feels appealing, they come with some caveats/limitations when it is about Web Components: the component models have different life cycles, they carry more code than necessary, the features are not matching 1-1...

Fortunately a new generation of frameworks, based on top of the Web Components specification, appeared. Will they replace the legacy ones is a good question. It won't certainly happen soon, although they make it easier and more efficient when leveraging Web Components.

Part of these frameworks are:

Lighning Web Components (LWC) This is one of the latest, but promising framework brought by Salesforce. Ok, my judgment is certainly biased because I'm a Salesforce employee, and because we are using this technology on a daily basis. But trust me, it deserves a look :-) Most of my upcoming posts going further will be around on that technology!
Stencil.JS This technology is developed by the Ionic team, basically to fulfill their own needs. In short, the first Ionic release was Angular based and they got many requests for both a React and a Vue version. So they decided to standardize on a common Web Components implementation and then wrap them within each of these framework.
Polymer That's one of the original frameworks brought by Google. It evolved a lot in the past 5 years, following the browser implementations, finally making it an efficient framework for writing Web Components. Finally, instead of the initial large monolithic framework, it now provides several projects like LitElement or lit-html.
Svelte Svelte is an efficient reactive library, oriented towards performance. It brings some innovation, particularly with the drop of the virtual DOM. Its community development model is very interesting, with an impressive list of involved people.
And many more!
Hybrids, Slim.JS, Bosonic, Riot.JS, Smart HTML Elements... And yes, I'm missing some, in particular the ones that do not yet exist.
Choosing one framework or the other can be matter of preferences, skills or actual framework capabilities. But we should not forget a non negligible aspect, which is the sustainability of the technology:
Will the technology remain compatible over time?
How will it adapt to the new standards?
Who is behind it? Is it another open source project that will loose attention& love in a foreseeable future?
What is the community?
These are fair questions that we need to answer before we choose a technology for business purposes. Of course, your mileage may vary.