Forem: Dante De Ruwe

How I Set Up Shared Agent Config for Our Team with APM

Dante De Ruwe — Fri, 08 May 2026 00:00:00 +0000

I set up a shared Git repo for our team to maintain reusable AI agent packages: skills, instructions, coding standards, custom agents. We use APM (Agent Package Manager) to distribute them to every project in one command. Think npm, but for agent config.

Four problems I kept running into

If you've been working with AI coding agents (Copilot, Claude, Cursor, Codex), you've run into a few of these.

Configuration drift

You spend time crafting instructions, coding standards, and skills for your project. It works well. Then you start a new project, and you copy-paste it all over. And again. A few months later, you've got a bunch of repos with their own subtly different versions of the same agent configuration. You improve the frontend guidelines in repo A, but repos B through N never get the update. Nobody notices until something breaks.

Tool lock-in

Each AI tool wants its config in a different place. Copilot reads from .github/, .copilot/, or .agents/ depending on where you put your config, Claude wants .claude/, Cursor has .cursor/ and so on. If you want to support multiple tools, or keep your options open, you end up maintaining the same knowledge in multiple formats and keeping all of those in sync.

No source of truth in the repo

One way to avoid tool lock-in is to not commit those tool-specific folders at all. But then a new team member clones a repo and gets zero agent setup. They build their own from scratch, copy files from a colleague, or grab what they can from a shared location. Everyone ends up with a different setup, and nobody knows which one is "right" for that project.

Shared and project-specific config blur together

Skills that apply to every repo live next to skills that only make sense for one project. If you store agent config in your user directory, it follows you to every repo whether it belongs there or not. If you try to share a setup with a teammate, you're handing over a flat pile of files with no indication of what's generic and what's project-specific. Copying setups between repos drags along things that don't belong.

I was dealing with all of these. It was getting out of hand.

Finding the right tool

I wanted a way to manage agent configuration as dependencies: declarative, versioned, and shareable across repos. Two tools stood out.

skills.sh

If you've looked into sharing agent capabilities before, you may have come across skills.sh (or its npx skills add CLI), built by Vercel. It's a solid tool for installing community skills into your project with a single command.

I started there, but ran into its limits. skills.sh focuses on skills¹, which are only one of the primitives you might want to share. I also needed to distribute instructions (coding standards, conventions), custom agent definitions, hooks, and prompt templates.

skills.sh is a good fit if you want to grab a few community skills. I needed something that manages a full stack of agent configuration across teams and projects.

APM: a package manager for agent configuration

APM, or Agent Package Manager , is a tool by Microsoft that does for AI agent setup what npm does for JavaScript dependencies. You declare what agent packages you need in an apm.yml file, run apm install, and it pulls everything in, lockfile included.

APM supports instructions, skills, hooks, agents, prompts, and MCP server configuration as first-class primitives². It also handles transitive dependencies, lockfiles, and deploying to multiple tools at once.

APM is tool-agnostic. It detects what tools your project uses and deploys the right files to the right places. Write your agent config once, deploy it to Copilot, Claude, Cursor, or any other supported tool.

There's no central registry. Packages are Git repos, resolved over SSH or HTTPS. That means private repos work out of the box if you have Git access to them (APM reuses your existing Git credentials³). If you stop using APM, your deployed files still work in their native format. The APM creator's HN post explains the reasoning: each tool vendor governs its own ecosystem, so a cross-tool dependency manager shouldn't introduce yet another walled garden⁴.

Dependencies can point to an entire repo, a subfolder inside a repo, or a single file. You can reference GitHub repos with shorthand (owner/repo), use full HTTPS or SSH URLs for any Git host (GitLab, Bitbucket, Azure DevOps, self-hosted), or point to local paths for monorepo setups². This flexibility is what makes the shared repo pattern work: one Git repo, multiple installable packages as subfolders.

One shared repo, many consuming projects

I took this further. Instead of maintaining agent config per project, I created a central Git repository that acts as a catalog of reusable APM packages.

APM's org packages guide suggests creating separate repos per concern: one for security baselines, one for coding standards. I tried a different approach: one repo with multiple packages as subfolders, connected through internal dependencies. Same composability, less overhead. One repo to manage, one place to review changes. Packages still stay independent and focused.

The structure organizes packages by concern, and each project pulls in what it needs:

agents-repo/
├─ general/ → guidance for ALL projects
├─ development/
│ ├─ _shared/ → shared building blocks (internal dependency)
│ ├─ backend-dotnet/ → .NET-specific guidance
│ └─ frontend-angular/ → Angular-specific guidance

Each folder is its own installable package with its own apm.yml. An Angular frontend project pulls in general and development/frontend-angular. A .NET API project grabs general and development/backend-dotnet.

Why this modularity matters

The packages form a dependency graph.

Both backend-dotnet and frontend-angular declare _shared as a dependency in their own apm.yml. _shared contains things that apply to all development work but not to non-development uses of the agent. Think instructions on how to write commit messages, a skill for addressing PR review comments, conventions around branching and code review. The stack-specific packages build on top of it. backend-dotnet adds .NET conventions like solution structure, API design patterns, unit and integration testing practices, validation steps for builds and formatting. frontend-angular adds things like component architecture guidelines, styling conventions, and its own validation flow for linting and builds.

The underscore-prefixed _shared folder is an internal dependency by convention. Other packages in the repo depend on it, but consuming projects don't reference it. They get it transitively.

The general package sits outside the development/ tree. It holds things that apply to any project, no matter the tech stack: community skills like skill-creator⁵ and grill-me⁶, and connections to tools the whole organization uses. Non-developers like functional analysts can pull in general on its own, without any of the development packages.

For an Angular project, the dependency graph could look like this:

consuming project's apm.yml
├─ general (non-technical guidance, community skills)
└─ development/frontend-angular (or backend-dotnet)
   └─ development/_shared (transitive: shared dev tooling and skills)

A consuming project needs two lines in its apm.yml. APM resolves the rest, and _shared comes along because frontend-angular depends on it.

I update the PR review skill in _shared, and every frontend and backend project picks up the change. I tighten the Angular coding standards, and only Angular projects are affected.

How a project consumes shared packages

In any project repo, you reference the shared packages in your apm.yml. In this example, the shared config lives in a repo called agents:

dependencies:
  apm:
    - git: your-git-host.com/your-org/agents
      path: development/frontend-angular
      ref: main

    - git: your-git-host.com/your-org/agents
      path: general
      ref: main

Then run:

apm install

APM resolves all dependencies, including transitive ones, and deploys the instructions, skills, and hooks into the right tool-specific folders (.github/, .claude/, etc.). You don't need to commit these generated files to source control, because apm install can regenerate them at any time.

Add --target <tool> (e.g. --target claude) to deploy for a specific tool only. Add --update to pull the latest versions of all dependencies before installing. You can combine both:

apm install --target claude --update

Pulling in community-built skills

APM also supports pulling in packages from public GitHub repos:

dependencies:
  apm:
    - anthropics/skills/skills/skill-creator
    - mattpocock/skills/productivity/grill-me

The community around shared skills is growing. You can mix community-built skills with your own organization's standards. Found a good skill on GitHub? Add it as a dependency!

Side note: these two specific skills are fantastic. Anthropic's skill-creator⁵ helps you build, test, and iterate on new skills with evals baked in. Matt Pocock's grill-me⁶ interviews you about a plan or design until the gaps surface. I added both to my default setup and I can't imagine working without them now.

Local overrides with `.apm/`

Some projects have quirks that don't belong in a shared package. For these, you can place project-specific instructions, skills, or hooks in a local .apm/ folder right inside your project repo:

my-project/
├─ apm.yml
├─ apm.lock.yaml
└─ .apm/
   ├─ instructions/
   │ └─ local-conventions.instructions.md
   └─ skills/
       └─ my-project-skill/
           └─ SKILL.md

