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.
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.
The following functions are brought to the Pilet API.
Changes the current updatability. Takes specific constants, either allow
, or block
.
::: 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',
}),
})],
// ...
});
:::
Piral is released using the MIT license. For more information see the license file.