DEV Community: Shy Ruparel

How we turned the Replay keynote surprise into an open-source embedded playground

Shy Ruparel — Tue, 02 Jun 2026 15:36:42 +0000

In the first post, I told the story of how the Replay badge went from "wouldn't it be cool if..." to thousands of circuit boards showing up at a developer conference.

This one is about what was hiding inside that surprise.

Samar Abbas, our CEO and co-founder announcing the Replay Badges

During the final keynote at Replay, our CEO and co-founder, Samar Abbas, came back on stage at the end of the session for a very "one more thing" kind of moment. He wanted to give Replay attendees one more place to deploy Temporal, then revealed that we had secretly manufactured 2,000 hardware badges for the people in attendance.

As attendees left the keynote hall, we handed them something that looked, at first glance, like a very over-engineered conference badge. Which, to be clear, it absolutely was. But it was also a tiny hackable computer: an ESP32-S3, an OLED screen, an LED matrix, buttons, joystick, motion sensor, haptics, IR, MicroPython, games, firmware updates, and enough sharp edges to remind me that embedded systems do not care about my feelings.

Now that the source is public on GitHub with our docs live at badge.temporal.io, I want to open the thing up and show you all the strange little systems inside it.

Because we did not just open source "some firmware."

We open sourced an entire ecosystem.

Our hard work visualized. These are the Temporal badges laid out and ready for attendees to grab after the day 2 keynote. A huge moment for me and the team!

Crowds swarming the tables to pick up their badges.

Attendees checking out their badges

What we actually open sourced

When I say the badge is open source, I do not just mean "there is a folder of C++ somewhere." The public repo includes the firmware, hardware design package, fabrication files, docs site, release asset documentation, flashing tools, MicroPython examples, community app infrastructure, and enough context for someone else to pick up the project without needing to inherit every weird Slack thread, manufacturing panic, and half-obsolete architecture decision that got us here.

The public repo looks roughly like this:

firmware/        C++ runtime, MicroPython bridge, apps, Doom, OTA
hardware/        KiCad source, fab outputs, artwork, mechanical files
ignition/        Temporal-powered flashing workflows
docs/            public badge docs site
community_apps/  installable apps from contributors
data/            schedule, speaker, and floor bundles
release-assets/  firmware and factory image release notes

The goal was for the badge to stop being only a thing we handed out at Replay and become something people could inspect, modify, repair, reflash, extend, and, if they are brave enough, theoretically manufacture themselves.

The hardware package includes KiCad projects, fabrication outputs, BOM and CPL files, mechanical references, and artwork. In theory, you can take the files we published and manufacture your own badge.

In practice, this is where you discover that "open hardware" still means making friends with fab notes, component substitutions, assembly constraints, and files named things like GBR_260331-R3.zip.

Which brings us to the first lesson.

Hardware has different gravity

The hardware is where the project becomes physical. Every feature has to fit inside real power, space, component, manufacturing, and assembly constraints.

The badge runs on an ESP32-S3 module with 16 MB of flash and 8 MB of PSRAM. It has a 128x64 monochrome OLED, an 8x8 LED matrix, four face buttons, an analog joystick, an accelerometer, haptics, IR send and receive, USB-C, battery power, and a two-board assembly where the backplate is also part of the visual design.

That sounds like a spec list, but in hardware every bullet point is also a negotiation. The screen wants power. The LEDs want power. The battery wants to be treated like a tiny volatile roommate. The IR receiver wants timing. The buttons want debounce. The enclosure wants tolerances. The PCB wants trace routing. The manufacturer wants files in a very specific shape. The designer wants the badge to look like it belongs at Replay and not like a dev board fell into a lanyard.

Our hardware guys did not believe I was going to be useful writing code at first, which is fair. From their perspective, I was a DevRel person walking into a hardware project with a lot of opinions and an alarming amount of confidence. It took them seeing my personal hardware hacking setup: the bench, the parts, the alarming amount of half-finished projects, and the Gridfinity-filled tool chest to become fully confident in me. After that, the dynamic changed a little. I was still learning their world, but I was not a tourist in hardware.

I also want to be clear about something: at the beginning, I did not understand half of the hardware file types involved.

KiCad projects, Gerbers, CPLs, fab zips, board backups, assembly exports, pick-and-place files — all of it looked like someone had taken a normal software repo and fed it through a manufacturing portal.

Our hardware consultants were moving fast in the tools they actually use. That matters. Hardware collaboration is not shaped like web app collaboration. A lot of hardware work naturally happens through big generated files, CAD exports, board snapshots, and zip packages that are meant for humans, factories, and design tools, not for a tidy Git history.

They also contributed to the C firmware along the way, so the Git problem was not just "how do I store board files?" It was also "how do I rebase active firmware changes from people who are simultaneously thinking about traces, components, and whether a factory can actually assemble this thing?"

So, somehow, my job became translating all of that into Git: rebasing branches, separating source from generated artifacts, preserving the files a manufacturer would need, and cleaning the history enough that a future human could make sense of it. At some point the hardware guys started referring to me as the Merge Czar, which is not a job title I expected to earn on a PCB project, but here we are.

There is a commit in the hardware history literally titled "i got spooked by the datasheet." I respect that commit deeply. That is hardware development in one sentence. You read something, your stomach drops a little, and suddenly there is a new BOM, a new CPL, a new Gerber package, and an R number attached to the end of the filename.

Software teams debate commit hygiene. Hardware teams have fab revisions.

Both are valid. One of them is just much heavier on zip files.

Firmware as joy infrastructure

The firmware had two jobs that were always in tension: create joy and delight for attendees, and make the badge easy enough to hack on that the delight could keep going after Replay.

A Replay attendee putting our fun firmware to good use

At first glance, firmware sounds like the boring layer. It is not. It is the layer that decides whether the badge feels alive.

The native C++ firmware handles boot, the OLED UI, inputs, LED animations, haptics, IR, storage, OTA updates, app launching, power behavior, the file system, and the basic resource ownership rules that keep everything from stepping on everything else.

This is where the badge became less like a single Arduino sketch and more like a tiny operating environment.

Every fun thing on the badge wants to own the same small set of resources. The screen. The buttons. The joystick. The LED matrix. The IR receiver. The filesystem. Memory. Time.

If you launch a MicroPython app, who owns the OLED? If Doom starts, what happens to the scheduler? What even is a scheduler? If an LED animation is running in the background, what happens when a game wants to take over the matrix? If IR is listening, how long can Python go without polling before frames start getting dropped? If a file is being written, what happens if power gets weird?

These are not abstract architecture questions. These are "why is this thing frozen in my hand?" questions.

The public firmware is organized into subsystems because eventually it had to be. Hardware, UI, screens, IR, boops, MicroPython, OTA, LED runtime, identity, storage, and infrastructure all got their own homes. That structure was earned, mostly by discovering what happens when too many responsibilities live in one place and then you add a deadline, a battery, and 2,000 units.

The firmware is where the badge learned how to be playful without being fragile.

Mostly.

The badge is not a browser tab

Most of my recent software life has been in environments where memory is something you notice when the bill arrives, the page gets slow, or a process gets very dramatic in production.

Embedded work does not let you be that vague.

On paper, the badge has 16 MB of flash and 8 MB of PSRAM. It also has the ESP32-S3's 512 KB of on-chip SRAM, which is technically true in the same way that an apartment technically has floor space before you move in. By the time the runtime, stacks, radios, buffers, static data, and display code take their share, the actual headroom feels much smaller.

That sounds like a lot if you are thinking "tiny conference badge." It sounds like nothing if you are thinking "computer that runs a UI, games, Python apps, a file system, OTA updates, IR, LED animations, and Doom."

The useful mental model is that flash is the badge's persistent storage. It survives power loss and holds the firmware, OTA update slots, filesystem image, apps, data bundles, and Doom's resources. FatFS is a partition of that flash presented like a tiny disk, which is why MicroPython apps can feel like files you can inspect and edit even though underneath it is all still a carefully partitioned chunk of SPI flash.

Internal SRAM is the tiny fast workbench where the firmware keeps the things it needs right now: task stacks, driver state, Wi-Fi and TLS buffers, timing-sensitive code paths, and anything that really cannot tolerate being slow or weirdly placed. PSRAM is the bigger folding table next to it. It gives us breathing room for larger allocations like the MicroPython heap, app metadata, editor buffers, and Doom, but it is still external RAM, not a free substitute for internal SRAM.

The public firmware gives MicroPython a 2 MB heap from PSRAM. That is the friendly layer where people can write apps. But the native firmware still needs memory too: task stacks, display buffers, IR queues, JSON-ish state, app registries, file buffers, OTA metadata, Doom resources, and all the small allocations you do not think about until the badge starts behaving like it has developed opinions.

On the web, if you accidentally allocate a few extra objects in a render loop, maybe Chrome sighs at you. On the badge, you feel it immediately. A garbage collection pause is not just an implementation detail when the UI is trying to stay responsive and timing-sensitive hardware is still running.

So memory became a design material.