When you run apm install, APM picks up this local content and deploys it alongside your shared dependencies. No extra config in apm.yml needed.

I'm a bit proud of this one, because this feature started as a feature request I filed on the APM repo. Before v0.8.12, the .apm/ folder in your own project wasn't treated the same way as content from installed packages. You had to use workarounds like apm install ./.apm/skills/skill-name to get local skills deployed. That felt inconsistent. The .apm/ folder is the natural place for project-local APM content, so it should work out of the box.

I filed the issue, another user independently confirmed the gap, and the APM team shipped the fix within two days. That kind of responsiveness from an open-source project is refreshing, and it shows APM is still in active development with a team that listens.

What you get from this setup

DRY, for real. Write your coding standards once. Share them across projects. When you improve a skill or update an instruction, consuming projects get the update on their next apm install --update.

Tool independence. I don't want to commit to a single AI tool while this space evolves this fast. APM lets the same package of instructions and skills target Copilot, Claude, Cursor, or any other supported tool. If you switch tools next month, your agent knowledge comes with you.

Different team members can even prefer different tools. Each person runs apm install, and they get the config deployed for their tool of choice.

Easy updates. Updating is a one-liner: apm install --update. You can also pin to specific branches, tags, or commits for stability. Pin to v1.2 for a production project, or follow main if you want the latest.

Smooth team sharing. A new team member runs apm install and has the same agent setup as the rest of the team. The config lives in a repo, versioned and reviewable in pull requests.

Composability. A consuming project picks the packages it needs. No Angular project inherits .NET conventions. No .NET project pulls in frontend linting instructions.

Supply-chain security. Agent instructions have direct access to your codebase and terminal. That makes them a vector worth scanning. APM ships with apm audit, which checks installed packages for hidden Unicode characters, bidi marks, and prompt-injection payloads. It outputs SARIF, so you can plug it into your existing code scanning pipeline⁷.

CI/CD integration. The lockfile (apm.lock.yaml) pins every dependency to an exact commit SHA, so apm install in a CI pipeline produces the same agent setup as on your local machine. There's also an official GitHub Action if you want to automate installs and audits on every PR.

Offline support. apm pack bundles your resolved dependencies into a portable archive. apm unpack restores them on a machine without Git access. Useful if you work in environments with restricted internet connectivity, or if you want to ship a self-contained agent setup to someone who can't reach your Git host.

Local overrides. Projects with specific quirks can add instructions, skills, or hooks in a local .apm/ folder without touching the shared packages.

Advice if you're doing this too

Keep packages narrow

It's tempting to create one mega-package with all your standards, skills, and hooks bundled together. Resist that. Smaller, composable packages are easier to maintain. They let consuming projects pick up frontend guidance without also inheriting backend conventions they don't need. If two packages share common ground, extract that into a _shared dependency rather than duplicating it.

Only share what's reusable

If guidance applies to one project, keep it local in that project's .apm/ folder. The shared repo is for patterns that apply across projects and teams. Putting single-project quirks in a shared package adds noise for consumers who don't need them, and creates maintenance burden when that project's needs change.

Treat it like code

Use pull requests, reviews, and meaningful commit messages. Your agent configuration shapes how AI tools behave across your entire organization. A bad instruction can propagate to dozens of repos on the next update. Give changes the same review rigor you'd give production code.

Consider not committing generated files

APM's own docs suggest committing the tool-specific folders (.github/, .claude/, .cursor/, etc.)⁸, and there are valid reasons to do so: cloud agents may need config present in the repo, and committed files give contributors instant context before they run apm install.

I chose not to, for now. My reasoning: these files can be regenerated from apm install at any time, committing them repeats content that already lives in the shared packages, and I don't want the repo to prescribe which AI tool developers should use. If the generated config lives in .gitignore, each developer runs apm install and gets the output for their tool.

I'm not 100% sure this is the right call long-term, but it follows a principle I like: if code is generated from source, don't commit the output.

Try it yourself

If you're managing AI agents across multiple projects and you're still copy-pasting instructions between repos, this setup is worth an afternoon of your time.

Install APM: irm https://aka.ms/apm-windows | iex (Windows) or curl -sSL https://aka.ms/apm-unix | sh (Mac/Linux)
Run apm init in a project
Add a dependency and run apm install

The APM docs walk through each step. The org packages guide covers the shared repo pattern in detail.

If you do set this up, I'd be curious to hear how it works for your team.

skills.sh focuses on installing skills (folders with a SKILL.md) from GitHub repos. ↩
APM supports instructions, prompts, agents, skills, hooks, chat modes, and MCP server configuration as first-class primitives. Dependencies can be entire repos, subfolders, or single files from any Git host. See the APM dependencies guide. ↩
APM resolves authentication through environment variables, gh auth login, or your system's Git credential helper. Private repos on GitHub, GitLab, Bitbucket, and Azure DevOps all work. See the APM authentication guide. ↩
From the APM creator's Show HN post: "Why this won't come from plugin vendors: each tool governs its own ecosystem. [...] Nobody governs across tools, resolves cross-plugin dependencies, or gives consumers a lock file for what they actually installed." ↩
skill-creator by Anthropic. Helps you create, test, and optimize skills with built-in evals. ↩
grill-me by Matt Pocock. Stress-tests your plans and designs through relentless questioning. ↩
Marcel Lupo wrote a good DevOps-focused walkthrough of APM that covers the security and CI angles in more detail. ↩
See the "What to commit" section in the APM quick start guide. ↩

How to create a local gitignore file

Dante De Ruwe — Wed, 18 Mar 2026 00:00:00 +0000

Sometimes, you want to experiment and tinker with stuff locally without git tracking your files. Think about experimenting with AI agents, local scripts, or even leaving yourself todo notes in every repo.

In stead of carefully avoiding to stage and commit these files, we can let git ignore them without changing the repo's .gitignore!

Additional gitignore files

Did you know you can create additional gitignore files? These can extend your main gitignore file.

You can let git know it should treat an extra gitignore file with:

git config --local core.excludesfile "<my-gitignore-path>"

This way, you can add your experimental files or folders that you're not ready for the world to see, away from the allseeing eye of git 👀

Keeping your gitignore file local

We don't want this gitignore to be added to the repo! So we'll have to set it up to be local.

We're going to do this as follows:

Create a local gitignore file (call it e.g. .local.gitignore)
Add it to the git config as shown above:
Add a reference to the local gitignore file in the local gitignore file itself

🚀 Terminal oneliners for quick setup

Run this in the root folder of your git repository.

Bash (Linux or Git Bash):

echo ".local.gitignore" &gt; .local.gitignore &amp;&amp; git config --local core.excludesfile "$(pwd)/.local.gitignore"

Powershell (Windows):

Set-Content .local.gitignore ".local.gitignore"; git config --local core.excludesfile "$PWD\.local.gitignore"

Tips

The contents of my local gitignore are mostly as follows:

.local.*
.local/

This ignores all files starting with .local. (such as .local.gitignore itself!), and also ignores a .local folder where you can keep your super secret files with whatever names you wish.

Switching up your Spotify experience with microfrontends and Blazor

Dante De Ruwe — Fri, 07 May 2021 08:03:26 +0000

In my previous article, I talked about creating a Netflix clone using Piral: an open-source framework for creating modular applications. I highly recommend giving that article a quick read first, if you are not yet familiar with microfrontends and/or Piral.

Dante De Ruwe

Mar 18 '21

My experiences creating a Netflix clone using microfrontends

#piral #microfrontends #react #webdev

237

Comments 8

23 min read

Since then, I've been making contributions on GitHub and working closely together with the maintainers of Piral, to provide a helping hand to improve their framework in any way I could.
The main bulk of the improvements was made in their converter for Blazor.

In this article, I will share my experiences creating a microfrontend web app with Blazor and Piral. I'll also give a little behind-the-scenes look at how this was made possible, highlight some of the quirks of using Blazor in a microfrontend solution, and explain how the combination of Piral and Blazor has improved.

