piral-update
    TypeScript icon, indicating that this package has built-in type declarations

    0.14.9 • Public • Published

    Piral Logo

    Piral Update · GitHub License npm version tested with jest Gitter Chat

    This is a plugin that only has a peer dependency to piral-core. What piral-update brings to the table is the possibility of automatically updating pilets (or prevent such an automated update).

    By default, these API extensions are not integrated in piral, so you'd need to add them to your Piral instance.

    Why and When

    By default, Piral does not update your pilets at runtime. As such a user that wants to get an updated pilet will always need to refresh the application (e.g., by pressing F5). There is a reason for this out of the box behavior: Automatic updates may have unintended side-effects and are therefore problematic.

    Example scenario: A pilet comes with a form where the user can enter information and submit it. If a user is already half-way through the form (entering a lot of information) and an update for this pilet would come up, the pilet would be unloaded and loaded again with the updated content. This process would destroy the form and all the information already entered by the user. Sure, there are ways to "store and restore" the form's data, however, quite often these techniques are not used (as the given scenario is not anticipated).

    piral-update comes with extensions to the pilet API that allow communicating update behavior from the pilets to the app shell. If you think these are sufficient and provide a good safety net then you can make your application more dynamic using this plugin. It's quite cool, but in most cases not really needed.

    Documentation

    The following functions are brought to the Pilet API.

    canUpdate

    Changes the current updatability. Takes specific constants, either allow, or block.

    Usage

    ::: summary: For pilet authors

    You can use the canUpdate function from the Pilet API to define if the current pilet can be updated or not.

    Example use:

    import { PiletApi } from '<name-of-piral-instance>';
    
    export function setup(piral: PiletApi) {
      piral.registerPage('/test', () => {
        const [name, setName] = useState('');
        useEffect(() => {
          if (name) {
            piral.canUpdate('block');
            return () => piral.canUpdate('allow');
          } else {
            return () => {};
          }
        }, [name]);
    
        return <input value={name} onChange={e => setName(e.target.value)} />;
      });
    }

    Right now the possible values are:

    • block, updates for this pilet should be blocked
    • allow, updates for this pilet are possible (components may be replaced dynamically)
    • ask, user needs to confirm to allow an update - otherwise it will be blocked

    :::

    ::: summary: For Piral instance developers

    The provided library only brings API extensions for pilets to a Piral instance.

    For the setup of the library itself you'll need to import createUpdateApi from the piral-update package.

    import { createUpdateApi } from 'piral-update';

    The integration looks like:

    const instance = createInstance({
      // important part
      plugins: [createUpdateApi({
        listen(notify) {
          // check every 30 seconds
          setInterval(() => {
            // notify will automatically compare the given pilets with the available ones
            fetch(myFeed).then(res => res.json()).then(pilets => notify(pilets));
          }, 30 * 1000);
        }
      })],
      // ...
    });

    Additionally, you'll need to define an UpdateDialog component. This component can be as simple as:

    const layout = {
      UpdateDialog: ({ onApprove, onReject }) => (
        <div>
          <p>
            <b>New update ready!</b>
          </p>
          <button onClick={onReject}>Skip</button>
          <button onClick={onApprove}>Install</button>
        </div>
      ),
      // ...
    };

    To integrate the full update dialog you'll need to mention it in your page layout.

    import { UpdateDialog } from "piral-update";
    
    const layout = {
      Layout: ({ children }) => (
        <div>
          <UpdateDialog />
          <div className="container">{children}</div>
        </div>
      ),
      // ...
    };

    The most important strategies are already available in helpers.

    If you want to check periodically you can use the checkPeriodically helper factory:

    import { createUpdateApi, checkPeriodically } from 'piral-update';
    
    const instance = createInstance({
      // important part
      plugins: [createUpdateApi({
        listen: checkPeriodically({
          period: 30 * 1000,
        }),
      })],
      // ...
    });

    If you can use a WebSocket connection we recommend using the checkWebSocket helper factory:

    import { createUpdateApi, checkWebSocket } from 'piral-update';
    
    const instance = createInstance({
      // important part
      plugins: [createUpdateApi({
        listen: checkWebSocket({
          url: 'ws://<insert-ws-host-here>/api/pilets',
          available: (data) => JSON.parse(data).type === 'update_available',
        }),
      })],
      // ...
    });

    If you can use Server-Sent Events to detect updates using the checkServerSentEvents helper factory:

    import { createUpdateApi, checkServerSentEvents } from 'piral-update';
    
    const instance = createInstance({
      // important part
      plugins: [createUpdateApi({
        listen: checkServerSentEvents({
          url: 'http://<insert-sse-host-here>/api/pilets',
          name: 'update_available',
        }),
      })],
      // ...
    });

    If you can use a Piral event to check for updates then we recommend the checkPiralEvent helper factory:

    import { createUpdateApi, checkPiralEvent } from 'piral-update';
    
    const instance = createInstance({
      // important part
      plugins: [createUpdateApi({
        listen: checkPiralEvent({
          name: 'check-update',
        }),
      })],
      // ...
    });

    :::

    License

    Piral is released using the MIT license. For more information see the license file.

    Install

    npm i piral-update

    Homepage

    piral.io

    DownloadsWeekly Downloads

    419

    Version

    0.14.9

    License

    MIT

    Unpacked Size

    58.6 kB

    Total Files

    60

    Last publish

    Collaborators

    • florianrappl