We reused buffers. We avoided giant temporary objects. We cared about whether something lived in internal RAM or PSRAM. We had to think about what survived reboot, what survived a firmware flash, and what would be wiped when the filesystem was replaced. We built helpers like GCTicker and DualScreenSession so MicroPython games could keep running without making garbage collection everyone else's problem.

This is also where I learned about MessagePack. MessagePack is a binary serialization format: it carries JSON-shaped data like arrays, maps, strings, numbers, and booleans, but encodes it as compact bytes, completely dropping the benefit of being human-readable text, while keeping all the other benefits of JSON. It exists for the moments when you still want something portable and language-friendly, but you care more about size and parsing cost than being able to open the payload in a text editor.

Before this project, I had almost exclusively reached for JSON because JSON is just what we all use. It is readable, debuggable, and extremely convenient. It is not what you want on a tiny device. The badge still generates JSON versions of the schedule, speaker, and floor data so humans can inspect the output, but the firmware consumes a MessagePack bundle instead. In the public data package, those JSON files are about 35.9 KB together; the packed bundle is about 20.6 KB. Saving roughly 43 percent on one data bundle is not life-changing on a laptop or server. On the badge, it was one more place where the project taught me that every comfortable default has a cost.

Doom wanted everything

The OLED framebuffer is only 1024 bytes, which is adorable right up until you remember that every byte has to be drawn, rotated, copied, or handed across a boundary at the right time. The IR receive queue is small enough that "read your frames promptly" is not a suggestion. The LED matrix is tiny, but animations still want timing.

Doom is probably the best way to explain how quickly the badge stopped feeling spacious. The shareware WAD, which is Doom's asset bundle, is 4,196,020 bytes. It does not live inside the firmware binary; it lives on the flash-backed FatFS partition next to the MicroPython apps and data files. Even there, it takes up about two-thirds of the badge's 6 MB filesystem partition and almost exactly one quarter of the entire 16 MB flash chip.

The compiled Doom code and static data contribute on the order of another 330 KB to the firmware, which is about 12 percent of the current firmware image, or about 8 percent of one OTA app slot. At runtime, Doom's zone allocator reserves 2 MB of PSRAM before you count the screen buffers, luma buffer, and OLED buffer. It also uses a 24 KB internal SRAM stack for its own FreeRTOS task. FreeRTOS is the little real-time operating system under the firmware; a task is its version of a thread.

And yes, we had to leave room for OTA. That was the part of the memory map that made the flash budget feel much less like "16 MB" and much more like "two carefully guarded parking spaces." The production partition table has two app slots, each about 3.875 MB, so the badge can keep the currently running firmware while writing the next firmware image into the other slot. The current firmware binary is about 2.8 MB, which is already around 68 percent of one slot. If the firmware grows past the slot size, OTA does not happen. It does not matter that there is technically flash elsewhere; the update has to fit in the slot.

This was one of the most difficult parts of the project for our entire team. It forced embedded humility.

Every allocation felt physical.

C++ as the kernel, MicroPython as the place I wanted to play

When I do hardware hacking for myself, I usually reach for MicroPython or CircuitPython. That is the layer where I feel fast and curious instead of precious. I can make an LED blink, read a sensor, draw something on a screen, and keep going before my brain has time to turn the whole thing into a software architecture dissertation.

So part of the badge goal was selfish in the best way: I wanted a surface where I could contribute comfortably.

But I also wanted that for everyone else.

Not everyone who gets excited by a weird piece of hardware wants to become an embedded C developer before they can make it do something personal. The badge needed a low-friction layer for people who wanted to write apps, make tiny games, animate the LEDs, draw on the OLED, use the IMU, trigger haptics, or send IR without rebuilding the firmware.

That is what MicroPython is for.

The trick was not "put Python on a badge." The trick was deciding what Python should never be responsible for.

C++ owns the scary stuff: timing-sensitive hardware, resource ownership, storage safety, recovery paths, native UI, device lifecycle, and the pieces that need to survive a Python script doing something ambitious. MicroPython gets the friendly APIs: draw text, set pixels, read buttons, move a cursor, rumble the haptics, send IR, store app state, write a little game.

That meant I also had to learn how to expose C++ functions as MicroPython functions. If MicroPython apps were going to feel like they belonged on the badge, they needed to use the same UI primitives as the native firmware: layout helpers, button prompts, icon drawing, storage helpers, input handling, and all the small pieces that make an app feel consistent instead of like a loose script that happened to run on the same hardware.

I did not expect to spend as much time as I did on glyphs.

At 128x64 pixels, a button icon is not just decoration. It is either legible or it is dust. We tested version after version of the tiny glyphs for the physical buttons because those shapes were part of the language of the badge. The first version used a Nintendo-style button layout. Then we swapped toward a PlayStation/Xbox convention. Then we discovered that most of us had already internalized the Switch version so deeply that the "more standard" mapping felt wrong, and we changed it back.

That is firmware work too. Not glamorous, exactly, but it is the difference between a hackable thing and a thing people can actually use.

For a tiny app, the badge can feel almost casual:

oled_clear()
oled_println("Hello, Replay")
oled_show()

led_override_begin()
led_show_image(IMG_HEART)
led_override_end()

You can connect over USB, use JumperIDE, inspect files, run scripts through the REPL, and iterate without treating the firmware like a locked box.

That is the part I care about most. The C++ runtime makes the badge stable enough to trust. MicroPython makes it personal enough to love.

Games, Doom, and hidden delight

The games were partly technical demos, partly love letters to weird handheld games, and partly a way to hide little moments of surprise inside the badge.

Replay attendees doing exactly what I hoped they would! Playing with the badges

I grew up loving Nintendo DS games that treated hardware constraints as creative prompts instead of limitations. Games like Henry Hatsworth and The World Ends with You were always doing something strange with two screens, odd controls, timing, and divided attention. The device shaped the play.

So once the badge had an OLED screen, joystick, buttons, accelerometer, haptics, and an LED matrix, my brain went directly to "what can this do that a normal screen cannot?"

That is how you end up with Flappy Asteroids: Flappy Bird on the lower LED matrix, Asteroids on the top OLED, and absolutely no mercy anywhere.

The current record is 27 seconds, which I understand as a number but not as a human achievement. I made the thing and I cannot reliably survive five.

Breaksnake, IR Block Battle, Synth, the drawing tools, the LED toys, the community apps — they all served the same purpose. They made the badge feel discoverable. I wanted people to keep finding things. A menu item. A hidden interaction. A weird little game. Something that made them turn to the person next to them and say, "wait, this does what?"

And then there is Doom.

Doom is funny because getting Doom running on strange hardware is almost a genre of engineering by itself. It is a joke, but it is also a test. Can the device handle input ownership? Can it render fast enough? Can it allocate the buffers? Can it pause the normal badge services and restore them afterward? Can the partition layout hold the WAD? Can release tooling distribute the pieces correctly?

On the badge, Doom runs as a guest mode. It takes over the screen and input, uses PSRAM for large buffers, renders a 160x100 view down to the 128x64 monochrome OLED, drives the LED matrix as part of the HUD, and then has to cleanly hand the device back when you are done.

That forced architectural honesty. Resource ownership stopped being theoretical once a 1993 game wanted to borrow the entire badge.

I highly recommend adding a ridiculous feature to your embedded project if you want to find out whether your abstractions are real.

Temporal flashing Temporal badges

Flashing one badge is a command.

Flashing thousands of badges is a distributed systems problem wearing a USB cable.

At some point, manually flashing badges stops being a developer workflow and starts being a production line. You need to detect devices, build firmware, prepare the filesystem image, flash in parallel, retry failures, verify boot, sync clocks, keep logs, and know which unit failed without squinting at a dozen terminal windows.

So I built Ignition.

Ignition is the Temporal-powered flashing system in the public repo. It runs locally, no cloud required, and uses Temporal workflows to orchestrate the build and flash pipeline. It can download the latest factory image from GitHub Releases, detect connected badges over USB, start child workflows per badge, flash firmware and apps in parallel, verify the badge booted, sync the clock, and show progress through workflow history and activity heartbeats.

The point was not that existing factory flashing tools are bad. The factory already has tools that can write bytes to chips very efficiently. Ignition wrapped that kind of work in a software-shaped control plane: retries, per-badge state, logs, boot verification, clock sync, and a visible history of what happened to each physical device. That is the difference between "we flashed a batch" and "we know which badges flashed, which ones failed, why they failed, and where to pick back up."

In other words, at some point the badge project became Temporal enough that we needed Temporal to ship the Temporal badge.

Which is objectively too on the nose, but I am choosing to embrace it.

The funny thing is that this was not just brand poetry. It was useful. Temporal gave us retries, status, history, and a durable mental model for a process that involved physical devices being plugged in and unplugged in batches. The same tool we talk about for long-running software processes turned out to be a pretty good fit for "please flash this table full of 32 tiny computers and tell me which ones survived."

And now that same tool is in the public repo. You can use it to flash one badge on your desk, which is calmer than what we were doing with it, but spiritually related.

The open-source victory lap

Getting the badge ready for open source was the victory lap after shipping these crazy things.