Spiralfy: a modular web application
- Overview
- The Spiralfy appshell
- The player: a simple pilet
- The controls: a Blazor pilet!
Dev story: making Blazor work with microfrontends
- Looking back
- What needed improvement, and why?
- What has changed and improved?
Final thoughts

Spiralfy: a modular web application

First of all, let's discuss the demo application that I created to showcase the use of Blazor with Piral: Spiralfy. A clever – or some would say cheesy – play on words between Spotify and Piral, of course. But what does it do?

Overview

For a long time now, I wanted a way to shuffle play my playlists. I'm not talking about shuffling the songs within one playlist, that's something you can obviously already do. The feature I wanted could be described as "swiping through playlists": Spiralfy picks one playlist at random, shuffle playing its songs, and whenever you feel like you want a different vibe, you let Spiralfy pick a new playlist to listen to.

(I got inspired in part by lofi.cafe, where you can switch through curated lofi playlists like they were radio stations. But I wanted the user to be able to use their own Spotify playlists instead.)

The code

"Talk is cheap. Show me the code" ~ Linus Thorvalds

Spiralfy is a modular distributed web application, also known as a microfrontend application. In my previous microfrontend project I decided to make separate GitHub repositories for each and every module; to really demonstrate that these are highly decoupled and autonomous. This time, I chose to bundle all parts into one repository (a monorepo), just because it would be easier to discover and browse all the code at once. You can find the code on git.io/spiralfy

DanteDeRuwe / spiralfy

A different way of using Spotify! Built using a microfrontend approach with Piral, Blazor and React. Read more on https://bit.ly/spiralfy-article

switching up your Spotify experience with microfrontends and Blazor

Made with React , Blazor and Piral

Article

In this DEVCommunity article, I share my experiences creating a microfrontend web app with Blazor and Piral. I also give a little behind-the-scenes look at how this was made possible

About

View on GitHub

For now, Spiralfy exists in 3 parts:

the Piral instance: spiralfy-appshell
the player pilet
the controls pilet

What are these words?
In case you did not read my previous article: a quick summary here. In the Piral framework, pilets are the individual feature modules, also known as microfrontends. Pilets are usually published to a feed service. The Piral instance (aka app shell) will pull all registered pilets from the feed service, and put them where they need to go as defined by the pilets themselves.

The Spiralfy appshell

For the Spiralfy app shell, I decided to go with piral-core instead of the full piral framework.

I actually started with the full version of Piral, but after realizing that I will not be using any dashboards, translation, notifications... and other fancy features (bundled in a collection called piral-ext) I migrated to piral-core.

The Piral docs page on piral-core actually describes this scenario pretty well:

Quite often the scenario is that somebody starts with piral but then realized that one or the other plugin should not be included. (...) In any of these cases a migration from piral to piral-core makes sense.

There were only 2 plugins that I actually wanted: piral-menu, in case I would want to add items to the navigation menu in an easy way; and piral-blazor, for reasons explained below.

So, the index.tsx file looks a little bit like this:

import * as React from 'react';
import { render } from 'react-dom';
import { createBlazorApi } from 'piral-blazor';
import { createInstance, Piral, SetErrors, SetLayout } from 'piral-core';
import { createMenuApi } from 'piral-menu';
import { errors, layout } from './layout';

const feedUrl = 'https://feed.piral.cloud/api/v1/pilet/spiralfy';

const instance = createInstance({
  plugins: [
    createBlazorApi(), //this is where the magic is included ✨
    createMenuApi()
  ],
  requestPilets: () => fetch(feedUrl).then(res => res.json()).then(res => res.items)
});

const piral = (
  <Piral instance={instance}>
    <SetLayout layout={layout} />
    <SetErrors errors={errors} />
  </Piral>
);

render(piral, document.querySelector('#app'));

Things to notice about this setup:

the plugins each come from their respective packages, not from piral.
in the full Piral framework, we would use renderInstance. Piral-core however, does not come with react bundled. It means we should use the standard render method from react-dom to render our Piral instance. (read more here)

`piral-blazor`

Although I called piral-blazor a plugin, it is actually considered a converter: a package that brings support to use a different UI framework. Piral supports around 15 different UI frameworks, other than React.

If you would like more information on how piral-blazor works, I would suggest you read the second part of this article, too!

I included the Blazor converter in the app shell, because I already knew I was going to add a Blazor pilet. It's also possible to load piral-blazor from a pilet. This is for example useful if the app shell already existed and you don't want to change it. This is beyond the scope of this article.

The player: a simple pilet

The player pilet is rather barebones. It uses the following npm package, which is neat wrapper around the Spotify web playback SDK.

gilbarbara / react-spotify-web-playback

A simple player for Spotify's web playback

This allows us to have Spotify playback from the browser. If we only used the Spotify API, we could control the playback, but we would have to have an active device it is playing on. This eliminates that.

Since I wanted to make my own layout for a player in Blazor, I'm setting this one to display:none. This way it's loaded, but it's also hidden from view. Yes I am aware that this is hacky, stop bullying me! :/

While the pilet is simple, this is however demonstrating a niche problem that is pretty well solved by the fact that Piral (and microfrontends in general) can be very technology-independent. If you want to write an app in Blazor, but a certain feature has a pretty nice Javascript library already: You can most of the time just use it from a different microfrontend. This way, there's way less need in having to struggle with any JS interop.

The controls: a Blazor pilet!

Now for the interesting bit: the Blazor pilet!

To create the Blazor pilet, I followed the documentation for Piral.Blazor, from their README on GitHub. Piral.Blazor is a set of NuGet packages that will make Piral work from the .NET side.

smapiot / Piral.Blazor

All .NET things to make Blazor work seamlessly in microfrontends using Piral. 🧩

Here is also a quick video on the process, if you don't like reading:

The process boils down to installing a template. If you want to transform an existing Blazor app however, all you have to do is defining the app shell name, installing the Piral.Blazor.Tools package that will create the right files for your pilet, and installing Piral.Blazor.Utils to be able to use custom Piral attributes in your code.

To make the interaction with the Spotify API a lot easier I used the following great NuGet package, which provides fully typed responses and requests.

JohnnyCrazy / SpotifyAPI-NET

🔉 A Client for the Spotify Web API, written in C#/.NET

Alright, after this round of NuGet installing, we can talk about the components.

A standard page in Blazor, using the @page directive, will work as expected, and will be automatically registered on the pilet API. This is what I used to register the player on the homepage.

For an extension, like a login button that should end up in the app shell header, we can use the PiralExtension attribute, specifying the name of the extension slot you want to render into.

@attribute [PiralExtension("header-items")]

@if(_username is null){
    <a href="@_authUri">Login via Spotify</a>
}
else
{
    <p>Welcome @_username</p>
}

@code {
   //...
}

And... I would say... That's almost the entire story. Because Piral.Blazor does some pretty neat stuff under the hood, the developer experience of creating a Blazor pilet is really similar to creating a regular Blazor WASM application!

Let's run it!

Because we are using Piral, running the Blazor pilet does include an extra step. We need to use the Piral CLI to do its magic! Again, the Piral.Blazor docs to the rescue!

From your Blazor project folder, run your pilet via the Piral CLI 🚀

cd ../piral~/<project-name>
npm start

(You could also add a --feed argument, as outlined here)

In addition to this, if you want to debug your Blazor pilet using for example Visual Studio, you can just run the pilet with IISExpress. (if you want to use Blazor 3.2, there are extra things to consider. You can read about them here. The cool kids use Blazor 5 anyway ⌐■_■ )

This way, you can really use the entire Blazor debugging experience: hitting breakpoints, stepping through your code, and so on.

Dev story: making Blazor work with microfrontends

Achievement unlocked: you have reached part 2 of the story. In this part, I wanted to take the opportunity to tell you about how the combination of Piral and Blazor has matured over the period that I was actively contributing to its codebase; working closely together with the maintainers of Piral.

