Chapter 11: Siteless UIs
In the previous chapter, we saw how the SPA composition pattern can be used to combine multiple SPAs into one unified application. While this pattern is attractive due to a variety of business and technical factors, we've also drilled deep enough to observe its challenges.
A pattern that directly builds on top of the SPA composition is the creation of siteless UIs. In this pattern, analogies and ideas from serverless functions are applied to frontends. In the end, we'll get runtime-driven micro frontends, which offer a lot of advantages and flexibility.
In this chapter, we'll close our tour of the different micro frontend patterns by taking a deep dive into next-generation micro frontends with the siteless UI pattern.
We'll structure this chapter as follows:
- Basics of siteless UIs
- Advantages and disadvantages
- Comparing with serverless
- Creating a runtime
- Writing modules
This should help us to understand when the siteless UI pattern makes sense and how we can implement it practically.
Technical requirements
To follow the sample implementation of this chapter, you need knowledge of Node.js, webpack, and the DOM. The code can be found on GitHub – spread across multiple repositories. The URLs are listed before going into each part.
The Code in Action video for this chapter can be found here: https://bit.ly/2SStQeM
The basics of siteless UIs
The siteless UI pattern builds directly on top of the SPA composition. It leverages a plugin architecture, which has been known for its flexibility without the loss of consistency.
Like with the previous chapters, we will also introduce this pattern using our standard structure. We will start off with a closer look at its architecture, before we try to come up with a simple sample implementation. Finally, we will discuss potential enhancements of the sample.
Let's start with a closer look at its architecture.
The architecture
One of the issues with the SPA composition pattern was that the app shell was a bit too constrained, in the sense that the app shell most likely knows where all micro frontends reside and how to integrate them.
In contrast, in an evolved version the app shell itself would not know about the micro frontends. Instead, it would rely on some other part to identify which micro frontends to resolve and integrate. The integration itself would be left to the micro frontends.
The following diagram illustrates the core architecture principles of the siteless UI pattern:
Figure 11.1 – Siteless UIs are built using the combination of a runtime with a micro frontend feed
In Figure 11.1, we also see the similarities to the SPA composition. What makes the siteless UI pattern unique is that the feed should be served from a different server than the data sources of the individual micro frontends. Furthermore, instead of being fully autonomous, micro frontends are rather modules that are still run within the execution context of the app shell.
To provide these kinds of modules, we can use a plugin architecture. One way of introducing a plugin architecture is to define two things:
- A general life cycle of the modules exposed via functions
- An API to be handed over to the plugins – accessible during their life cycle
In the simplest approach, we reduce the life cycle to a single step: the setup of a plugin. In this case, each module exposes a single function, for example, called setup. The app shell can now call these setup functions providing an API object as an argument to the function. The content of the object is left to the app shell owner. It makes sense to provide dedicated methods here, which allow the registration of components for specific parts of the UI such as a navigation or content area.
Using the exports of the scripts is a clear change in direction when compared to the SPA composition beforehand. Instead of using global variables, we now work exclusively in modules. While global variables may still be used somewhere under the hood, for instance, to get some singleton behavior or share some dependencies, we should never see or interact with these global variables directly.
Let's try to experience the siteless UI pattern by modifying the sample from the previous chapter.
Sample implementation
To illustrate the workings of this pattern in the most extreme setup, we'll distribute all parts of the solution. This means we'll end up with five repositories:
- One repository for the feed service providing the feed
- One repository for the app shell orchestrating the micro frontends
- One repository for the "tax" micro frontend providing a tax-deductible information component for the balance table (or other interested micro frontends)
- One repository for the "settings" micro frontend providing the user settings page
- One repository for the "balance" micro frontend providing the dashboard page with the balance sheet
In the following sections, we'll cover each repository. We will start with the feed server.
Feed server
The code for this section can be found at https://github.com/ArtOfMicrofrontends/11-service-feed.
The feed server can be implemented as a simple Node.js application using Express. The core part of the server consists of three different route handlers, which can be defined like this:
app.get("/modules", getLatestModules());
app.post("/modules", publishModule(host));
app.get("/files(/@:org)?/:name/:version/:file?",
getFiles());
The first route handles all the requests for retrieving the available modules. It will respond with the latest modules.
Even though our feed server may store multiple versions for each micro frontend, we'll only serve the latest one in the sample. With further APIs or efforts, this enables quick rollback or A/B testing scenarios, as follows:
exports.getLatestModules = () => async (_, res) => {
const modules = await getAllModulesFromDatabase();
const unique = modules.reduce((prev, curr) => {
prev[curr.meta.name] = curr.meta;
return prev;
}, {});
const items = Object.keys(unique).map((name) =>
unique[name]);
return res.json(items);
};
There are multiple ways of publishing modules. One way could be to couple to some other service, for example, providing a private npm registry.
A more integrated way would be to allow the upload using a form with a file entry. An implementation of this approach is as follows:
exports.publishModule = (rootUrl) => (req, res) => {
const bb = req.busboy;
req.pipe(bb);
bb.on("file", async (_, file) => {
try {
const content = await getModuleContent(file,
rootUrl);
await setModuleData(content);
res.sendStatus(200);
} catch (err) {
res.sendStatus(400);
}
});
};
The getModuleContent function is used to extract the content from the provided file. In our example, we'll use an npm package, which is just a tgz file. We'll discuss later in the Publishing modules section why this might be a good choice.
Finally, we need a way to retrieve the files. Ideally, this is not part of this service. However, in this ideal scenario, we would need another service – most likely a kind of Content Delivery Network (CDN) with access to really fast storage. Therefore, we'll just provide an endpoint that is capable of serving any kind of demanded file – if it was part of a previously uploaded micro frontend.
Now, we will discuss the function to create the request handler for these files. The thing we need to be most careful about is the potential naming of the packages. Since npm packages can be scoped, a single path separator may appear in the URL part, representing the package name. We need to apply some logic to correctly identify this part, which is shown in the following code:
exports.getFiles = () => async (req, res) => {
const { name, version, org, file } = req.params;
const id = org ? `@${org}/${name}` : name;
const moduleData = await getModuleData(id, version);
if (moduleData && file) {
const path = path.join(moduleData.root, file);
const content = Buffer.from(moduleData.files[path]);
if (content) {
const tenYears = 24 * 60 * 60 * 365 * 10;
return res
.header("Cache-Control", `public, max-
age=${tenYears}`)
.contentType(mime.lookup(file) ||
"application/octet-stream")
.status(200)
.send(content);
}
}
res.status(404).send("File not found!");
};
With these handlers implemented, we can start the server and see whether everything works fine. We'll keep it running for now to test the integration with the other pieces. Let's implement the app shell before we continue with the individual micro frontends.
App shell
The code for this section can be found at https://github.com/ArtOfMicrofrontends/11-app-shell.
At the heart of the app shell is a function to retrieve the existing modules. This looks quite similar to the script loading from the SPA composition sample (Chapter 10, SPA Composition).
However, in contrast to the sample done in Chapter 10, SPA Composition, we are not loading a static file. Also, we need to do a bit more work than beforehand. Unlike the SPA composition pattern, where each micro frontend reaches out to some functionality, we need to provide a set of APIs in a well-defined interface.
In the following example, we assume that each micro frontend will be exposed as a global variable yielding its exports. In these exports, we'll look for a setup function. The function is finally called by the app shell providing the API object for the micro frontend to use, as follows:
const feedUrl = "http://localhost:9000/modules";
fetch(feedUrl).then(res => res.json()).then((modules) =>
modules.forEach((moduleData) => {
const script = document.createElement("script");
script.src = moduleData.link;
script.onload = () => {
const nsName = moduleData.name;
const { setup } = window[nsName] || {};
if (typeof setup === "function") {
const api = createApi(nsName);
setup(api);
}
};
document.body.appendChild(script);
})
);
Keep in mind that the URL of the feed server should be adapted to our case. For running the sample locally, the given URL may be adequate. However, in general, we should make this configurable, allowing the use of a different URL for our production environment.
We should create an API object per micro frontend. The advantage of such an approach is to avoid potential conflicts and manipulations between the different micro frontends.
For this sample we'll provide a simple yet effective API, pretty much providing the same functionality as before.
One advantage of creating an API object per micro frontend is that we can immediately recognize that we don't have to specify the name of the micro frontend in all the APIs. This can be captured when creating the APIs. Since we do that per micro frontend, we can also capture micro frontend-specific information.
The general outline for the API creation can be summarized as follows:
function createApi(nsName) {
return {
registerPage(route, lifecycle) {
// ...
},
registerExtension(id, lifecycle) {
// ...
},
on(eventName, handler) {
// ...
},
off(eventName, handler) {
// ...
},
renderExtension(container, id, props) {
// ...
},
};
}
For instance, the registerPage API could use a combination of the registerComponent and activateOnUrlChange functions, which we've seen in the sample for the SPA composition.
Applied with the captured information, the implementation may be as simple as this:
registerComponent(nsName, route, lifecycle);
activateOnUrlChange(
nsName,
route,
(location) => location.pathname === route
);
We don't need to change the build process. Like before, we are free to choose whatever tooling we want to. In this case, we keep the Parcel bundler for building and development.
With the app shell up and running, we can focus on the different micro frontends. We'll start with the micro frontend concerned with tax information.
Micro frontend – Tax
The code for this section can be found at https://github.com/ArtOfMicrofrontends/11-frontend-tax.
The tax micro frontend does not require many changes. The Info component itself can still be provided as a Svelte component. There are no changes needed to this component.
The root module of the micro frontend requires some changes. It now reads as follows:
let Info = undefined;
export function setup(api) {
api.registerExtension("balance-info", {
bootstrap: () =>
import("./Info.svelte").then((content) => {
Info = content.default;
}),
mount: (target, props) =>
new Info({
target,
props,
}),
unmount: (_, info) => info.$destroy(),
});
}
We've transported the life cycle defined earlier in the app shell into the new way. This way leverages an exported setup function that receives an object containing the app shell's API.
What we see is that the micro frontend's name does not need to be mentioned when we call the registerExtension function. What we changed here is to use a more appropriate name. We'll see that the loose coupling demands giving careful names to the extension slots, instead of directly obtaining components via the names of their micro frontends.
Let's explore the settings micro frontend to review more of the changes that are needed to be applied.
Micro frontend – Settings
The code for this section can be found at https://github.com/ArtOfMicrofrontends/11-frontend-settings.
Again, the major changes are within the root module. But we need to be careful with the package.json file too. Since we use the information stored in this file on our feed server, we need to have accurate information in there.
Previously, we did not keep the meta information regarding the main field accurate. However, this should reflect where build artifact is placed. In our case, we choose dist/index.js. To fully accommodate it, we need to also modify the configuration for webpack.
In the case of the settings micro frontend, the webpack configuration reads as follows:
const { name } = require("./package.json");
module.exports = {
entry: {
[name]: "./src/index.js",
},
output: {
filename: "index.js",
library: name,
path: __dirname + "/dist",
},
// ... as beforehand
};
We reuse the information from package.json to create a consistent and reusable configuration file. The output filename is now fixed to index.js. Furthermore, we use the library target with the same name. This follows the convention established earlier in the app shell.
Consequently, the build process remained very similar but handles the exports via a global variable. The necessary wrapper is introduced by webpack.
With these changes in mind, let's look at the most important micro frontend – hosting the balance sheet.
Micro frontend – Balance
The code for this section can be found at https://github.com/ArtOfMicrofrontends/11-frontend-balance.
The balance micro frontend also needs to have its metadata, webpack configuration, and root module modified. Additionally, we also need to apply the new way of rendering the extension components registered in the app shell.
What we'll do is to provide the renderExtension API to the BalanceSheet component. In the root module, this looks as follows:
export function setup(api) {
api.registerPage("/", {
mount: (target) => render(<BalanceSheet
onRender={api.renderExtension} />, target),
// ... as beforehand
});
}
This way, the component can also use the renderExtension API. In our case, we could just provide the onRender prop to the interested children, who may provide that prop to their children again.
Important note
In React, there are two preferred ways of passing in values. One is via props, while the other is via context. Usually, we should prefer props. However, under certain circumstances a context may be even better. One situation where contexts shine is when we otherwise would see a phenomenon known as "prop drilling." This appears when we need to pass on the same prop multiple levels down just to give a fairly distant child element a prop.
Now that we transformed all these micro frontends, it's time to publish them on the feed server. This means that first, we need to build and pack them as follows:
npm run build
npm pack
For the actual upload, we can use a graphical tool such as Postman or a command-line utility such as cURL.
As an example, the balance micro frontend in version 1.0.0 is published with the following command:
curl -F 'file=@./balance-1.0.0.tgz' http://localhost:9000/modules
After all the micro frontends have been published, the feed server's response is no longer empty. We should see a response similar to the following snippet:
[
{
"name": "balance",
"version": "1.0.0",
"link": "http://localhost:9000/files/balance/
1.0.0/index.js"
},
{
"name":"tax",
"version": "1.0.0",
"link": "http://localhost:9000/files/tax/
1.0.0/index.js"
},
{
"name": "settings",
"version": "1.0.0",
"link": "http://localhost:9000/files/settings/
1.0.0/index.js"
}
]
So far, so good. As usual, the question now is: what could we have done better?
Potential enhancements
Even though the solution already works quite fine, it is only usable within the boundaries given by this particular sample. One reason for this is that there is almost no error handling. One thing that will happen when such an application is released to a larger audience is that problems will occur – problems we've never thought of. HTTP responses will be cut, requests will fail, and browsers that are either outdated or have been modified by company policies or installed extensions will interfere with the site. We need to be prepared and handle such unexpected behavior gracefully.
Another thing that becomes tedious is the lack of dedicated tooling. While it's certainly appreciated to be able to decide what tooling to use per micro frontend, we still want to have some things figured out. One example is the upload to the feed server. Using cURL may be an appropriate solution on macOS and Linux, but it's not ideal on Windows.
Furthermore, with the current implementation, we cannot see the bugs until a micro frontend is published. It is like working in the dark. Granted, this was the situation with the SPA composition sample too, but it's definitely one of the first things that should be changed.
Another thing to consider is that the shown implementation of the feed server is wide open. There is no restriction to stop uploads of files that are too large or come from an untrusted source. Also, existing uploads can just be overwritten – which is a huge problem with respect to the long caching that is desired.
Certainly, while the sample implementation leaves many things to desire, the general direction is great. Compared to the sample implementation of the SPA composition, the loose coupling alone makes the solution much more resilient. Nevertheless, to give it the final touches, a lot more is needed. Later in this chapter, we'll introduce a framework to handle these missing pieces for us.
For now, let's look at the general advantages and disadvantages of this pattern.
Advantages and disadvantages
Like with the other patterns, there are also clear reasons to go for this style or to avoid it. Primarily, siteless UIs will be used in highly interactive SPAs. As such, many of the advantages and disadvantages of the SPA composition are shared. However, due to the focus on developer experience and loose coupling, the development of individual modules is much simpler. The drawback is that the app shell development is much more complex. This is a standard tradeoff – a bit of complexity for all teams is exchanged for a lot more complexity for a single team.
The greatest disadvantage of this pattern is the implied – and strong – dependency of the modules to the API provided by the app shell. If we just change one of the APIs, we might crash all modules using that API. Even worse, we might not even recognize this problem until we release the updated app shell. As the modules are deployed independently, the whole system only comes together at runtime. At compile time, such issues are not easy to spot and will usually be missed.
You may argue that most drawbacks are less related to the siteless UI pattern and more of an issue with loose coupling in general. While this is true, since the pattern embraces loose coupling, all of these challenges can now be found in siteless UI implementations too. On the other hand, we'll also find all the advantages that come with loose coupling.
Potentially, the greatest advantage of the siteless UI pattern is that it pretty much guarantees a consistent application out of the box. By providing an API to access essential app functionality, all modules need to go through the same interface. Naturally, the same patterns and practices are already fully determined at this boundary. The UX is formed around the layouts, which are then communicated properly via the API. Here, this architectural style really ties all micro frontends together without crippling their freedom too much.
While big tech companies such as Microsoft use siteless UIs in one or the other form already, the pattern also appeals to more classical companies with a drive for digital transformation. One example of this is ZEISS, which used the pattern to establish its new customer-facing portal. We'll also discuss real-world siteless UI implementations in greater detail later (see Chapter 16, Case Studies).
The approach that is introduced by the siteless UI pattern on the frontend is quite similar to the serverless function architecture in the backend. To fully understand why these two approaches are similar and what advantages and disadvantages they may share, it makes sense to compare them in detail.
Comparing with serverless
After microservices were established on the backend, a new kind of architecture was introduced that became popular as serverless or Function as a Service (FaaS). In a nutshell, this architecture reduced backend services to single functions, where all the essentials are handled by an integrated runtime.
In the beginning, serverless was mainly a selling point for cloud providers. They advocated the new pattern with less dedicated costs. After all, since these functions use a shared and provided runtime, they are not required to run in custom containers that need dedicated resources. Instead, they can just sit idle and wait for a request – being invoked only when required. The runtime would be able to serve many different functions – from many different tenants.
In the following sections, we'll focus our comparison on two major aspects: how local development works and how modules are published. We'll start with the setup for local development.
Developing locally
Almost all FaaS solutions can be developed using a standard IDE – even though many offer dedicated online IDEs. Sometimes, cloud providers offer a direct way of manipulating the code for a serverless function. For instance, Microsoft's Azure was one of the first users to directly integrate the Monaco editor, which forms the basis of the popular Visual Studio Code text editor.
One of the major principles of a serverless project is that local development is not only possible but is as simple as development for a standard project. Thus, developers should be able to clone FaaS projects to build, debug, and publish them from their local machine.
With siteless UIs, we want to be able to provide the same experience. A new developer has to be able to clone the code of a single micro frontend and start a local debugging session. It should not be necessary to know any URLs or special tricks to inject the module into an instance running in a special development environment. Instead, the whole experience has to be as local as possible.
By using an emulator package, this is possible. The emulator is usually just a special development build of the runtime provided within the app shell. Since it runs the same code, it will work just like the original. The downside of this approach is that the emulator will require some installation. While the npm infrastructure helps us here, an installation also assumes that a specific version is picked. Consequently, the likelihood of dealing with an outdated version of the emulator is quite high.
Using outdated versions of the emulator does not sound like a problem at first. There are, however, some immediate issues spawning from an outdated installation. First, the functionality may have changed, thus giving us wrong typing information and leading to runtime errors later. Second, the design that we see on the screen may have changed too, which may lead to design inconsistencies when released.
A fix for most problems is to ensure that proper end-to-end testing is done after deployment. Also, insisting on doing a more extensive integration check is a part of the solution. In general, none of these should be new things. Thoughtful quality assurance and detailed validation of acceptance criteria are integral parts of the development process in many projects.
In the end, most checks can be done when actually publishing the modules anyway.
Publishing modules
Every FaaS platform requires a way to quickly have existing functions updated or new functions added. While microservices leverage container formats such as Docker, FaaS usually leverages simple archive formats such as tar files.
For micro frontends, the situation is similar. Backend-driven micro frontends are usually delivered in container formats – but even client-side composed variants may be released that way. For siteless UIs, a simple archive format is sufficient. A popular choice may be a zipped tarball using the tgz extension.
There are multiple advantages to using tgz files as the package format. The most important point is that the format is already produced and used by the npm tool itself. Being compliant with the most important development tooling is huge with respect to developer productivity. Instead of relying on custom tooling, standard applications can be reused.
The npm package format also gives us a predefined location for metadata: the package.json file. This file also helps us to get some information about the files contained in the package. For instance, the value of the main field tells us the location of the entry module representing the package.
While the FaaS offering of a cloud provider comes with an integrated way of accepting new functions, in a custom siteless UI solution, we need to provide a service to handle that. Usually, this responsibility falls to the feed server.
Important note
An open source implementation of a feed server is the Piral Feed Service. The available source code allows publishing and provisioning modules provided in an npm package. A cloud version of the service exists as a free community edition, as well as a commercial enterprise offering. These versions have more features such as dynamic module provisioning. More information can be found at https://www.piral.cloud/.
The feed server is therefore a core infrastructure piece that provides a way of writing micro frontends without having to take care of the core infrastructure such as a deployment target. If taken from an existing SaaS offering, we can build a frontend solution that does not require any infrastructure at all – as everything can be either hosted on some static storage or provided via a third-party cloud service.
All this makes siteless UIs quite similar to serverless functions – just working at the frontend level instead of the backend. As we saw, the most important piece in this construct is a runtime. Let's explore in a bit more depth what needs to be considered when implementing it.
Creating a runtime
We've already seen that a runtime forms the centerpiece of a siteless UI implementation. While the runtime forms as an orchestrator when released and running in production, it also provides an emulator to allow local development of new modules.
This way, things such as automatic provisioning, caching rules, and runtime optimizations are all available in production – but they don't reduce developer efficiency during development.
In order to focus on the decisions that matter for our runtime, we should pick an established framework to provide the technical basis. One possible choice is Piral.
Important note
Coming up with a full siteless UI implementation is difficult. It not only requires a model for the app shell that emphasizes local development, but it also requires that the feed service and micro frontend packaging are defined and implemented while adding a custom API with reliability for micro frontends. A quick way around this is the Piral framework, which essentially is a tool for creating plugin-based UIs, thus providing everything needed for a siteless UI implementation.
In the following sections, we will look into the creation and deployment of an app shell with Piral. We start by building a runtime, before we actually deploy it.
Building a runtime with Piral
Like many other frameworks, Piral comes with many templates, boilerplate generators, and tutorials to get started quickly. We will not use the standard template, and instead will start by creating a new project from scratch.
The first command is to create a new package.json file using the npm command-line tool:
npm init -y
Then we can install the dependencies. In this case, we'll use the piral package and the piral-lazy plugin to represent the runtime, while piral-cli and the piral-cli-webpack package are used to actually build it.
The commands to install these dependencies are as follows:
npm i piral piral-lazy --save
npm i piral-cli piral-cli-webpack --save-dev
The app shell is transported in the form of an HTML file to the client. To tell the Piral CLI where the HTML file sits, we need to change package.json. We'll add this:
{
... // previous properties
"app": "src/index.html"
}
The HTML file may look as simple and elementary as this:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>My Siteless UI App</title>
</head>
<body>
<div id="app"></div>
<script src="./index.jsx"></script>
</body>
</html>
Besides standard HTML templating, the reference to the loader script is placed. This is used by the tooling to define the entry point of the bundler. We may also directly reference TypeScript files here as the HTML is only used to identify the sources. The sources will be replaced with their generated filenames in the build artifacts.
The loader script can then be written with a simple structure in mind, as follows:
import { renderInstance } from 'piral';
import { createLazyApi } from 'piral-lazy';
import { createCustomApi } from './api';
import { errors, layout } from './components';
const feedUrl = 'https://feed.piral.cloud/api/v1/
pilet/<feed-name>';
function requestPilets() {
return fetch(feedUrl)
.then(res => res.json())
.then(res => res.items);
}
renderInstance({
errors,
layout,
requestPilets,
plugins: [createCustomApi(), createLazyApi()],
});
In Piral's terminology, the modules are called pilets. In the loader, we need to give Piral a function that is able to connect to a feed server responding with a list of pilets. The function for specifying this is called requestPilets. In this example, we use the official Piral Feed Service to host the pilets. Make sure to replace the feed-name placeholder with the name of your feed.
The integration of the piral-lazy plugin package was done by adding the result of calling the createLazyApi setup function to the provided plugins. The errors and layout objects are filled with components to define the display elements for common layout and error parts of the UI.
The api module could be defined like this:
export function createCustomApi() {
return context => ({
myApiFn() {
console.log('Hello from the API!');
},
});
}
This would add a myApiFn function to the API available in the modules. At this time, we can use the Piral CLI to bundle and deploy our runtime.
Deploying a runtime with Piral
Building an app shell is already integrated in the Piral CLI. The build command automatically processes the package.json file of the current folder and processes the HTML file in there.
All we need to do is run the command, for example, via the npx task runner, as follows:
npx piral build
This will result in two artifacts. One is a dist/release folder that contains files, which can be uploaded to some static storage. This is the production build of our app shell. The dist/emulator folder only contains a tgz file. This is the emulator bundled together in an npm package, which could now be published on the official registry or some private npm registry.
Using GitHub as a basis for our runtime, we can also leverage GitHub pages for the simplified hosting of static websites. The simplest way to follow the right steps is to install the gh-pages package as follows:
npx gh-pages -d dist/release
This will take all the files from the dist/release folder and put them in the root directory of the gh-pages branch. Usually, this is an orphan branch, which means a branch that is not based on some other branch and containing its own history of changes.
Pushing this branch leads to a new site available at https://<username>.github.io/<project>, where username represents your GitHub username and project represents the name of the repository. The website should be live within seconds.
Afterward, we can publish the npm package representing the emulator. The easiest way is to use the npm command-line utility as follows:
npm publish dist/release/<package-name>.<package-version>.tgz
Now that we have a runtime that is not only live and online but also available in the form of an emulator, it's time to write some modules for it.
Writing modules
We've already heard that a module for an app shell created with Piral is called a pilet. Pilets are developed like most frontend applications – with the small exception that pilets are not self-contained applications, but closer to independent libraries.
If we want to start a new pilet, we have two options: we can use the integrated tooling to scaffold a new project with the right setup or start from scratch as we did with the app shell. When we have published the emulator, we can scaffold a new project from the command line:
npm init pilet --source <package-name> --bundler webpack --registry https://registry.npmjs.org/ --defaults
This will initialize a new npm project with a package.json file representing a pilet. The pilet will be targeted at the previously published emulator package. For bundling purposes, we use again webpack. If a private npm registry was used for publishing the emulator, the URL in the command needs to be adjusted too.
Once we have scaffolded a new pilet, we can start development right away. We'll continue our investigation by first going into details on the life cycle of a pilet, before we see how framework-agnostic components can be implemented in such a setup.
Looking at a pilet's life cycle
When we discuss the life cycle of a pilet, we need to consider two different kinds of life cycles:
- The software development lifecycle of a micro frontend – from initial creation to maintenance efforts to phasing out
- The pilet's functional life cycle – from loading to installation to uninstallation
Let's try to cover both a bit here, with the focus being on the latter to fully understand how a pilet works.
We already scaffolded the pilet (in the previous section). Once this has been completed, we can start the development of our desired functionality. To start the debugging process, we can use the Piral CLI to start a development server with live reloading as follows:
npx pilet debug
At some point, our micro frontend will be feature complete for a first release. Now, we should first try to build it:
npx pilet build
Alternatively, if we have already a feed server running somewhere, we can also publish it directly. This works against a created npm package or by doing everything in one command:
npx pilet publish --fresh –api-key <your-api-key> --url https://feed.piral.cloud/api/v1/pilet/<feed-name>
As target feed, we choose the same feed that was used as the source for all the pilets within our final app shell.
Updates to this micro frontend are developed and released with the same three commands – we first debug and fix the issue, then we try to build. If everything goes well, we can publish the updated pilet. The only thing to make sure of is to change the version within package.json. Just like normal npm packages, we can publish every pilet just once per version. One of the reasons for this is to ensure that pilets can be cached indefinitely – which makes them really efficient frontend resources.
To be efficient, we should leave the actual publish steps to a CI/CD pipeline. Since we used GitHub for the app shell, we could also host this pilet in a GitHub repository. Therefore, using GitHub Actions is a straightforward way to establish a pipeline quickly.
The .github/workflows/publish.yml file of the pilet uses publish-pilet-action to leverage the Piral CLI. The API key for publishing is made available through GitHub secrets as follows:
name: CI
on:
push:
branches:
- master
jobs:
publish-pilet:
name: Build and Deploy
runs-on: [ubuntu-16.04]
steps:
- uses: actions/checkout@master
- name: Publish Pilet
uses: smapiot/publish-pilet-action@v2
with:
feed: <feed-name>
api-key: ${{ secrets.apiKey }}
Now, let's say the pilet was published successfully. What happens if a user accesses the app shell? Like beforehand, the feed server is called when the loader script initialized. In contrast, however, the response will not be empty but contain the published pilet.
The response from the feed server may now look similar to this:
{
"items": [
{
"name": "<pilet-name>",
"version": "1.0.0",
"link": "https://assets.piral.io/pilets/<feed>
/mario5-sample-pilet/1.2.0/index.js"
}
]
}
This tells the app shell that there is a single micro frontend that should be loaded from the URL mentioned in the link property.
Once the script is evaluated, the Piral framework will look for a special function that was exported from the script: setup. This function is needed for integration purposes. It will be called from Piral with the API object as the only argument.
Piral knows three phases for each micro frontend:
- Evaluation (the micro frontend is loaded).
- Setup (the micro frontend is integrated).
- Teardown (the micro frontend is removed).
While the first phase is implicit, the second phase is required for a script to be recognized as a micro frontend. If a script does not export a setup function, it cannot be integrated further. On the other hand, a teardown function is optional and not really needed.
One of the reasons why a teardown function may be useful is to clean up some resources that may cause conflicts if the setup function is run twice. Running potentially the same setup function again may only appear during development, or the app shell must have been created in a way that allows live updates of pilets.
Now it's time to actually create and use components in our micro frontend solution.
Implementing framework-agnostic components
The index.jsx file of a pilet starts like this:
export function setup(api) {
// ...
}
If we want to register a new page, we can use the registerPage function exposed by the API. This function expects two arguments – the path that triggers the navigation and the component to show as content. This is as follows:
export function setup(api) {
api.registerPage('/example-page', PageComponent);
}
The component itself can be defined inline or referenced from some other module. Ideally, we use some kind of lazy loading to only load the code for the component when it should be rendered.
With React, such a lazy loading mechanism is quite straightforward. In this case, we could define it like this:
import * as React from 'react';
const PageComponent = React.lazy(() => import('./Page'));
Since Piral has first-class support for React, there is nothing else to do in this case. It just works. But what about components coming from other frameworks, for instance, Svelte?
Let's pretend we've already configured webpack to process Svelte modules and that we've already created PageComponent in Svelte:
import PageComponent from './Page.svelte';
The registration of a component coming from Svelte directly is not possible. Instead, we need to wrap it using a generic life cycle:
export function setup(api) {
api.registerPage('/example-page', {
type: 'html',
component: {
mount(container, data) {
container.$svelte = new PageComponent({
target: container,
props: {...data},
});
},
update(container, data) {
Object.keys(data).forEach((key) => {
container.$svelte[key] = data[key];
});
},
unmount(container) {
container.$svelte.$destroy();
container.innerHTML = '';
},
},
});
}
This defines the whole DOM life cycle for the component. Since the code is quite lengthy, it may make sense to extract that into a dedicated function. Luckily, there is already a Piral plugin that does that – and can be also used directly from a pilet.
Installing piral-svelte as a dependency in the pilet makes the following code possible:
import { fromSvelte } from 'piral-svelte/convert';
import PageComponent from './Page.svelte';
export function setup(api) {
api.registerPage('/example-page',
fromSvelte(PageComponent));
}
Likewise, other frameworks can be either integrated simply by using an existing plugin or by building upon the generic HTML component with the explicit life cycle definition.
Summary
In this chapter, you learned how to create appealing SPAs using individual plugins, which are merged into a single coherent web application. In contrast to the classic plugin architecture, these modules may get privileges and responsibilities that are on the application level.
As with the SPA composition before, you've seen that user interaction is meant to be quite high, but unlike SPA composition, the user experience and developer experience are supposed to be smooth. While the internal complexity and tool reliance has increased, the major drawback is the dependency of the modules to the API defined in the app shell.
In the upcoming chapters, we'll see how we can efficiently deal with updates to the app shell. We will see that governance and design awareness are required to establish a common foundation.
In the next chapter, we will start the journey of onboarding everyone – not only the developers – with a preparation round involving the major stakeholders. We'll discuss how everyone can be made aware of the technical principles, leading to improved expectations and more clearly defined requirements.