It was also a second engineering project.

Locally on my machine, this project lived in what I called the omni directory, which is exactly as ominous as it sounds. I have no idea how anyone else structured their copy of the work, but mine had firmware repos, hardware repos, prototype repos, QA firmware, flashing tools, event tooling, design assets, worktrees, specs, agent reports, old branches, website QA code, and the printing software I had to build for our badge generator all piled into one place.

Some of that belonged in the public artifact. Some of it very much did not. Some of it was useful context. Some of it was archaeology. Some of it was a reminder that every ambitious project creates a wake behind it.

So open sourcing the badge meant curating.

We had to remove private and event-only context. We had to make the docs usable. We had to separate source from generated artifacts. We had to package release images. We had to publish the hardware files in a form that was useful without dumping every temporary file a design tool had ever breathed on. We had to preserve licensing and third-party notices, especially because Doom brings its own legal furniture. We had to create a Community Apps path, contribution rules, and review checks so the badge could grow without turning into a tiny chaos machine.

We also had to decide what future contributors, human or AI, actually need to know.

One underrated part of the cleanup was producing a small memory layer for future agents. Not the whole project history. Not every false start. Not every conversation. Just enough context to know where the important code lives, which repos matter, what the architectural boundaries are, what old branches mean, and which parts should be treated as historical sediment instead of active direction.

That feels like a very 2026 kind of maintainability problem.

Open source is no longer only about code being available. It is about whether the next person, or the next coding agent helping that person, can arrive in the project and become useful before they get overwhelmed. As my colleague Cornelia Davis put it in a line that has been rattling around in my head for months: "We are no longer just teaching humans, we are teaching agents now."

The public repo is not the whole messy garage. It is the workbench after we cleaned it enough that someone else could actually build something there.

The second life of the badge

The badge did its job at Replay if it made people smile.

And something that made me smile — after all the hard work, seeing the badges in the wild hanging around attendees necks

It keeps doing its job if people keep changing it.

That was the whole point. We did not want to make 2,000 objects that felt magical for three days and then became drawer fossils. The badge has a second life because the firmware is open, the hardware files are there, the docs are readable, MicroPython is embedded, and the community app path exists.

Badge.temporal.io

You can reflash it. You can write an app. You can install community apps. You can inspect the hardware. You can try to manufacture one if you are feeling brave. You can make the LED matrix do something wonderful or cursed. You can build a tiny game. You can make an IR remote. You can find some corner of the device we did not fully explore and make it yours.

If the first life of the badge was surprise, I hope the second life is mischief.

Everything you need is at badge.temporal.io and all the code is up on GitHub ready for you to clone.

github.com/temporal-community/badge.temporal.io

We have also made updates since Replay, so even if your badge worked perfectly at the conference, you will want to update your firmware.

Flash it, fork it, write an app, inspect the hardware files, submit a PR with a Community App or a fix, or send us something weird enough that I have to stop what I am doing and try it. You can submit any cool stuff in this Slack channel.

We also have a few extras, and we will be sharing them with people at our San Francisco events over the next few months. So if you missed Replay, come find us.

There may still be a tiny hackable computer waiting for you to put your name on it.

Temporal AI Question Planetarium using Temporal Workflows

Shy Ruparel — Mon, 01 Jun 2026 17:23:38 +0000

Behind The Badge: How We Built 2,000 Hackable Badges For Temporal Replay

Shy Ruparel — Tue, 26 May 2026 04:00:00 +0000

At some point in December, Candace, our Head of Design, asked me: what if your time at Replay could be represented as a Workflow? Every check-in, every fun event, every person you met, a living timeline, running on Temporal.

Four months later, I'm coordinating manufacturing circuit board badges in Shenzhen over WhatsApp at 11 p.m., and I've hand-soldered more PCBs than I'd like to admit.

To understand why I was asked to figure out this project is to know that my role at Temporal has this informal understanding baked into it: give Shy the weird projects. The ones that involve breadboards on a kitchen table at 11 p.m., a document translation pipeline for toys, or a half-baked idea (or two, or three...) that could either be really cool or a complete disaster at a conference in front of 2,000 people.

The latter is this project where I set out to create badges for Temporal's annual developer conference, Replay.

The Concept Stage

I hit the ground running and started spec'ing it out. I could make one badge by myself, but to scale up to make a badge for everyone at Replay I knew I would need help. Through an introduction from some fellow Recurse Center alum, I found a hardware consultant and we put together a proposal.

Next, I had to pitch that proposal to Andrew Baker, our VP of Developer Relations, during his first five days on the job. Tricky because he didn't know me at all, but lucky for me, he trusted some DevRel guy with a hardware project budget that required convoluted manufacturing.

The early concept drawings are genuinely charming to look at now.

Our hardware consultant's early sketches are full of hand-drawn illustrations of attendees holding a chunky handheld device with a T9 keyboard, an e-paper name tag on the front, a kickstand so it could sit on a table. There's even a little Tamagotchi-esque character on the screen. The vision at that stage was something closer to a personal game console, or honestly a weird cell phone that only worked at Replay.

Then on to artistic inspiration. Our consultant came back with these stunning hand-drawn illustrations. It captures the spirit of what we were going for better than any spec doc ever could: it shows attendees gathered together, shrouded in a collective glow, illuminated by the feeling of knowledge and community. I'd even say the energy is a little cosmic.

This is just the type of energy we captured for the event, as Replay is the community's conference. We just get the privilege of paying for it. Finding ways for attendees to interact, share moments, learn from each other, and spark something in each other is always the actual goal. The badge is the vehicle taking you there.

What The Badge Does

When you hear "badge," you probably picture a rigid little plastic thing with your name and an outdated LinkedIn headshot on it. Scrap that entire notion when we're talking about this badge because this one is more like a game piece.

Attendees navigate Replay with a mission of gathering with their peers to traverse the cosmos of the development unknown. Along the way, they collect connections, unlock new levels, and even find hidden treasures, all while the badge handles the technical complexity involved underneath.

So what's actually inside it?

The badge runs on an ESP32-S3 microcontroller with a 128x64 pixel OLED screen, an IR transmitter and receiver, a joystick, buttons, haptic feedback via a vibration motor, and an LED matrix with programmable colors.

It also has a gyroscope, so the screen reorients depending on how you're holding it. Firmware is written in C, with a MicroPython layer sitting on top so attendees can write their own apps without needing to learn anything new. Attendees are able to update their contact information by using the MicroPython REPL and then beam it over to each other with the IR transmitter. The conference schedule is right there on the badge so you don't have to download an app. I don't know about you, but I've encountered very few conference apps that I've liked.

And this is what it became after Kathy, our Senior Brand Designer, got involved. The back of the badge has Ziggy, our tardigrade mascot, as an astronaut, which I love, etched into a PCB.

The AI Of It All

I have to tell you something, and I want you to keep it just between us... I never wrote firmware code before this project. Like ever.

Now, I'm a decent enough programmer and I know how to have an architecture conversation with the best of 'em. I can confidently identify when something is going wrong and I know the right questions to ask to reveal a solution, but C firmware for an embedded microcontroller wasn't something I had ever done professionally.

My testimony is this: generative AI made this project possible for me!

I used Claude and Claude Code extensively throughout my development process, eventually swapping to Codex as newer models became available. The way I think about it: I became a full-time architect with access to a team of very high int, low wisdom junior engineers who are great at implementation but need a lot of hand-holding. You can't give them something vague. You have to know what you want, know when they've gotten it wrong, and stay deliberate about what you let them build. I genuinely don't think this workflow would have worked without my ten-plus years of developer experience behind it because the experience tells you which questions matter and when to push back.

The codebase ended up around 5,000 lines of production logic, with tests more than quadrupling that. I used those tests as a way to validate what the AI was building and build trust in the output. I would record and review Playwright tests to confirm user interactions worked the way I wanted them to. I'll admit, when I code without AI, I mostly skipped writing tests in all my previous work. For me to have trust in the code that was getting generated, I needed extremely solid test coverage from the start.

The documentation from all the architecture debates I had with the AI, the back-and-forth about structure, what to build, and what to cut, is over 21,000 lines, managed through GitHub Spec Kit that tracked specs and architecture decisions as the project evolved. That ratio says something interesting about what the job actually looks like now. It was very out of my comfort zone as someone with a CS degree and a full career without any AI tools even existing. As this project took four months, I swapped my tooling quite a bit. I finalized the project leveraging Codex with the Grill Me Skill. It was a lot more reminiscent of wordsmithing an English essay than anything hands-on-keyboard, which I'm still adjusting to.

Something for you to look forward to: the whole codebase is open source! That means you'll be able to see the output of every argument I had with AI to get here! and the crowd goes wild

From One To Two Thousand

Now, I've built weird IoT stuff before. In fact, that's kind of my whole thing. But I've never had to build 2,000 of the same thing, and it turns out those are completely different problems.