Looking back

Now, how was Piral with Blazor organized some 2 or 3 months ago?

The Piral Blazor ecosystem in March, 2021

This does not look too complicated. Let's break it down.

For the Piral instance, we rely of course on the Piral framework (although, as said before, this could also be piral-core). Next to that, we also need piral-blazor as a converter.

Under the hood, piral-blazor would actually download the Piral.Blazor.Core NuGet package, which would contain

Blazor framework files: dlls, boot files, metadata, etc.
custom code that would
- expose some methods that can be invoked from the JS side to register, load and unload components
- make sure activated components get rendered in a <div> with a specific id
- provide a way to register dependencies from the pilets in the DI container
- ...

piral-blazor would include these files in the Piral instance, and could call the exposed methodes using JS interop. This then would allow exposing some functions in the pilet API to allow pilets to activate components from their setup function.

The pilets would be created using the official template. The template created files that can be divided into 2 categories:

the Blazor files
other files, mainly TS, codegen and JSON files, where the registration with the pilet API was handled (setup function etc...)

The Blazor files can be considered to be the heart of the pilet, while the other files were just there to be the proverbial "glue" that would make everything integrate into the Piral framework.

Still confused? Below I give an example on how this all worked.

Example

Let's say you know how to create the most beautiful counter component in Blazor. You want to use this counter as a microfrontend in your React application, and give it a dedicated page. Maybe you would also want to render it as an extension on another part of your web app.

Of course, you are already using Piral. You would add the piral-blazor converter to the plugins of your Piral instance.

Then, you would then set up a pilet using Piral.Blazor.Template, and add your counter component. To expose this component to be able to get picked up by Piral you would add an ExposePilet attribute. This would look like this:

@attribute [ExposePilet("my-awesome-counter")]     //!

<div>
    <p>Current count: @count</p>
    <button @onclick="Increment">Increment</button>
</div>

@code {
    int count = 0;

    void Increment()
    {
        count++;
    }
}

Then you would edit the created index.tsx file to something like:

import { PiletApi } from '<name-of-piral-instance>';

export function setup(app: PiletApi) {
  app.defineBlazorReferences([
    require.resolve('./My.Dependency.dll'),
    require.resolve('./My.Components.dll'),
  ])
  app.registerPage('/counter', app.fromBlazor('my-awesome-counter')); //page
  app.registerExtension('counter-slot', app.fromBlazor('my-awesome-counter')); //extension
}

These last lines would register the counter component as a page and an extension via the pilet API. piral-blazor would then via Piral.Blazor.Core lookup the component in the defined references, activate it using JS invokable methods, and integrate it somewhere in the webpage.

What needed improvement, and why?

There are several aspects where the aforementioned ecosystem could improve. Below I outline some of the goals that were set to make this better:

The user should be able to select the version of Blazor they want, independently of the piral-blazor version (because the latter is tied to the Piral version).
There should be a way to transform an existing Blazor application into a Blazor pilet with minimal effort.
Registering Blazor dependencies is cumbersome and error-prone: they need to be manually entered, and if they are not in the right order they will not load correctly. Ideally, we would have an automatic solution.
Registering pages and extensions onto the pilet API should be possible purely from Blazor, without having to do any TypeScript configuration (in the setup function). Additionally, to define pages we should not use a custom attribute, but use the built-in @page directive from Blazor.
Debugging a Blazor pilet from for example Visual Studio should be possible: triggering breakpoints, stepping through the code, ...
Various improvements to single-page navigation, static files, scoped razor styles, ...

What has changed and improved?

Let's dive right in by providing an updated diagram of the Piral Blazor ecosystem:

The Piral Blazor ecosystem in May, 2021

Let's go over the improvement goals and see how this new architecture fulfills them:

1. The user should be able to select the version of Blazor they want, independently of the piral-blazor version (because the latter is tied to the Piral version).

This first goal was made possible by extracting the responsibility of dealing with Blazor files into a new npm package called blazor, and including it as a peer dependency of piral-blazor. This way, the user can install a piral-blazor version that corresponds to their Piral version, and choose any version of the blazor package to include any version of Blazor (e.g. blazor@3.2.x will resolve to the .NET Blazor 3.2 release train).

2. There should be a way to transform an existing Blazor application into a Blazor pilet with minimal effort.

For this goal, we created Piral.Blazor.Tools. The workflow for transforming a Blazor project into a pilet now looks something like this:

Add a PiralInstance property to your .csproj file with the name of your Piral instance.
Install the Piral.Blazor.Tools package
Build the project. The first time you do this, this can take some time as it will fully scaffold the pilet.

(stuff omitted for brevity. Read the complete description here)

This is the reason the template is now grayed out on the diagram: you don't need it anymore (but it's still nice to get a quick start)!

Template or not, the tools package will do all the heavy lifting and create all files needed for integration with the final framework. But this time, they will not be mixed in with the Blazor files: the user should not see these at all! We decided to put them all in a piral~ folder. This final tilde makes it so that this folder will by default not be checked in, thanks to the default .NET .gitignore file.

3. Registering Blazor dependencies is cumbersome and error-prone: they need to be manually entered, and if they are not in the right order they will not load correctly. Ideally, we would have an automatic solution.

The tools package allows us to scaffold the pilet, and also copy over any files that we like to the user's pilet. We used this to fix this problem, by letting the tools copy over a blazor.codegen file.

If you are unfamiliar with codegen files, no worries, I was too! They are basically ways to generate code at build-time. Here you can learn more about one of the loaders that Piral can use (this is one for Parcel):

FlorianRappl / parcel-plugin-codegen

Parcel plugin for bundle-time code generation. Simple, powerful, and flexible. 📦

blazor.codegen looks for a JSON file called project.assets.json to build up a dependency graph for the Blazor project, and then traverses/flattens this graph in the right order: dlls without dependencies (=leaves in the graph) should be loaded first, then their parents, and so on. (For you algorithm nerds: this is depth-first post-order traversal 🤓 ).

It will then use this ordered list of dependencies to generate the pilet API integration code for us at build-time! (How this works will become clearer together with the next goal)

4. Registering pages and extensions onto the pilet API should be possible purely from Blazor, without having to do any TypeScript configuration (in the setup function). Additionally, to define pages we should not use a custom attribute, but use the built-in @page directive from Blazor.

This was an interesting challenge. What has to happen for this to work is that we should have a list of all components that are defined as pages or extensions. And as an additional challenge: we need this list before the components are even loaded, so we cannot simply get them at runtime.

Luckily, when Blazor gets compiled, this @page directive just gets converted into a [RouteAttribute], and we also have the [PiralExtension] attribute, so it's all attributes and we can treat these almost in the same way!

What we came up with, is the Piral.Blazor.Analyzer: a command line tool that will use reflection on the Blazor project dll to extract all components that have certain attributes. The codegen then calls dotnet Piral.Blazor.Analyzer <args>; the output of which gives us something like this:

{
  "routes": ["/counter"],
  "extensions": {
    "My.Components.Counter": ["my-awesome-counter"]
  }
}

The codegen then has all the required information to create code for functions that the setup function needs. The index.tsx file then will use these generated functions from the codegen, and becomes:

import { PiletApi } from '<name-of-piral-instance>';
import * as Blazor from './blazor.codegen';

export function setup(app: PiletApi) {
  Blazor.registerDependencies(app);
  Blazor.registerPages(app);
  Blazor.registerExtensions(app);
  //...
}

5. Debugging a Blazor pilet from for example Visual Studio should be possible: triggering breakpoints, stepping through the code, ...

This was an interesting challenge. The first step for me was learning how the debugger actually works. I stumbled upon an excellent blog post by Safia Abdalla. She's a software engineer at Microsoft on the .NET team.

Safia AbdallaFollow

I make open source at @nteractio, make software at @Microsoft, and write books and blogs. Dream big and follow through even bigger.