The original inspiration for this whole category of badge, ours, Twilio's, GitHub's, traces back to DEF CON, the hacker conference in Las Vegas. They've been doing programmatic badges for over twenty years. The badges run cryptography puzzles, communicate with each other, and unlock hidden games. Last year's badge had a full Pokemon clone where you could walk around a virtual version of the convention center. The level of engineering that community pours into these things is genuinely absurd in the best way, and I have a lot of love for it. I used to go when I was back in college during the era of Ryan "LostboY/1o57" Clarke making all the conference badges, and my memories here helped guide a lot of the creative energy I poured into this project.

I had a lot of guidance too. Pimoroni, the team behind the GitHub Universe badge, were also incredibly generous. They couldn't meet our timeline but they sat with me anyway and gave me advice, so this is a huge shout out to them. Their work inspired me and the updated Badgeware ecosystem served as my prototyping platform to prove that I could pull this off. Their contributions helped us get here.

On the manufacturing side: I knew, at least in an abstract way, that hardware companies manage factory relationships through WhatsApp and that most electronics manufacturing happens in Shenzhen. Actually living that is something else. I'd start getting messages from the factory at 10 p.m. I'd answer until I fell asleep. I'd wake up and our west coast based hardware consultant had been chatting with them for another four hours on top of that. You're always catching up, always a little behind.

Our manufacturer, Elecrow, was incredibly generous with their time and expertise, helping us solve the problems that came up throughout this entire process. I'm especially grateful to our account manager, Chris, who not only stepped up to make sure everything worked, arrived safely, and showed up on time, but also helped us get the most out of our time in Shenzhen. She did double duty, guiding us through all the electronics markets Shenzhen is known for.

Sourcing LiPo batteries in bulk is harder than you'd think because you can't air ship them, so everything goes ground, and vendors get suspicious when you try to order large quantities at once. This resulted in our dev kits running off triple A batteries. Getting enough screens for the dev kits turned into placing about 30 separate Amazon orders across different sellers to work around quantity throttling. Our accounting team is going to have feelings about that for a while... sorry guys.

There's also the China trip. Temporal's security policy doesn't allow company compute into the country, which is reasonable, so when I needed to go supervise manufacturing, it required multi-week negotiations between HR, security, and finance to work out.

The answer turned out to be a clean MacBook and a clean phone provisioned specifically for the trip, access to exactly one Slack channel, and no corporate accounts. I had to say goodbye to Claude for the duration, which means I had to go back to the ways of ye olden days, pre-2023, for the development, which definitely made the firmware work interesting.

That setup was the right call, but it did mean that once I was in China, I was mostly on my own for anything that came up. Between the limited access, the timezone gap, and the fact that problems were being discovered in real time on the manufacturing floor, there was not much opportunity to phone a friend. I got one hour-long call to get help on a specific issue, and otherwise the last-minute problems had to be debugged with whatever I had with me in the moment.

Meanwhile, my single allowed Slack channel basically turned into a mini travel blog: factory floors, production lines, electronics markets, and a steady stream of "look at this, manufacturing is magic and also chaos." It was useful for keeping people in the loop, but it was not exactly the same thing as having the full company brain available while trying very hard not to become the bottleneck between "we found a problem" and "thousands of these need to ship."

Here are a few photos of what went down on my trip.

Now, I'm back, the badges were in tow, and I was excited to get them in your hands at Replay.

It's In Your Hands At Replay! And Beyond

We live in a hyper-consumerist world, and we don't want to pile on to that by creating a bunch of e-waste.

So the badge isn't e-waste when the conference ends. That was a hard constraint from the start: we're not building 2,000 things that get thrown in a drawer after three days. Because the firmware is open source and MicroPython is embedded, you can keep hacking on yours after Replay.

The sky's the limit really. The IR sensor means you could build a universal remote, the screen and joystick give you a tiny game device, and it'll keep being whatever you make it.

People also started hacking on the firmware almost immediately. One attendee built a full Tamagotchi game during the conference. That's exactly the kind of thing we hoped for: someone picking up the hardware and immediately thinking cool, what can I make this do?

For next year, I want to shift from the ESP32-S3 to the Raspberry Pi RP2350 and have every badge function as a Temporal worker. We managed to get Temporal's Rust SDK running on the badge thanks to Edward Amsden, Staff Software Engineer on the SDK Language Runtime team, who saw me demo the badge during an engineering sprint showcase in his first week at Temporal and then casually spent the weekend hacking together Rust SDK support for us. I more or less seconded him to the badge team for his first month with us so we could get the project over the finish line. SDK team, I promise you can have him back now that we're finished with Replay. Because Edward got Temporal running in the final weeks of the project, we didn't have enough time to really showcase what we could do with it. Next year, though: two thousand workers hanging around people's necks in the same room. I don't know what I'd run on them yet, but I very much want to find out.

We also made a bunch of deeply weird games for the badge, because apparently once you put an OLED screen, joystick, accelerometer, LED matrix, Wi-Fi, and a questionable amount of ambition into something people wear around their necks, then put a person who spent far too much time playing The World Ends with You and Henry Hatsworth on the Nintendo DS in their youth in charge of the project, aka me, this is what happens. Some are real games, some are firmware tests that got out of hand, and at least one is Flappy Asteroids: Flappy Bird on the lower LED matrix, Asteroids on the top, and absolutely no mercy anywhere. If you survived for more than 30 seconds at Replay, I hope you got your special variant joystick cap. And yes, we got Doom running.

2,000+ badges showed up and worked. If you want to get hands-on with yours, everything you need is at badge.temporal.io, and if you missed out this year, make sure you come to one of our SF events over the next few months and attend Replay 2027!

Why I needed Durable Execution to Read a Toy Manual

Shy Ruparel — Fri, 10 Apr 2026 15:53:01 +0000

Watch me take a Japanese toy manual and turn its translation into a bulletproof, AI-powered ETL pipeline. I’ll show you how I use Temporal Workflows to guarantee an AI pipeline never loses progress, surviving network failures, API crashes, and more.

What You'll Learn

Why Spider-man is the reason that Power Rangers has a giant robot.
Guaranteed Completion with Temporal: I’ll show you how to ensure your code keeps running even if servers crash or APIs fail.
Parallel OCR & Translation: Learn how I used a "fan-out" pattern with Google Document AI to process a 20-page manual in 50 seconds instead of 10 minutes.
Resilient AI Cleanup: See how I use Pydantic and Temporal together to handle non-deterministic LLM outputs from Gemini and automatically retry failed validations.

Ready to build it yourself? 👉 Check out the code here!

Tracking Global Vaccination Rates with Docker, Python, and IoT

Shy Ruparel — Tue, 29 Mar 2022 17:19:09 +0000

I'm a major fan of the ESP32-S2 platform of low-power, low-cost, Wi-Fi capable microcontrollers. Adafruit specifically sells a variant that features a 2.9' E-ink display and Python support, called the MagTag. I'm not ashamed to admit I have far too many of these things littered across my apartment.

One of my favorite organizations is Our World in Data (OWID). They work with thousands of researchers to make research and data accessible to the public. In particular, I've been closely watching their repo that tracks COVID vaccination rates. As numerous worldwide agencies update their vaccination rate metrics, OWID consolidates that data into a single JSON file.

The combination of the MagTag and OWID's data set inspired my first project as the newest member of Docker’s DevRel team. I decided to turn the MagTag into a display for the specific OWID I’m following. However, I ran into a few problems while getting started.

OWID uploads its JSON data collection to GitHub as a raw JSON (or CSV) file, rather than serving it over an API endpoint. The total payload is also 34MB. While that doesn't seem huge, the MagTag itself has just 4MB of flash storage and 2MB of PSRam. That's nowhere near enough memory to parse all that data. Luckily, I commandeered a few spare Raspberry Pi's to create a data processing layer. Using Python, I’m able to spin up a quick Flask server to process the image—and because of Docker, I can deploy a containerized service to my Raspberry Pi in just a few seconds.

My Pi pulls an image built for Armv7 from Docker Hub. That container creates an API endpoint that’s accessible on my local network. From there, the MagTag can request a country's data from the Pi. The Pi grabs the most recent JSON file from OWID, pulls out just the information the MagTag is looking for, and then passes it along. This method reduces the data payload from 34MB down to the KB range, which is much more manageable for an IoT device.

That said, let’s dive into the code.

Coding Your Solution

If you'd rather just read the code, head over to GitHub or Docker Hub for deployment instructions.

Data processing

Knowing that the Raspberry Pi’s data processing function would be pretty lightweight, I decided to spin up a Flask server—taking advantage of Flask's built-in ability to handle JSON with jsonify. The requests library for grabbing our data from OWID was also pretty handy:

# Setup a health route to check if the service is up
@app.route("/")
@app.route("/health")
def hello():
    response = jsonify({"status": "api online"})
    response.status_code = 200
    return response

Secondly, and more importantly, is your route to hit the OWID dataset. This route parses the 34MB JSON file for the requested ISO code, retrieves the most recent data, and formats it for the Raspberry Pi:

# Setup a GET route for requesting the data of the requested ISO Code.
@app.route("/iso_data/<iso>", methods=["GET"])
def iso_data(iso):
    # Get the OWID Data from GitHub
    vaccination_url = "https://raw.githubusercontent.com/owid/covid-19-data/master/public/data/vaccinations/vaccinations.json"
    try:
        vaccinations = requests.get(vaccination_url)
    except:
        return "False"

    vaccinations_dict = {}
    # Using lambda and filter to find our requested ISO Code
    item = list(filter(lambda x: x["iso_code"] == iso, vaccinations.json()))
    if item:
        item = item[0]
        # If data is found format it for our response.
        vaccinations_dict = {
            "data": item["data"][-1],
            "iso_code": item["iso_code"].replace("OWID_", " "),
            "country": item["country"],
        }
        response = jsonify(vaccinations_dict)
        # Returning a 203 since it's a mirror of the OWID data.
        response.status_code = 203
    else:
        # If no data is found return a 404.
        response = jsonify(
            {"status": 404, "error": "not found", "message": "invalid iso code"}
        )
        response.status_code = 404
    return response

Lastly, you should get the code to install the dependencies and generate a requirements file. I use pyenv to manage my Python virtual environments, but you substitute that with your preferred method.

pyenv virtualenv 3.10.1 flask-owid-server
pyenv activate flask-owid-server
pip install flask requests
pip freeze > requirements.txt
flask run

Next, open a new shell prompt and make a curl request to the Flask server, just to confirm that everything is running as expected.

curl localhost:5000
curl localhost:5000/iso_data/USA

Dockerizing and Deploying the Flask Server

With a functional Flask server, we can dockerize it and simplify the app-deployment process for the Raspberry Pi. I started by creating a Dockerfile.

#Use the python 3 base image.
FROM python:3-slim
#Expose ports
EXPOSE 5000
# Setup work directory.
WORKDIR /app
# Copy the requirements file to the container and the install dependencies.
COPY requirements.txt /app
RUN pip3 install -r requirements.txt --no-cache-dir
# Copy all the code into the container/
COPY . /app
# Spin up our flask server.
ENTRYPOINT ["python3"]
CMD ["app.py"]

With this Dockerfile in place, I can run a Docker build command to create my image.

docker build --tag {yourdockerusernamehere}/flask-owid-parser:latest .

You can run your newly-created image from Docker Desktop—while making sure you name the container and set the local port to 5000.

If you prefer using the command line, something like Docker CLI can achieve the same effect.

docker container run --publish 5000:5000 --detach --name flask-owid-parser {yourdockerusernamehere}/flask-owid-parser

Once again, make a curl request to localhost:5000 to confirm that everything is running correctly.

With everything verified on your machine, you can build the application to run on a Raspberry Pi. The Raspberry Pi 3 Model B from this example uses the armv7 platform, so I can create a build specifically targeting armv7. By running this build on my MacBook, the build time will be substantially faster than on my Raspberry Pi.

docker build --platform linux/arm/v7 -t {yourdockerusernamehere}/flask-owid-parser:armv7 .

Back in Docker desktop, you can push your armv7 build to Docker Hub.

Head over to Docker Hub to confirm the armv7 build is displayed correctly.

SSH into your Raspberry Pi to start deploying this code. If you haven't already installed Docker, you can view our documentation for instructions on getting started with Docker on the Pi.

Next, pull the armv7 image from Docker Hub and run it on the Raspberry Pi.

docker pull {yourdockerusernamehere}/flask-owid-parser:armv7
docker run -d -p 5000:5000 --name flask-owid-parser {yourdockerusernamehere}/flask-owid-parser:armv7

Back on my original MacBook, I can both confirm that the server’s running and that it's accessible from my local network—via one final curl request. The default hostname on a fresh Raspberry Pi OS install is raspberrypi, so any Raspberry Pi running Pi OS automatically responds to raspberrypi.local. If that doesn't work for you, swap raspberrypi.local with your Raspberry Pi’s IP address.

ping -c 3 raspberrypi.local
curl raspberrypi.local:5000
curl raspberrypi.local:5000/iso_data/USA

Configuring the MagTag

One of my favorite MagTag features is its Circuit Python support. Forget using pip to install dependencies. Instead, simply copy .mpy onto the MagTag via USB alongside your code. To set up a MagTag for the first time, I'd defer to the excellent tutorials put together by the folks over at Adafruit.