The blogpost can be found on her personal blog: Under the hood with debugging in Blazor WebAssembly. There, she explains the concept of the debugging proxy.

After some experiments and proof-of-concept work, we found out that in Blazor 3.2, we could not load the dlls and pdbs (symbol files) dynamically. They had to be included in the blazor.boot.json file for them to get picked up by the debugger.
We solved this by configuring the Piral CLI using a kras script injector. I won't go into too much detail here, so I'm oversimplifying massively: kras is a proxy/mock server for your frontend.

FlorianRappl / kras

Efficient server proxying and mocking in Node.js. 💪

While it is most commonly used to mock a backend, we can use it as a proxy too! You can configure kras with js files included in a mocks folder. Let's take a look at a code snippet:

/* mocks/debug.js */

//...
const toProxy = [...uniqueAssemblyNames, ...uniquePdbNames];
const shouldBeProxied = ({ url }) => toProxy.filter(x => url.endsWith(x))?.length && url.startsWith('/_framework/_bin');

module.exports = (ctx, req, res) => {
    if (shouldBeProxied(req)) {
        return proxy(req, iisUrl);
    } else if (req.url.endsWith('blazor.boot.json')) {
        return returnWithTweakedBBJson(res);
    }
};

This last part is what we mentioned before: when we debug we want to modify the blazor.boot.json file to include our pilet dlls and pdbs, so they get loaded when the debug starts.

As we see on line 5, a request should be proxied if the url points to one of our unique dlls or pdbs. This means the shared dlls from the appshell will just be loaded as normal, but the dlls the Pilet brings will be proxied. On line 9 we can see where to: the requests for the pilet dlls will be proxied to the url where IISExpress is running (we can get this from the launchSettings.json file by the way).

Because of this hack, we can now trigger breakpoints in Visual Studio, step through the code, inspect variables, etc.!

Oh, by the way, .NET 5 made stuff a lot easier with the inclusion of lazy loading! I won't give a full explanation, but it boils down to: we can now just load the pilet dlls and pdbs lazily, and everything just works! Proxying and tweaking the boot file isn't necessary!

6. Various improvements to single-page navigation, static files, scoped razor styles, ...

I won't go into details about these. There are always things to improve about code, and these were some major ones :)

Example

We take the same scenario as before: the counter. With the new setup, if we want a page, there is nothing at all to do that is special. We just need a regular Blazor page. If we also want to expose an extension, we can use the new [PiralExtension] attribute from Piral.Blazor.Utils

@page "/counter"
@attribute [PiralExtension("my-awesome-counter")] 

<div>
    <p>Current count: @count</p>
    <button @onclick="Increment">Increment</button>
</div>

@code {
    int count = 0;

    void Increment()
    {
        count++;
    }
}

The tooling will do all the rest! No more screwing around in TypeScript for a setup function to manually create and keep updated! Isn't that convenient?

(For more advanced uses you can still define an optional setup.tsx file. Refer to the README to see how that works.)

Final thoughts

My first thought after writing this article would be "damn, I wrote quite a long article again", immediately followed by "are people actually going to read this one?". My last post was received very well, and I thank each and everyone that reacted to it! Feel free to let me know in the comments if this article was in any way interesting, helpful or cool!

I enjoyed contributing to Piral a lot. I've always wanted to dive into the open-source community, and because of the guidance given by the Piral maintainers, I feel like I could make a difference in this project (Piral is also pretty damn cool if you ask me).

Looking back on it, in my opinion, using Piral and Blazor has become better in both functionality and developer experience, and I'm really proud of that ("hey, a Belgian guy that says he is proud of something, that's quite rare!"). If you want to see my contributions first-hand; or just criticize my code, here and here are lists of the PRs I made.

Then I want to address Blazor. While I can definitely see the appeal of it, and it's a cool technology: it was pretty hard to get a grasp on the technical side of it. Lots of the stuff that's going on is quite magical at first. I'm glad the entire thing is open-source, because finding solutions often meant peeking behind the curtain and reading the source files on the dotnet/aspnetcore repo.

Because of this however, I've learned an awful lot about how Blazor WebAssembly works; what the limitations and weird quirks are, etc. It also just broadened my knowledge of the .NET ecosystem as a whole.

My experiences creating a Netflix clone using microfrontends

Dante De Ruwe — Thu, 18 Mar 2021 16:46:32 +0000

I created a Netflix clone using Piral: an open-source framework for creating modular applications.

In this article, I will go over what microfrontends are, why they are useful, and what frameworks exist to make implementing them easier. I'll also share my experiences creating a project by myself using React and Piral: two technologies I had previously never touched. I will cover what I did, and how I did it. Finally, I will present some closing thoughts, opinions, and personal notes about this endeavor.

The "How I did it" section will be written in a way where every developer, regardless of skill level, should be able to follow. Be sure to give Piral or microfrontends as a whole a try, and let me know how it went!

The home page of the application

What are microfrontends?
Why microfrontends?
Microfrontend frameworks
Piral
- Building blocks and terminology
The project
- What I did
- How I did it
Final thoughts
Quick links to all code

What are microfrontends?

Microfrontends try to extend the idea and the benefits of microservices into the frontend space. In essence, this architecture pattern comes down to "splitting up the frontend monolith" into smaller, more easily manageable pieces.

This allows fully cross-functional teams to work on these, focussing on a specific business feature or company mission. Rather than "horizontal" teams, per layer or technology; these teams manage the "vertical" slices of the application. Each team is autonomous, and has end-to-end – from the database to the UI – responsibility for the features they develop.

Teams should be able to independently create and deploy these microfrontends. This cuts down on inter-team communication; which could then also enable distributed development.

This is especially beneficial for larger companies and projects, where the Jeff Bezos "Two Pizza Team" rule (i.e. the whole team can be fed by two pizzas) can be helpful. Spotify for example, calls these smaller feature teams "squads". Interesting read here.

Why microfrontends?

Microfrontends make teams more agile

When comparing the characteristics and benefits of microfrontends with the 12 Agile Principles, lots of overlap emerges:

Autonomous teams

Autonomous teams satisfy lots of these agile principles. In short: teams that can operate on their own are less prone to being slowed down, can make changes quickly, and feel a greater sense of ownership.
Incremental upgrades

By being decoupled and decentralized, the microfrontends architecture pattern ensures that the incremental and iterative process of agile software development can succeed.
Independent deployment

Microfrontends can be deployed independently. This can enable shorter release cycles, because all different parts don't have to be in sync with each other.
Simple and decoupled codebases
Simplicity is essential to agility: this makes it easier for the whole team to be on board and iterate fast. Decoupling makes using different technologies possible; but even when using the same technologies throughout the app it can still be very beneficial for efficiency of development.

Microfrontend frameworks

While you could take the microfrontend principles and devise your own solution to manage them (in fact, that's kinda what my bachelor thesis will be about); there are lots of frameworks already out there that can do some of the heavy lifting for you.

Florian Rappl outlines and categorizes a lot of these frameworks in the following blog post:

Florian Rappl

Nov 21 '19

Six Patterns for Microfrontends

#piral #microfrontends #patterns #architecture

Comments

17 min read

Popular options include Single SPA, Open Components, Mosaic, Podium, Luigi and Piral.

Rather than competing frameworks, most of these exist side by side, and they each provide a different way of creating these microfrontend solutions. They differ in key properties such as completeness (just solving some problems such as routing vs providing a full end-to-end solution with error boundaries, tooling, eco-system, etc.) or architecture style (e.g., build-time composition vs client-side composition vs server-side composition).

Piral

Piral is an open-source framework for fully flexible modular applications. It is built on top of React, but has lots of plugins available for other frameworks and technologies.

Building blocks and terminology

An application built with piral consists of multiple parts.

If you have no experience with microfrontends, this section can be confusing. Don't be alarmed: the section "The project" below will turn the abstract into the practical, which will be easier to follow.

The Pilets (feature modules)

These are the individual feature modules, also known as microfrontends. They each include their own dependencies and assets, and are completely independent of each other.

Pilets can define how the integration of their components will happen. Does the pilet need a dedicated page, or will the content be rendered inside an already existing pilet? Maybe we need a dedicated page, and also register a button somewhere else that will link to the page? It is all possible.

The feed service

Pilets are usually published to a feed service (e.g. a REST API). Piral provides its own feed service over at piral.cloud.

It should be noted that Piral can work without a feed service but a feed service makes deployments easy and consumption very dynamic; showcasing all the advantages of Piral.

The Piral Instance (app shell)

This is the place where all feature modules will be integrated. The piral instance will pull all registered pilets from the feed service, and put them where they need to go as defined by the pilets themselves. The app shell also is the place to put your basic layout: navbars, headers, footers, and shared components.

The result of building the app shell is a dist/release directory for hosting, and a dist/emulator directory with a tarball which can be published to an NPM registry to aid in the development and the debugging of the individual pilets.

(Component) extensions, pages and menu items

The piral API supports registering extensions in your pilets and Piral instance. Let's say for example we have a webshop with 2 pilets: a discover pilet that lists products and a checkout pilet that enables users to purchase these items (this is by the way a classic example for microfrontends, read more here). The discover pilet should include a button to purchase items, but since that is not the responsibility of this team, the checkout team will create this button and register it as an extension that all pilets can use. The discover pilet will then just register an extension slot where the app shell will integrate the right extension into.

Piral also has a built-in way to register pages and menu items. These can also be seen as extensions, but where the work is already done for you.

The project

What I did

Application overview

You can find the application online on netflixclone.deruwe.me.

This application is a Netflix clone with some basic functionalities. There is a Browse page where the user can discover showcases of trending series and movies, top-rated ones, etc.

Of course, to find a specific movie or series, the user can also use the provided Search bar.

Every media tile also has a Favorites toggle in the top right corner. Clicking it adds the series or movies to the user's favorites list, to be found on the favorites page.

The user can switch accounts via the Profile option in the top right. All favorites are linked to the specific account.

It is worth noting that this demo project does not come with a custom backend: all data is coming from a 3rd party API, the accounts are dummy accounts, and the favorites are stored in local storage.

Impressions

The Browse and the Favorites pages The Profile page

Structure of the application

The app shell

The app shell contains only the logo, navigation, and footer. All the other components are provided by the pilets in the form of extensions, pages, and menu items.

The pilets

Pilet	Registered components
`Browse`	Menu item `Browse` (page)
`Favorites`	Menu item `FavoritesToggle` (component extension)
`Watch`	`MovieTile` (component extension) `Player` (page)
`Search`	`Search` (component extension)
`Profile`	`UserProfile` (component extension) `AccountSwitcher` (page)

How I did it

Throughout the creation of the project using piral, obviously, the Piral documentation was my main source of inspiration. There, they also have video tutorials on lots of topics regarding Piral.

The Piral documentation also talks about the 3 phases of the development workflow. This is also the way I tried to develop my application. Of course, to be able to experiment, I sometimes stepped a bit of out bounds.

0. The planning phase

But before following any of the laid-out steps provided by Piral, I looked out for a sample project that I could build upon. I'm not a designer, so looking for a React project with good styling was the easiest option. I found this project, which was written using an older React syntax, and was all in one big App module. I converted everything into separate React functional components. This was a great way to learn how React works.

You can see the results in the following repo. The commit history here shows what I did.

DanteDeRuwe / react-netflix-clone

Learning React by creating a simple Netflix clone. (I transformed this into a microfrontend solution! See https://git.io/netflix-piral)

1. The setup phase

What needs to be done in this phase?

Develop the piral instance

Set up a feed service and connect the piral instance to it

Distribute an emulator package

1.1. Creating the Piral instance (app shell)

You can find the code on github

Following the documentation showed me how to get this up and running. Install the Piral CLI globally by running:

npm install piral-cli -g

(one could also use npx to avoid unsafe global installations, see below)

The CLI exposes commands starting with piral and pilet. In this phase, of course, we will need the piral commands.

To create a Piral instance (app shell) called netflix-piral, let's run

piral new --target netflix-piral

We can run the newly created Piral instance with the following command:

piral debug

# or, if you want to open the browser automatically:
piral debug --open

– using npx –

Instead of a command like piral debug which only works inside a directory with a package.json or if you have the Piral CLI installed globally, you can also use npx:

if the given name is not available in (modified) path (e.g., global path or node_modules/.bin), npx will try to get the command from NPM and run it (non-globally i.e. from user privileges)

if the given name is available it will just run it from there (also from user privileges)

Let's have a look at one of the most important files, index.tsx:

The renderInstance function outlines the responsibilities of the app shell: it takes care of the layout, the error layout, and requests the pilets from a feed service. As we can see on line 6 - by default - it's just pulling from an empty feed.

In fact, the only thing that will change in this file, is the feed URL. To be able to do that: let's first set up a feed.

1.2. Setting up the feed service

While you could (and in some circumstances, should) set up your own feed service, most of the time the service provided by the Piral team itself will suffice. For development purposes, you get multiple feeds for free! This service can be found on piral.cloud.

▸ Creating a feed on piral.cloud

Of course, we're going to click + New Feed.
Next, we'll give the feed a unique name (which cannot be changed), and optionally, a description so it's clear for what this feed will be used.
You can also configure the allowed hosts.

You'll see the result on the overview:

To be able to publish pilets later, we'll need an api key. You can manage them by clicking
To get the feed url for the app shell, we can click the feed title. The url will be displayed:

We'll copy the feed url and place it where we wanted it before: in the index.tsx of the Piral instance (line 6).

1.3. Creating the app shell layout

We have an app shell now which pulls from our own (still empty) feed! We'll add pilets to this feed later. But first, maybe we should customize the layout of this app shell. As written before, the main responsibilities we want for this app shell are the logo, the navigation, and the footer.

After scaffolding, the layout.tsx file contains a lot of components and also combines them in a layout object to be used by the index.tsx. While this is fine, I like to split up all my components using a single file per component, so the result looks like this:

We'll put the layout in ./components/App.tsx, the navigation template in .components/Navigation.tsx and for the menuitems, they are just rendered using <li>...</li>.

Remember what I mentioned before:

The app shell contains only the logo, navigation, and footer. All the other components are provided by the pilets in the form of extensions, pages, and menu items.

This is absolutely the case, but we do however need to define where the pilets need to render these extensions! Here is a quick wireframe diagram for the app shell.

The pages registered by the pilets will just be given to the App component as children. We can use a react-router to surround them.

As for the extensions: The key to being able to integrate these is an ExtensionSlot with a specific name. The pilets are then able to register extensions, providing a name, and the app shell will put them in the right slot.

The code for the App component is below. On line 14 the extension slot with name="header-items" is registered, on line 19, the different pages will be rendered.

The menu items are standardized in Piral. The component registered in index.tsx as the MenuContainer (= in our case, the Navigation component) will get menu items as children when pilets register them.

1.4. Deploying the app shell on Netlify (or somewhere else)

If you already know how hosting works, here's a TLDR: execute piral build --type release and publish the dist/release/ folder! You could of course set up CI/CD to do this for you. Don't forget a _redirects file for routing!

To deploy the application for the world to see, we need to publish it somewhere. To me, the best place to do this is Netlify. One could of course choose Azure Static Web Apps, Github pages, or another hosting platform, but Netlify is easy to use and has a lot of great features that are completely free.

To get started, create an account on Netlify. I like to use my Github account because this way the accounts are already linked.

Next, create a "New site from git" in the sites tab of the interface.

Find the Github repository of your app shell. If you don't have one already... you should create one ;)

Now configure the build settings as follows:

set a branch (I use master, you could also create a custom release branch)
set the build command to npm run build or piral build or piral build --type release
set the publish directory to /dist/release/ (don't skip this step!)

Then you are ready to deploy your site with the click of a button! Now every time you push your code to the selected branch, the site will be updated! CI/CD for the win!

▸ The `_redirects` file

When you deploy the app shell for the first time, you will not notice it, but the routing is not perfect. To save yourselves some headaches later on, you best follow the next steps already, so you won't have to touch your app shell again.

If you go to yourwebsite.netlify.app/test, Netlify will try to find a test.html page to serve you, will not find it, and show an error message. We want React Router to deal with routes. We have to redirect all routes to the index.html... To do this, we create a folder with path /src/static/ and put a _redirects file into it:

/* /index.html  200

To make sure this file is copied to the release directory on build, we need to configure webpack to do so.

Install the CopyWebpackPlugin

npm install copy-webpack-plugin --save-dev

In the root folder of your project, create webpack.config.js

This will copy everything from the src/static/ directory to the build directory. This means you can later on also add images and other files to this static directory if you so desire.

1.5. Publishing the emulator

▸ What is the purpose of the emulator?

Now, we have our app shell up and running. When pushing Pilets to our feed service, the app shell can access these immediately and the site will be updated. But what if we want to develop new pilets? Surely we won't be publishing them a hundred times to see how they look, right?

Luckily, Piral has a good solution to this: an app shell emulator. The pilets can use the emulator to see how they will look when integrated into the app shell, to be able to quickly debug the pilets.

To create an app shell emulator, run

piral build --type emulator

The emulator is a .tar.gz or .tgz file (a so-called "tarball") and can be found in the /dist/emulator/ directory.

Great. Now we have a file. If we are creating pilets alone, on one pc, this is no big deal. But ideally, we want the emulator to be accessible from every pilet, and also be able to update the emulator when a new version of the app shell is necessary. That's why it makes sense to publish the emulator.

▸ publishing the emulator package to npm

If you have experience with npm, here's a TLDR: run npm publish dist/emulator/<emulator_file>.

To be able to access the emulator from everywhere, we are going to use the node package manager or npm. First, go to npmjs.org and create an account if you don't already have one.

Next, in your terminal, run

npm login

and log in using your username and password. Next, you can run

npm publish dist/emulator/<emulator_file>

The <emulator_file> will in our case be netflix-piral-1.0.0.tgz or something similar. If you get an error (which could mean the name you chose is already taken), refer to this article or the npm docs.

If you look at your registered packages on npmjs.org, you should be able to see the published emulator package! This will be very useful in the next phase: the feature phase, where the development of the pilets will be addressed.

2. The feature phase

What needs to be done in this phase?

Build and publish pilets to enable functionalities in the app.

Manage separation of concerns

extract app shell functionality into pilets

split larger pilets or merge smaller ones

2.1 Scaffolding a pilet

Creating a pilet is really straightforward. The piral CLI provides an easy way to scaffold a pilet based on a piral instance. For us the workflow will look like this:

mkdir browse
cd browse
pilet new netflix-piral

This will create a folder browse, and put a new pilet called "browse" – which is based on the Piral instance netflix-piral – inside of it.

2.2 The first version of the `browse` pilet

Let's create some functionalities! The home page of this app will be the "browse" page. Since discovering new series and letting the user browse through series and movies is a pretty big part of the app, this will be the responsibility of one pilet (and, by consequence, a separate dev team).

The file structure looks like this:

A pilet is very lightweight. The only file to look at is the index.tsx, where some interesting examples of the Piral API are shown:

The setup function is the heart of the pilet. This is where the app shell will look for instructions for integrations.

We won't need the notifications or the tiles. You can learn more on these from the Piral documentation.

The most interesting method for us is registerMenu, we'll need this for the "Browse" menu item:

app.registerMenu(() => <Link to="/browse">Browse</Link>);

And to register a page where this menu item can link to, we will need to add

app.registerPage('/browse', Browse);

Where this Browse is just a regular React component (for now). The structure looks a bit like this:

Browse
    ├── Hero
    ├── Showcase
    │       ├── MovieTile
    │       └── ... #more movietiles
    └── ... #more showcases with movietiles

▸ Debugging the pilet in isolation

To be able to test how the pilet will look after integration into the app shell, of course, we could just publish it and look at the live website. However, I won't have to explain why "testing in production" is not the best idea ever.

So, Piral offers a way to debug the pilet, this is where the emulator comes into play. To debug the pilet, you can run

pilet debug

After the build process is complete, the CLI will let you know on what local address you can look at the result (usually http://localhost:1234).

It's interesting to note that this command is almost identical to the one for the app shell, but there we used the piral keyword, and now we use pilet.

This section is called "debugging the pilet in isolation", which seems logical since we only have one pilet defined. Later on, I'll discuss a great feature that enables you to debug one pilet that is part of an application with multiple pilets.

▸ Publishing the pilet

We already published the piral instance (app shell), and the fun thing about working with Piral is that this app shell will pull every pilet from a feed and integrate them client-side.

This means, to publish a pilet, we won't have to touch deployment stuff. We just need to publish the pilet to the feed we created earlier.

We can do this by:

pilet publish --fresh --url <feed_url> ---api-key <feed_api_key>

Tip: I saved this snippet as a script called publish.sh, added it to .gitignore (so my API key won't be on Github), and then ran the script whenever I wanted to publish.

The --fresh flag makes sure that before publishing, a fresh build is made to include any changes made after the last build.

The feed url and API key, as mentioned before, you can find in the piral feed service dashboard. The direct url is:

https://www.piral.cloud/feeds/<feed_name>/api-keys

2.3 The `profile` pilet

Next, let's tackle a more interesting case. The profile pilet. This pilet will again register a page, /profile, but will also do something else: it will register a component extension.

When looking back at the app shell, this component extension has to be put in the extension slot header-items. so that's what we will do.

The index.tsx of the profile pilet will then look like this:

Where ProfileExtension and ProfilePage are just regular React components.

As is the deal with component extensions: the app shell will integrate the registered extension into the right ExtensionSlot (the one with a matching name).

2.4 The `favorites` pilet

Here we start to run into an interesting thing. We want to introduce the favorites as a page where we can find all the favorite series or movies. This means multiple things:

Just like in the Browse component, we will need a way of displaying media (MovieTile)
We will need to provide a FavoritesToggle button in every MovieTile, to be able to toggle this item as a favorite

▸ The `MovieTile` and thoughts about code duplication

We could just copy over the MovieTile code from the browse component and reuse it here. This would be a very viable strategy, and it's also the one I used when you look back in the commit history.

– "Don't repeat yourself" ? –
While it is true that the DRY principle can result in cleaner code within the scope of one solution; it sometimes limits the desired decoupling of applications. Especially in microfrontends, sometimes repeating yourself cán be useful, and the reverse is often more difficult and undesirable. There is an interesting article to be read here

That being said, later on in the project, I looked back at this part in the Piral docs:

"Determine when to split pilets and potentially split larger pilets or merge smaller ones."

That's when it started making sense to extract the MovieTiles into a separate watch pilet, where they are registered as component extensions. I'll talk about the watch pilet in the next section.

▸ The `FavoritesToggle`

We'll offer the favorites button as a component extension, so all pilets or the app shell can integrate this button wherever they want them.

For that, we need this in the setup function of the favorites pilet:

    app.registerExtension('ListToggle', props => <FavoriteToggle {...props.params}></FavoriteToggle>);

This is where passing parameters into component extensions becomes interesting. A very basic FavoriteToggle component may look like this:

(If you want to see the full code, check the github repo, I'm omitting stuff for brevity)

For this toggle function, it is important that the button gets some properties. Using a favourites toggle may look like this:

<FavoritesToggle movieId="15165" media_type="tv" />

or something similar. All this introduction leads us to the main question: how to pass parameters to component extensions when using them across pilets?

Well, it's pretty easy: the Extensionslot component has a property params. Whenever we want to use an extension, we give the slot the params, and piral will pass these params to the extension that will end up in that slot. This means, a registered extension will have props.params, which will come from wherever we defined the extension slot.

If we want to use this component extension from other pilets, the extension slot will have to look something like:

<ExtensionSlot name="ListToggle" params={/*an object with the params here*/}/>

We will see an example and best practices about this in the next section:

2.5 the `watch` pilet

This pilet would have 2 things registered:

the MovieTile we talked about earlier.
- this should have a spot where our FavoritesToggle component extension can fit into!
the Player (which is just a simple page and we won't discuss further)

▸ The MovieTile

This was an interesting lesson in what I like to call extensionception: we'll register a component extension, but within that extension, we'll use an ExtensionSlot where another component extension will fit into:

The eventual result on for example the favorites page will look like this:

Ok, let's look at the MovieTile component:

This component accepts a whole bunch of properties to be able to display the movie tiles with all the information. It's a purely presentational component.

▸ Passing extension dependencies via props

On line 11 you can see that the MovieTileProps also contain a definition for a React component reference: this will be the FavoritesToggle we defined before.

But why don't we just put <Extensionslot name="ListToggle"/> there? Well, it's because of what I learned while reading the Pilet best practices on using extensions

Using components provided from other pilets is done via "extensions". The problem is that the extensions require the Extension component of the Pilet API to be integrated.

Indeed. We would need to do this at the top of our component extension file

import { ExtensionSlot } from 'piral';

This is a bad practice: we couple our components to the Pilet API, and now they are no longer reusable, testable, and generic.

The fix comes down to this: The only file in a pilet that should depend on the Piral framework is the index.tsx file with the setup function. From there, we can pass down the needed dependencies. For the MovieTiles, it looks like this:

On line 10, we use app.Extension, which has the same purpose as an ExtensionSlot. We use the result of that to have a component to pass into another component. This way, the MovieTile has props.Toggle defined, and can use it just like any other React component.

▸ Debugging one pilet and seeing the interaction with the other pilets too

While developing the browse pilet, the section where I talked about debugging was called "debugging the pilet in isolation". Now, we're going to do something more powerful.

Let's recall what happens when we run pilet debug. We have an app shell emulator in which the pilet will be integrated. That's it – 2 parts:

the app shell (emulated)
the pilet that's being debugged

But what if we want to see the already published pilets too, to see how the pilet that we are debugging will fit into them? (mainly, in this case, we want to see how the extensions integrate)

At the time of writing, the Piral CLI is still in version v0.12.4, but I got the recommendation to switch to the v1.0.0 preview version (the @next version). This version of the CLI provides in my opinion a major game-changing feature: the ability to debug pilets, while also being able to include remote pilets from the feed!

It's also very easy to do:

pilet debug --feed <feed_url>

And voila! We can see how the new pilet will fit into the app shell and the already defined pilets in the feed! Amazing!

Honestly, since learning about this feature, I never ever used debugging in isolation again. It's so much easier to see how the pilet will fit into the application when also including other pilets into view.

To make my life easier, this is what my scripts looked like in every pilet's package.json:

  "scripts": {
    //...
    "debug": "pilet debug --feed <feed_url>"
  },

This way, I could just run the command npm run debug!

2.6 The `search` pilet

This pilet just registers one component extension. We'll also set it to render into the header-items slot. This way: we will get the search and the profile extension both in there.

3. The maintenance phase

This is mainly bug fixing and doing optimizations.

Persisted state

This has nothing to do with Piral, but I wanted to store some data via local storage and I ran into a pretty cool way to do this by using this custom react hook.

Lazy loading

In the pilet setup function, we can set pages to lazily load. This is related to bundle splitting: more info here.

e.g.

  const ProfilePage = React.lazy(() => import('./components/ProfilePage'));
  app.registerPage('/profile', ProfilePage);

Making changes to the app shell

If time was spent thinking about the responsibilities of the app shell before developing the first pilets, you can save yourself a lot of headaches. Though it is possible that the app shell needs to be updated. Of course, the pilets that depend on the app shell emulator for debugging would need to get an update as well!

Luckily, this is fairly simple

the app shell is updated, built, and the update is pushed to npm
in the pilet, run pilet upgrade to pull in the latest version of the emulator

Final thoughts

While I had 0 experience using React and Piral before doing this project, I think the project turned out really well.

When working with microfrontends, the biggest hurdle is getting to the big picture. To me, it was really complicated to imagine how all the microfrontends would come together.

▸ The "black box method" for learning concepts

I saw this video recently and it really stuck with me. When trying to understand hard concepts: treat them like a black box first, and learn how to use them, before learning about how they work.

The experience you get by using a concept will give you a major advantage while learning how they work because you will already understand the desired outcome.

The key to understanding microfrontends – in my opinion – is to build some! Once you see visually how they all come together, it's easier to imagine how this integration is happening. This is why a microfrontend framework is valuable. Not only does it provide the best developer experience, but also: lots of stuff is already done for you, and you can get started easily.

This analogy, by the way, also makes sense when explaining how I learned to work with React in just one week. Rather than starting from scratch, I just tweaked an already existing project, and that already got me to understand lots of the concepts. (Of course, my experience with Angular helped a little as well)

Quick links to all code

App shell

DanteDeRuwe / netflix-piral

A Netflix clone using microfrontends built as a proof of concept for Piral. This repository contains only the app shell. Built with React. Read more at http://bit.ly/netflix-piral-article

Forem: Dante De Ruwe

How I Set Up Shared Agent Config for Our Team with APM

Four problems I kept running into

Configuration drift

Tool lock-in

No source of truth in the repo

Shared and project-specific config blur together

Finding the right tool

skills.sh

APM: a package manager for agent configuration

One shared repo, many consuming projects

Why this modularity matters

How a project consumes shared packages

Pulling in community-built skills

Local overrides with .apm/

What you get from this setup

Advice if you're doing this too

Keep packages narrow

Only share what's reusable

Treat it like code

Consider not committing generated files

Try it yourself

How to create a local gitignore file

Additional gitignore files

Keeping your gitignore file local

Tips

Switching up your Spotify experience with microfrontends and Blazor

My experiences creating a Netflix clone using microfrontends

Contents

Spiralfy: a modular web application

Overview

The code

DanteDeRuwe / spiralfy

A different way of using Spotify! Built using a microfrontend approach with Piral, Blazor and React. Read more on https://bit.ly/spiralfy-article

Article

About

The Spiralfy appshell

piral-blazor

The player: a simple pilet

gilbarbara / react-spotify-web-playback

A simple player for Spotify's web playback

The controls: a Blazor pilet!

smapiot / Piral.Blazor

All .NET things to make Blazor work seamlessly in microfrontends using Piral. 🧩

JohnnyCrazy / SpotifyAPI-NET

🔉 A Client for the Spotify Web API, written in C#/.NET

Let's run it!

Dev story: making Blazor work with microfrontends

Looking back

Example

What needed improvement, and why?

What has changed and improved?

FlorianRappl / parcel-plugin-codegen

Parcel plugin for bundle-time code generation. Simple, powerful, and flexible. 📦

Safia AbdallaFollow

FlorianRappl / kras

Efficient server proxying and mocking in Node.js. 💪

Example

Final thoughts

My experiences creating a Netflix clone using microfrontends

Contents

What are microfrontends?

Why microfrontends?

Microfrontend frameworks

Six Patterns for Microfrontends

Piral

Building blocks and terminology

The Pilets (feature modules)

The feed service

The Piral Instance (app shell)

(Component) extensions, pages and menu items

The project

What I did

Application overview

Impressions

Structure of the application

The app shell

The pilets

How I did it

0. The planning phase

Local overrides with `.apm/`

`piral-blazor`

▸ The `_redirects` file

2.2 The first version of the `browse` pilet

2.3 The `profile` pilet

2.4 The `favorites` pilet

▸ The `MovieTile` and thoughts about code duplication

▸ The `FavoritesToggle`

2.5 the `watch` pilet

2.6 The `search` pilet