To install this project on your MagTag, visit the GitHub repo (https://github.com/Shy/Docker-MagTag-OWID/tree/main/magtag) containing this project’s code. Drag all code from the MagTag directory onto your MagTag via USB.

If you inspect the code.py file, you'll notice that the MagTag is configured to connect to the Raspberry Pi.

# Build our endpoint
endpoint_iso_first = "http://raspberrypi.local:5000/iso_data/{}".format(
    secrets["iso_first"]
)

Update the secrets.py file to include the information for your own Wifi network. Ensure that your MagTag and Raspberry Pi share the same network.

Reboot the MagTag to see the most recent information—posted by the folks at Our World in Data.

Head over to GitHub to find the full source code for this project with dependencies, and links to the image on Docker Hub. First-time Python and Docker users should browse our quick start tutorial for Python devs.

App hosting with the Contentful App Framework

Shy Ruparel — Wed, 23 Jun 2021 14:52:04 +0000

I'm cross-posting this article for my Colleague David Fateh. Check out the original post over on the Contentful Blog.

When you develop an app for Contentful using the App Framework, you create a single-page application that runs inside an iframe and shows up in the Contentful UI. Previously, hosting an app on the App Framework was only possible through third-party solutions. Today, we are announcing an easier method to host your app called app hosting!

App hosting takes the hassle out of finding a hosting provider for your app. We have provided developers with a tool to upload their application in bundles which provides for many great development features.

An app bundle is your single-page application directory. Each bundle should contain at least an index.html file, which will serve as the main entry point for your application to load. A typical bundle's file tree will look something like this:

build
├── index.html
└── static
    ├── css
    │   └── index.css
    └── js
        └── index.js

Where build is your root directory and, inside it, there is an index.html file, along with any assets such as CSS and JavaScript that would get loaded alongside your index.html file.

While there are many ways to create apps, we provide a quickstart tool, the create-contentful-app, which can get you a jump-start on your app. If you aren't familiar with building apps, I'd suggest checking out our livestream where Felix and I build the Contentful starter tutorial app.

Now, let's take a look at the three easy steps to bundling and hosting your own app.

Step 1

If you built your app using the create-contentful-app or create-react-app, you can simply run

npm run build

If you built your app using another tool or from scratch, your directory structure will need a minimum of an index.html file at the root.

Again, a simple app directory structure would look something like this:

build
├── index.html
└── static
    ├── css
    │   └── index.css
    └── js
        └── index.js

Step 2

Navigate to your app's AppDefinition found in your organization settings.

Step 3

Toggle the app hosting option found under "Frontend" and drag and drop your build directory into the highlighted area like so:

"/>

That's it! Your app is now hosted via Contentful. In the Bundles tab, you can check out multiple build versions and revert to an older version of your app in case you need to roll back changes.

While uploading an app is easy, there are some common errors that could occur:

Your app doesn't have an index.html file in the root of the uploaded bundle.
You are uploading a Zip that encapsulates the root directory instead of the content directly. Most of the time, the common fix is to navigate into your root directory, select all your files, and zip it at that level.
Your upload succeeds but the app doesn't load or appear in the UI. This could be caused by an error in your app's index.html or the JavaScript that it executes. A look at the developer console should provide some hints.

To learn more about the technical details of app hosting, head over to our documentation.

Launching app hosting on Contentful is another step forward in our vision of creating an extensible and cohesive set of tools that connect our projects and our content. If you want to chat about what you're working on, feel free to ping me on our community Slack where I work with fellow developers as we take steps to make our App Framework more accessible and versatile for everyone.

How to build a multi-location app for the Open Graph protocol

Shy Ruparel — Wed, 23 Jun 2021 14:44:09 +0000

I'm cross-posting this article for my Colleague David Fateh. Check out the original post over on the Contentful Blog.

If you are a content creator for the web, you may have used the Open Graph protocol. The Open Graph protocol is a way to display and share information about your resource on the internet. You may have seen these in action when sharing websites and URLs on Twitter and Facebook, or when you are chatting with your coworkers on Slack. The preview and metadata for the link is shown to the user as in the Twitter post below.

Building an app on the App Framework can be as simple as creating a single custom button or as complicated as composing multiple components in different locations of Contentful. I want to run through an example app I've created which makes use of the App Framework's ability to handle complexity, but more importantly shows how to pass data between different app locations.

In Contentful, we can create our own Open Graph data by making use of a simple content type that provides the user with the necessary fields to show these kinds of previews. Then, using the App Framework, we can augment the editor experience to allow for automated title generation of our content as well as a visual preview.

In this post, we will cover a two things: 1. Creating a content type to handle simple Open Graph data. 2. Creating an app which helps visualize the data and allows for a preview mode. 3. When all is said and done, our Open Graph content type will still need to be pulled from a Contentful API response when we generate our web pages. The information contained in an Open Graph entry will be enough information to populate meta tags in the head of our HTML filles. Let's get started!

Creating the content type

We can start by creating a new content type in our space called "Open Graph," which will have five fields:

Title: short text
Content: single reference (in our case, referencing blog posts)
Type: short text
Image: media
URL: short text

This content type does a few things. First, it allows editors to pick a reference entry. In many cases, this could be a blog post, web page, link or other type of media. In our example, we will be using the Open Graph content type in a blog. This means our Content reference field will reference "Blog Post" content types.

Second, we can automate the "Title" field by asking the editor to select a blog post and grabbing the title from that post. This is something we will look at when we dive into the code.

Lastly, we can create a custom button that will show the editor a preview of our Open Graph data as it might appear in a card UI such as Twitter or Facebook.

Now that we have our content type set up, let's start developing our app.

Creating the app

For those that are familiar with the App Framework and want to see the source code of the app, you can see it here on GitHub. For those less familiar, I've written a few tutorials in the past about how to build apps. We also have a tutorial for beginners, Building your first app, where we explain all the necessary steps to get up and running.

An app is a single page application that runs inside of an iframe and can be rendered in different locations inside of the Contentful Web App. While building an app can be done using any framework (or lack thereof), I'm going to use the Create Contentful App CLI tool, which will bootstrap a React app with all the necessary logic required to get up and running inside of Contentful.

To initialize and run our app locally, run these commands in your terminal:

npx @contentful/create-contentful-app init open-graph
cd open-graph
npm start

The app is now running as a single page application on http://localhost:3000. In order to see our app in Contentful, we will need to create an AppDefinition and assign our app to show up in the correct locations.

Creating the AppDefinition

An AppDefinition is the entity that represents an app in Contentful. It contains general app information, like where it is visible. It also provides settings that enable it to run independently, or enable particular settings for any current and future installations.

Note: In order to create an AppDefinition, you must be a Contentful organization admin or developer. If you are not, you can ask your admin for access or sign up for a free Contentful account to use as a sandbox.

Let's create a new AppDefinition. Go to your organization settings. In the top menu, select Apps. From here we will create a new AppDefinition with the following properties:

Name: Open Graph
App URL: http://localhost:3000 (remember this is running on our machine)
First location: Field - short text
Second location: Page

Once filled in, hit the Create button in the top-right corner. Next, let's install our app into the space where we created our Open Graph content type.

Installing and developing the app

To install the app, head over to the space where we created our Open Graph content type. In the Apps menu bar, click "Manage apps" then find the Open Graph app in the list of available apps (it will show up with a private tag next to it). Click Install.

Once our app is installed, it is ready to be assigned to our Open Graph content type. Navigate to the Content Model page and select the Open Graph content type. In there we will modify the settings of our "Title" field by navigating to the appearance area selecting our Open Graph app. Click save.

Now, create a new Open Graph entry to see how the app renders. We can see that our app is rendering by the message that is showing up in our Title field. Of course, we'd like it if our title field actually showed a title instead of a developer message, so at this point it is time to dive into the code that was created earlier by our create-contentful-app CLI tool.

To start, create a field that shows a title based off of the reference blog post in our Content field. To get this functionality, we will make use of Forma 36 --- the Contentful Design System to implement UI elements which have the same look and feel as Contentful itself. We're going to use a TextInput which will be disabled for manual editing but will automatically pull the title information from our content reference field.

In our code, modify src/components/Field.tsx to create a better experience.

To start, import a few libraries that come out of the box when we ran the create-contentful-app CLI commands:

import React, {useState, useEffect} from 'react';
import tokens from '@contentful/forma-36-tokens'
import { TextInput, Note, Button } from '@contentful/forma-36-react-components';
import { FieldExtensionSDK } from '@contentful/app-sdk';

We are using React here for our UI. Tokens is a Forma 36 utility that will provide us with certain variables like color and sizing. The Forma 36 components also come out of the box and will be useful for constructing our UI. Since we are using TypeScript, I'm also including the SDK typings by default.

Next, we'll want to modify the component itself to handle state, pull information from another field and render some UI.

First, create some state:

const Field = (props: FieldProps) => {
  // Get the title of the field and create a setter
  const [title, setTitle] = useState(props.sdk.field.getValue() || null);

Next, listen for changes to our content reference field. When the content field has been populated with data, grab the entry, find the title and set that as the title in state. Also save that as the title field's value in the Open Graph content type.

  useEffect(() => {
    // Resize the field so it isn't cut off in the UI
    props.sdk.window.startAutoResizer();

    // when the value of the `content` field changes, set the title
    props.sdk.entry.fields.content.onValueChanged((entry) => {
      if (!entry) {
        setTitle(null);
        return;
      }

      // The content field is a reference to a blog post.
      // We want to grab that full entry to get the `title` of it
      props.sdk.space.getEntry<BlogPost>(entry.sys.id).then((data) => {
        if (data.fields.title['en-US'] !== title) {
          const title = data.fields.title['en-US'];
          setTitle(title);
          props.sdk.field.setValue(title);
        }
      });
    });
  });

Last, we can render our UI based on the above logic to give editors some validation hints. We can either warn that a reference needs to be picked, or if a reference is picked, to use the correct title information in our field. We are also going to include a button, which will open up our page location by passing the entry's ID. We will touch on that more below.

  if (title === null) {
    return <Note noteType="warning">Link a blog post below to assign a title.</Note>
  }

  return (
    <>
      <TextInput disabled value={title} style={{marginBottom: tokens.spacingM}}/>
      <Button onClick={() => props.sdk.navigator.openCurrentAppPage({path: `/${props.sdk.entry.getSys().id}`})} buttonType="naked">Preview Open Graph</Button>
    </>
  );
};

Our full component code looks like this now:

import React, {useState, useEffect} from 'react';
import tokens from '@contentful/forma-36-tokens'
import { TextInput, Note, Button } from '@contentful/forma-36-react-components';
import { FieldExtensionSDK } from '@contentful/app-sdk';

interface FieldProps {
  sdk: FieldExtensionSDK;
}
// Custom type to denote a blog post content type
interface BlogPost {
  sys: {
    id: string;
  };
  fields: {
    body: object;
    title: {
      'en-US': string;
    };
  };
};

const Field = (props: FieldProps) => {
  // Get the title of the field and create a setter
  const [title, setTitle] = useState(props.sdk.field.getValue() || null);

  useEffect(() => {
    // Resize the field so it isn't cut off in the UI
    props.sdk.window.startAutoResizer();

    // when the value of the `content` field changes, set the title
    props.sdk.entry.fields.content.onValueChanged((entry) => {
      if (!entry) {
        setTitle(null);
        return;
      }

      // The content field is a reference to a blog post.
      // We want to grab that full entry to get the `title` of it
      props.sdk.space.getEntry<BlogPost>(entry.sys.id).then((data) => {
        if (data.fields.title['en-US'] !== title) {
          const title = data.fields.title['en-US'];
          setTitle(title);
          props.sdk.field.setValue(title);
        }
      });
    });
  });

  if (title === null) {
    return <Note noteType="warning">Link a blog post below to assign a title.</Note>
  }

  return (
    <>
      <TextInput disabled value={title} style={{marginBottom: tokens.spacingM}}/>
      <Button onClick={() => props.sdk.navigator.openCurrentAppPage({path: `/${props.sdk.entry.getSys().id}`})} buttonType="naked">Preview Open Graph</Button>
    </>
  );
};

export default Field;

Now that we have a field that can automatically pull a title from the referenced blog post, we also want to build out a page location, which will show a preview of the Open Graph to editors when they click the preview button. The button is under our Title and says "Preview Open Graph." This button will direct us to our page location which we will create soon.

Let's start by modifying our src/components/Page.tsx file. Again, we are going to import a few things from Forma 36 in order to build a nice preview UI for our Open Graph components.

import React, { useState, useEffect } from 'react';
import {
    Card,
    Note,
    Heading,
    Paragraph,
    Typography,
    TextLink,
    Button,
    SkeletonBodyText,
    SkeletonContainer,
    SkeletonDisplayText,
} from '@contentful/forma-36-react-components';
import tokens from '@contentful/forma-36-tokens';
import { PageExtensionSDK } from '@contentful/app-sdk';

In the Page component, check the URL parameters that we passed in when the editor clicked the button:

const Page = (props: PageProps) => {
    // false indicates an error occurred
    // otherwise the entry is loading or loaded
    const [entry, setEntry] = useState<OpenGraphPreview | false>();

    useEffect(() => {
        // Get the entry ID which is passed in via the URL
        const entryId = props.sdk.parameters?.invocation?.path.replace('/', '');

        // If no entry ID exists, show an error message by setting content to false
        if (!entryId) {
            setEntry(false);
            return;
        }

We use sdk.parameters.invocation.path to access the custom path in the URL of our app, which was passed in by sdk.navigator.openCurrentAppPage from our field component as the on click function of the button.

Now, complete the useEffect function with some network calls to get all the data we need to display the preview:

        // Get the entry data by getting the linked asset and content body
        props.sdk.space.getEntry<OpenGraphEntry>(entryId).then((data) => {
            Promise.all([
                // Grabs the Image asset of the Open Graph content type
                props.sdk.space.getAsset<Asset>(
                    data.fields.image['en-US'].sys.id
                ),
                // Grabs the long text body of the blog post
                props.sdk.space.getEntry<Content>(
                    data.fields.content['en-US'].sys.id
                ),
            ]).then(([asset, content]) => {
                // combine the data from the two `space` calls
                setEntry({
                    title: data.fields.title['en-US'],
                    imageUrl: asset.fields.file['en-US'].url,
                    previewBody: content.fields.body['en-US'],
                    url: data.fields.url['en-US'],
                    id: entryId,
                });
            });
        });
    }, []);

Notice that we're using Promise.all to get data about the entry and the image asset which we will use in our preview.

Now render the component UI:

    if (entry === false) {
        return <Note noteType="negative">Error retrieving entry!</Note>;
    }

    return (
        <div
            style={{
                display: 'flex',
                width: '100%',
                height: '100vh',
                alignItems: 'center',
                marginTop: tokens.spacingXl,
                flexDirection: 'column',
            }}
        >
            <div style={{ justifyContent: 'center' }}>
                <SkeletonContainer>
                    <SkeletonDisplayText numberOfLines={1} />
                    <SkeletonBodyText numberOfLines={3} offsetTop={35} />
                </SkeletonContainer>
            </div>
            <Typography>
                <Heading>
                    Open Graph Preview
                </Heading>
            </Typography>
            <Card style={{ width: '260px' }}>
                {!entry ?
                <SkeletonContainer>
                    <SkeletonDisplayText numberOfLines={1} />
                    <SkeletonBodyText numberOfLines={3} offsetTop={35} />
                </SkeletonContainer> :
                <>
                    <Typography>
                        <TextLink href={entry.url}>{entry.title}</TextLink>
                        <Paragraph>{entry.previewBody}</Paragraph>
                    </Typography>
                    <img src={entry.imageUrl} alt="" style={{ width: '200px' }} />
                </>}
            </Card>
            <Button
                buttonType="muted"
                disabled={!entry}
                onClick={() => props.sdk.navigator.openEntry(entry!.id)}
                style={{ margin: `${tokens.spacingXl} 0` }}
            >
                Back to entry
            </Button>
            <div style={{ justifyContent: 'center' }}>
                <SkeletonContainer>
                    <SkeletonDisplayText numberOfLines={1} />
                    <SkeletonBodyText numberOfLines={10} offsetTop={35} />
                </SkeletonContainer>
            </div>
        </div>
    );
};

For the most part, I am using Skeleton components, which are for looks; they show a loading preview. The Card component is used for actually displaying the content in the Open Graph card. All together, the Page component code looks like this:

import React, { useState, useEffect } from 'react';
import {
    Card,
    Note,
    Heading,
    Paragraph,
    Typography,
    TextLink,
    Button,
    SkeletonBodyText,
    SkeletonContainer,
    SkeletonDisplayText,
} from '@contentful/forma-36-react-components';
import tokens from '@contentful/forma-36-tokens';
import { PageExtensionSDK } from '@contentful/app-sdk';

interface PageProps {
    sdk: PageExtensionSDK;
}

// An open graph content type
interface OpenGraphEntry {
    fields: {
        title: {
            'en-US': string;
        };
        type: {
            'en-US': string;
        };
        url: {
            'en-US': string;
        };
        image: {
            'en-US': {
                sys: {
                    id: string;
                };
            };
        };
        content: {
            'en-US': {
                sys: {
                    id: string;
                };
            };
        };
    };
    sys: {
        id: string;
    };
}

// A custom shape for the entry we are going to render in our UI
interface OpenGraphPreview {
    id: string;
    title: string;
    imageUrl: string;
    previewBody: string;
    url: string;
}

interface Content {
    fields: {
        body: {
            'en-US': string;
        };
    };
}

interface Asset {
    fields: {
        file: {
            'en-US': {
                url: string;
            };
        };
    };
}

const Page = (props: PageProps) => {
    // false indicates an error occurred
    // otherwise the entry is loading or loaded
    const [entry, setEntry] = useState<OpenGraphPreview | false>();

    useEffect(() => {
        // Get the entry ID which is passed in via the URL
        // @ts-ignore
        const entryId = props.sdk.parameters?.invocation?.path.replace('/', '');

        // If no entry ID exists, show an error message by setting content to false
        if (!entryId) {
            setEntry(false);
            return;
        }

        // Get the entry data by getting the linked asset and content body
        props.sdk.space.getEntry<OpenGraphEntry>(entryId).then((data) => {
            Promise.all([
                // Grabs the Image asset of the Open Graph content type
                props.sdk.space.getAsset<Asset>(
                    data.fields.image['en-US'].sys.id
                ),
                // Grabs the long text body of the blog post
                props.sdk.space.getEntry<Content>(
                    data.fields.content['en-US'].sys.id
                ),
            ]).then(([asset, content]) => {
                // combine the data from the two `space` calls
                setEntry({
                    title: data.fields.title['en-US'],
                    imageUrl: asset.fields.file['en-US'].url,
                    previewBody: content.fields.body['en-US'],
                    url: data.fields.url['en-US'],
                    id: entryId,
                });
            });
        });
    }, []);

    if (entry === false) {
        return <Note noteType="negative">Error retrieving entry!</Note>;
    }

    return (
        <div
            style={{
                display: 'flex',
                width: '100%',
                height: '100vh',
                alignItems: 'center',
                marginTop: tokens.spacingXl,
                flexDirection: 'column',
            }}
        >
            <div style={{ justifyContent: 'center' }}>
                <SkeletonContainer>
                    <SkeletonDisplayText numberOfLines={1} />
                    <SkeletonBodyText numberOfLines={3} offsetTop={35} />
                </SkeletonContainer>
            </div>
            <Typography>
                <Heading>
                    Open Graph Preview
                </Heading>
            </Typography>
            <Card style={{ width: '260px' }}>
                {!entry ?
                <SkeletonContainer>
                    <SkeletonDisplayText numberOfLines={1} />
                    <SkeletonBodyText numberOfLines={3} offsetTop={35} />
                </SkeletonContainer> :
                <>
                    <Typography>
                        <TextLink href={entry.url}>{entry.title}</TextLink>
                        <Paragraph>{entry.previewBody}</Paragraph>
                    </Typography>
                    <img src={entry.imageUrl} alt="" style={{ width: '200px' }} />
                </>}
            </Card>
            <Button
                buttonType="muted"
                disabled={!entry}
                onClick={() => props.sdk.navigator.openEntry(entry!.id)}
                style={{ margin: `${tokens.spacingXl} 0` }}
            >
                Back to entry
            </Button>
            <div style={{ justifyContent: 'center' }}>
                <SkeletonContainer>
                    <SkeletonDisplayText numberOfLines={1} />
                    <SkeletonBodyText numberOfLines={10} offsetTop={35} />
                </SkeletonContainer>
            </div>
        </div>
    );
};

export default Page;

In the final code, I've added some Typescript interfaces to ensure we are working with the correct data structures. If you'd like to check out the complete code, visit the repo: davidfateh/ctfl-open-graph: Multi location app for Open Graph.

If you'd like to go beyond this functionality, Salma recently wrote a post on solving this issue using Puppeteer and Node.js to generate this data programmatically.

Final thoughts

Passing data between app locations can be very useful for creating cohesive experiences for editors as they work on content that is meant to be visualized in different ways. The Open Graph app is one example of how retrieving entry data and passing it around inside of an app can extend some basic functionality.

If you have an app idea or are working on a prototype, our Slack Community can be very helpful if you want to share or get help implementing ideas. You can take advantage of some of the cool things we are doing and discussing over there. Our extensibility team and I are active in our community, and we are always curious to hear ideas about your next big projects!

App Framework tutorial: Building a custom reference app

Shy Ruparel — Wed, 23 Jun 2021 14:40:52 +0000

I'm cross-posting this article for my Colleague David Fateh. Check out the original post over on the Contentful Blog.

Shy and I set out on a livestream to customize the Contentful reference field by using the App Framework to build a custom React app that would provide us with some new and novel functionality. While our progress during the live stream was good, I took the liberty of tightening up the styling and making sure additional functionality was possible. In this post, I'm going to show you how I created a custom reference field app which provides custom functionality.

Building on the App Framework

Building an app on the App Framework as a developer requires an understanding of how editors --- the people who use the Contentful web app --- may want to manipulate and view entry data. We know that everyone has different use cases and so the customization allowed by the App Framework can be useful when trying to create an experience that will help solve these unique cases.

When you define fields in an entry, you are defining how data should be displayed. In the case of the reference field, data such as the title of the entry is displayed by default like in the screenshot below:

We can enhance this experience by creating a visually similar custom app using the App Framework that can show more data from the referenced entry such as the body of the post, not just the title.

Getting started

To start, we used the create-contentful-app CLI tool. The tool is available for free to developers, and they can use it to quickly get an app up and running. The create-contentful-app CLI tool creates a React app project with Forma 36 (our design library) and our open source field editors for easy access.

We get all this by running the commands below:

npx @contentful/create-contentful-app init reference-field-app
cd reference-field-app
npm start

At this point our app is running on localhost:3000 but won't be accessible until we create the AppDefinition and select the locations where we want it to show up. Let's do this next.

Creating the AppDefinition

An AppDefinition is the entity that represents an app in Contentful. You can think of it as a sort of blueprint for how your app will interact inside the Contentful experience.

You must have an admin or developer account in your Contentful organization. Many developers find it easiest to create a free Contentful organization for a developer environment. You can also develop an app in your primary organization if you prefer to develop in a space or environment which isn't production facing.

To create the AppDefinition, head to your organization settings and click on Apps in the top menu bar. Once on the AppDefinition page, click the button to create a new app.

First, we are going to name our app: Custom Reference Field. Next, we will make its app URL http://localhost:3000. This is where our local app is currently running. Last, we are going to select the field location and pick the reference field (many) and click the confirm button to save this AppDefinition.

Replacing a built-in reference field with our custom app

Let's now head over to a space where we want to see our app show up. In the top menu of our space or environment, click Apps then Manage apps. From here we can find our newly created Custom Reference Field app and install it into our space.

Since we are building an app that will take over a reference field, we must also have a content type that makes use of a reference field. For our purposes, we are going to use a blog post list content type as an example.

In our content model, we are going to adjust the field of our blog post list to use our app by editing the settings of the reference field and selecting appearance. Let's choose our newly created Custom Reference Field app.

Coding the app for custom functionality

Once the app is assigned to a field, we can head over to our entries section and find an entry to see how the app is displayed. In our example, we have a reference field which links to different blog posts. Each blog post has a rich text field which we'd like to use to display some more custom information --- something that will give us a bit more functionality than the default reference field experience.

Let's create some custom functionality. First, we are going to replace our Hello World component with components from Forma 36, as well as utilities from React and a Contentful rich text renderer for display use. We are also going to use the handy MultipleEntryReferenceEditor which is part of our open source editor package. We are using the rich text renderer in this situation because our referenced content model of blog posts uses a rich text field for its body. Depending on the content type, you are referencing in your custom reference field app, displaying this data through different custom or open source components is possible.

import React, { useEffect } from 'react';
import {
    Card,
    Typography,
    Heading,
    CardActions,
    DropdownList,
    DropdownListItem,
} from '@contentful/forma-36-react-components';
import { MultipleEntryReferenceEditor } from '@contentful/field-editor-reference';
import { documentToReactComponents } from '@contentful/rich-text-react-renderer';
import { FieldExtensionSDK } from '@contentful/app-sdk';

Next, let's replace the Field component with custom code using the MultipleEntryReferenceEditor. You'll notice that while this markup is not very complicated, we will have to implement a customRenderer for our MultipleEntryReferenceEditor to show properly.

const Field = (props: FieldProps) => {
    useEffect(() => {
        props.sdk.window.startAutoResizer();
    });

    return (
        <MultipleEntryReferenceEditor
            renderCustomCard={customRenderer}
            viewType="link"
            sdk={props.sdk}
            isInitiallyDisabled
            hasCardEditActions
            parameters={{
                instance: {
                    showCreateEntityAction: true,
                    showLinkEntityAction: true,
                },
            }}
        />
    );
};

Let's create the custom renderer function which will render some more React components:

 const customRenderer = (props: any) => {
    if (props.contentType.sys.id !== 'blogPost') {
        return false;
    }
    const title = props.entity.fields?.title?.[props.localeCode] || 'Untitled';

    return (
        <Card style={{ flexGrow: 1 }} padding="none">
            <div style={{ display: 'flex' }}>
                <div>{props.cardDragHandle}</div>
                <div style={{ flexGrow: 1, padding: '1em' }}>
                    <Typography style={{ marginBottom: '20px' }}>
                        <Heading style={{ borderBottom: '1px solid gray' }}>
                            {title}
                        </Heading>
                        {props.entity.fields.body &&
                            documentToReactComponents(
                                props.entity.fields.body[props.localeCode]
                            )}
                    </Typography>
                </div>
                <div style={{ padding: '1em' }}>
                    <CardActions>
                        <DropdownList>
                            <DropdownListItem onClick={props.onEdit}>
                                Edit
                            </DropdownListItem>
                            <DropdownListItem onClick={props.onRemove}>
                                Remove
                            </DropdownListItem>
                        </DropdownList>
                    </CardActions>
                </div>
            </div>
        </Card>
    );
};

Now let's put it all together:

import React, { useEffect } from 'react';
import {
    Card,
    Typography,
    Heading,
    CardActions,
    DropdownList,
    DropdownListItem,
} from '@contentful/forma-36-react-components';
import { MultipleEntryReferenceEditor } from '@contentful/field-editor-reference';
import { documentToReactComponents } from '@contentful/rich-text-react-renderer';
import { FieldExtensionSDK } from '@contentful/app-sdk';

interface FieldProps {
    sdk: FieldExtensionSDK;
}

const customRenderer = (props: any) => {
    if (props.contentType.sys.id !== 'blogPost') {
        return false;
    }
    const title = props.entity.fields?.title?.[props.localeCode] || 'Untitled';

    return (
        <Card style={{ flexGrow: 1 }} padding="none">
            <div style={{ display: 'flex' }}>
                <div>{props.cardDragHandle}</div>
                <div style={{ flexGrow: 1, padding: '1em' }}>
                    <Typography style={{ marginBottom: '20px' }}>
                        <Heading style={{ borderBottom: '1px solid gray' }}>
                            {title}
                        </Heading>
                        {props.entity.fields.body &&
                            documentToReactComponents(
                                props.entity.fields.body[props.localeCode]
                            )}
                    </Typography>
                </div>
                <div style={{ padding: '1em' }}>
                    <CardActions>
                        <DropdownList>
                            <DropdownListItem onClick={props.onEdit}>
                                Edit
                            </DropdownListItem>
                            <DropdownListItem onClick={props.onRemove}>
                                Remove
                            </DropdownListItem>
                        </DropdownList>
                    </CardActions>
                </div>
            </div>
        </Card>
    );
};

const Field = (props: FieldProps) => {
    useEffect(() => {
        props.sdk.window.startAutoResizer();
    });

    return (
        <MultipleEntryReferenceEditor
            renderCustomCard={customRenderer}
            viewType="link"
            sdk={props.sdk}
            isInitiallyDisabled
            hasCardEditActions
            parameters={{
                instance: {
                    showCreateEntityAction: true,
                    showLinkEntityAction: true,
                },
            }}
        />
    );
};

export default Field;

We now have a working component that not only shows the title of the blog post but also the first line of the blog post. We have successfully transformed the default experience of the reference field to show data that is more conducive for our use-case. If you're interested in seeing the full code, check out the repo here.

Wrapping up

For our purposes, changing the fields inside of an entry can be a very powerful tool. There are many cases for why you may want to either slightly modify existing functionality or totally recreate your own. For the cases where you'd like to simply modify the web app, we provide the default fields as a React component in our open source editor library. For cases where you'd like to create your own experience, Forma 36 can be an invaluable tool for achieving a very fluid look and feel of your UI without having to spend time messing with layout yourself.

That said, it is always interesting to see the different ways developers have come together and built their own components for the UI/UX they envision for their users. Many developers make use of our Slack Community where help and ideas are easily shared. I'm active on the channel and am always happy to help explore ideas or guide other developers through the app creation process.

If you'd like to join our community, you can take advantage of some of the cool things we are doing and discussing over there. If you are interested in seeing more video tutorials, check out our weekly streams on Twitch and YouTube where we code live and work through problems on the fly!

If you haven't signed up for a free Contentful account yet, register for a Community edition!

Visualize your Content Models with ContentModel.io

Shy Ruparel — Wed, 26 May 2021 14:15:37 +0000

Developer Advocate Shy Ruparel takes a look at ContentModel.io, a tool to visualize Content Models. ContentModel.io also let's you share your own content models and import the models that others have made.

How to post to Twitter using Contentful webhooks and IFTTT

Shy Ruparel — Mon, 24 May 2021 14:30:03 +0000

Want to post to Twitter every time you publish a blog post? Don't have the time to build a Twitter API integration? Contentful Developer Evangelist Shy Ruparel shows us how easy it is to set up social media posting using Contentful webhooks and IFTTT (If This Then That).

Contentful Updates: Introducing new APIs for managing bulk content

Shy Ruparel — Wed, 12 May 2021 14:59:25 +0000

Every month Shy from the Contentful Dev Rel Team will share his favorite changes from the Contentful Changelog.

This month is so jam packed he's made two videos. For this one he's sharing all of the details about the three newest Contentful APIs for managing content in Bulk Content

How does GraphiQL work? An intro to Introspection.

Shy Ruparel — Wed, 12 May 2021 14:36:02 +0000

Contentful Developer Evangelist Shy Ruparel took a deep dive into figuring out how does GraphiQL build the self documentation that we're all come to love as a major feature of the tool.