Michael Mikus

The books r/embedded keeps recommending

Sun, 04 Oct 2026 00:00:00 GMT

“What book should I read?” is one of the most common questions on r/embedded. It gets asked by students, by software developers moving closer to the hardware, and by electrical engineers who want to write better firmware. The answers are scattered across hundreds of threads, so I collected them and counted.

The short version: one book is named far more often than any other, the rest of the list is surprisingly wide, and the community’s taste has been shifting toward hardware.

How I counted

Reddit’s own site refuses automated requests like mine, so I used the Arctic Shift archive of public Reddit posts and comments. From it I took every r/embedded post that mentions books and kept the threads with at least three comments where either the title talks about books or the title asks for learning resources and the post itself mentions books.

That left 562 threads from August 2011 to 2 October 2026, with 7,502 comments by 3,233 different people.

I then matched the comments against a list of 92 titles, built from the books people actually link to and name in these threads. For each title I matched the author’s name and the distinctive part of the title. Titles that also read as ordinary phrases, like “Clean Code” or “Programming Embedded Systems”, only counted when written as a title or in a comment that also says “book”. I checked samples of the matches by hand and tightened the patterns where they caught the wrong thing, such as “Effective C” matching “Effective C++”, or mentions of an author’s podcast or video course instead of their book.

A mention below means one person naming a book in one thread. Someone who repeats a title three times in the same thread counts once.

The ranking

#	Book	Author	Mentions	Threads
1	Making Embedded Systems	Elecia White	105	78
2	The Art of Electronics	Paul Horowitz, Winfield Hill	61	32
3	The C Programming Language	Brian Kernighan, Dennis Ritchie	55	34
4	Mastering STM32	Carmine Noviello	46	39
5	Test-Driven Development for Embedded C	James Grenning	37	34
6	Practical Electronics for Inventors	Paul Scherz, Simon Monk	29	18
7	Make: AVR Programming	Elliot Williams	27	21
8	Real-Time C++	Christopher Kormanyos	22	14
9	Mastering Embedded Linux Programming	Frank Vasquez, Chris Simmonds	21	16
10	Linux Device Drivers, 3rd edition	Corbet, Rubini, Kroah-Hartman	20	15
10	Clean Code	Robert C. Martin	20	14
12	Embedded Software Design, Reusable Firmware Development	Jacob Beningo	19	16
13	The Definitive Guide to ARM Cortex-M3 and Cortex-M4, and others	Joseph Yiu	18	17
14	MicroC/OS-II and MicroC/OS-III	Jean Labrosse	17	12
15	Embedded Systems textbooks and free e-book	Jonathan Valvano	15	14
15	The Art of Designing Embedded Systems, and others	Jack Ganssle	15	13

Each title links to the publisher’s page for the latest edition. Where the authors keep an official site for the book or there is an official free copy, as with The Art of Electronics, Linux Device Drivers and Valvano’s books, the link goes there instead. The fourth edition of Mastering Embedded Linux Programming was renamed Mastering Embedded Linux Development.

Below these, mentions thin out quickly. Effective C++, An Embedded Software Primer, Modern C, Programming Embedded Systems and Hands-On RTOS with Microcontrollers each have between 11 and 14. Of the 92 titles on my list, 83 were named at least once, and the top ten account for almost half of all mentions.

Only 291 of the 562 threads name a book from the list at all. The others are answered with courses, boards, projects and general advice, or drift to other topics.

One book stands out

Making Embedded Systems is named in 78 threads, which is more than one in four of the threads that name any book at all. It leads in every period I looked at, with 105 mentions against 61 for second place.

The comments explain why. It is described as a broad, readable introduction that covers the whole spectrum of building an embedded system, rather than one chip or one technique. One commenter called it “the gold standard”. The main reservation is the mirror image of the praise: it is a survey, not the most in-depth book on any single topic. The second edition, published by O’Reilly in 2024, added chapters on IoT and networked sensors, debugging, and data handling.

Its author also co-hosts the Embedded.fm podcast, which is itself one of the most recommended resources in these threads (more on that below). Some of the book’s reach probably comes from that.

More than half is not about embedded

If you sort every mention into a category, only 47% go to books about embedded systems. The rest:

Category	Share of mentions
Embedded systems and firmware	47%
C and C++	17%
Electronics and hardware	14%
Embedded Linux	6%
Computer architecture and theory	6%
General software craft	6%
Real-time operating systems	4%

Shares are rounded. A handful of mentions of general-interest books, such as The Soul of a New Machine, are left out.

The second most named book is The Art of Electronics, a dense electronics reference. The third is K&R, a C book whose current edition dates from 1988. Clean Code ties for tenth. Embedded work sits between electrical engineering and software, and the reading list reflects that: it has circuits for people coming from software, and C and software design for people coming from hardware.

The threads are also clear that the two electronics books are not interchangeable. The Art of Electronics is praised as the reference people keep on the desk for years, and a few commenters warn that it is dense and not a beginner’s book. Practical Electronics for Inventors is the one recommended as the practical way in.

The classics are old, and the threads know it

Several of the most named books are well over a decade old. K&R’s second edition dates from 1988, Linux Device Drivers from 2005, and Test-Driven Development for Embedded C from 2011. Commenters recommend them for fundamentals that have not changed much, and some are free: Linux Device Drivers is readable online at LWN.

Commenters are open about the gaps. Some warn that K&R describes a version of C more than thirty years old, and in about a third of the threads where K&R comes up, someone also suggests a newer C book. Effective C by Robert Seacord (second edition 2024) and Modern C by Jens Gustedt (third edition 2025) both cover C23, and the manuscript of Modern C is free to read under a Creative Commons licence for non-commercial use.

Learn on a real chip

Two of the top seven books are written for one family of microcontrollers. Mastering STM32 teaches ST’s STM32 parts through the official STM32Cube tools and runs to about 900 pages in its second edition. Make: AVR Programming teaches the 8-bit AVR chips found on many Arduino boards, without the Arduino libraries.

The community clearly likes learning on concrete hardware. But the two books are heading in different directions: Make: AVR Programming appeared in 15% of the threads that named a book before 2020 and in 6% since 2023, while Mastering STM32 has held steady between 12% and 15%. That fits the wider move from 8-bit parts to 32-bit Arm Cortex-M. Joseph Yiu’s Definitive Guide books on the Cortex-M cores, which explain the processor itself, are gaining a little.

What is rising and what is fading

I split the threads that name at least one book into three periods and compared how often each book appears in them. The earliest period has only 48 such threads, so treat small differences as noise. A few changes are large enough to mean something:

Book	2011 to 2019	2020 to 2022	2023 to 2026
Making Embedded Systems	27%	36%	21%
The Art of Electronics	6%	11%	13%
Practical Electronics for Inventors	2%	4%	9%
Hands-On RTOS with Microcontrollers	0%	2%	6%
Test-Driven Development for Embedded C	13%	18%	8%
Make: AVR Programming	15%	6%	6%
Effective C++ (Scott Meyers)	13%	4%	1%
Jack Ganssle’s books	8%	8%	1%

Three trends stand out. Electronics books are gaining, and so are questions about hardware: threads with electronics or hardware in the title went from 2% of all threads before 2020 to 10% since 2023. Newer books are gaining ground: Brian Amos’s Hands-On RTOS with Microcontrollers (2020, and a second edition with two co-authors in 2025) for RTOS work, and Jacob Beningo’s books, most recently Embedded Software Design (2022), for architecture, while Jack Ganssle’s older books fade. And Scott Meyers’s Effective C++, once a regular in C++ answers, has almost disappeared.

Some of the best answers are not books

The same threads point to courses, podcasts and video channels as often as to many of the books on the list. Counted the same way:

Resource	Mentions
Miro Samek’s Modern Embedded Systems Programming (video)	30
Embedded.fm podcast	30
FastBit Embedded Brain Academy courses	30
Shape the World course on edX (Valvano, Yerraballi)	27
Embedded Artistry blog and reading list	20
Phil’s Lab (video)	16
Ben Eater (video)	15

Any of the top four would rank sixth or seventh among the books. Jonathan Valvano is the clearest example: his free course is mentioned almost twice as often as his textbooks.

If you only read three

This section is my reading of the threads rather than a count. Taken together, the advice converges on a small set rather than one perfect book:

One book about the whole job. Making Embedded Systems is the community’s default.
One book about the language. K&R is still the classic. Effective C or Modern C teach the C you will actually write today.
One book about the hardware. Practical Electronics for Inventors to start, The Art of Electronics as the reference you grow into.

Then add a book written for the chip you are using, like Mastering STM32, and a book about the area you work in, such as testing, embedded Linux or an RTOS.

What this data can’t tell you

A mention is not a review. Most of the mentions I read were recommendations, but some are warnings, like the “not for beginners” notes on The Art of Electronics. The people asking and answering on Reddit also skew toward students and early-career engineers, which favours introductory books over specialist ones.

The counts depend on my list of titles, so a book nobody names in a recognisable way is missing. The archive also thins out before 2018. And these numbers measure how often a book is recommended, not how good it is. They tell you what this community reaches for first, which is a useful place to start, but no more than that.

Sources

r/embedded, posts and comments from August 2011 to 2 October 2026, retrieved through the Arctic Shift archive
Making Embedded Systems, second edition, O’Reilly
Linux Device Drivers, third edition, free online at LWN
Modern C, third edition, Manning
Effective C, second edition, No Starch Press
Mastering STM32, second edition, Leanpub
Embedded Systems: Shape the World, Jonathan Valvano and Ramesh Yerraballi

What to expect in Zephyr 4.5

Tue, 22 Sep 2026 00:00:00 GMT

Zephyr 4.5 is scheduled for the week of 26 October 2026. Feature freeze is due in the week of 28 September, so the feature set is close to final. Everything below comes from the working drafts of the release notes and migration guide in the Zephyr repository, as of 30 September. Details can still change before the release.

When it lands, and why this one matters

Milestone	Week of
Feature freeze (RC1)	28 September 2026
Second release candidate (RC2)	12 October 2026
Hard freeze (RC3)	19 October 2026
Release	26 October 2026

The dates come from the project’s release schedule and are tentative.

Zephyr now ships on a fixed six-month cadence, in April and October. That makes 4.5 the last release before LTS4, planned as Zephyr 4.6 in April 2027. If you plan to move to the LTS, testing 4.5 now spreads the migration work over two releases instead of meeting all of it at once in April. It also matters if you are still on 4.3: its support ends on 15 October 2026, before 4.5 ships.

What’s new

A new architecture. Zephyr now supports Infineon TriCore, the architecture behind Infineon’s AURIX microcontrollers.
Video and multimedia. Video gets a proper subsystem API, taking over the functions that used to live in the video drivers. Applications only need to change the include, to <zephyr/video/video.h>. A new Multimedia Pipeline lets an application describe a media flow as sources, transforms and sinks, instead of driving each audio, video or display device itself.
Clock monitoring. A new Clock Monitor driver class observes clock frequency at run time.
An automotive bus and precision timing. A new LIN driver class covers the Local Interconnect Network bus used in vehicles, and a new precision timing subsystem gives drivers shared helpers for checked time arithmetic, clock operations and PI (proportional-integral) control.
A native LoRaWAN stack. A new backend implements LoRaWAN 1.0.x Class A directly on the LoRa radio driver, without the Semtech LoRaMac-node dependency. It supports only the EU868 region for now. If you try it, call runtime settings such as lorawan_set_datarate() and lorawan_enable_adr() after lorawan_start(); earlier calls are refused or dropped.
CPU affinity on every scheduler. CONFIG_SCHED_CPU_MASK no longer requires SCHED_SIMPLE, so SMP projects can pin threads while using the scalable or multi-queue scheduler.
Device classes in devicetree. A binding can declare a class:, and code can enumerate every enabled node of that class at build time with macros such as DT_FOREACH_CLASS_STATUS_OKAY. The ADC and I3C shells already use it, so they now find out-of-tree drivers too.
Security stack updates. Mbed TLS moves to 4.1.1, TF-PSA-Crypto to 1.1.1 and TF-M to 2.3.1, which can now be built with LLVM. A new dispatch hook lets TF-PSA-Crypto route operations to a hardware accelerator, and MCUboot can embed several signing keys, so a development bootloader can boot both development- and production-signed images.

The draft also lists 130 new boards so far, and two CVEs addressed in this release, CVE-2026-8718 and CVE-2026-9263.

What will need changes

The migration guide is long. These are the items most likely to reach an ordinary application:

CMake 3.28 is now the minimum. Ubuntu 24.04 ships 3.28.3. On Ubuntu 22.04, get a newer CMake from the Kitware APT repository or with pip install cmake.
C17 is now the minimum C standard. CONFIG_STD_C11, CONFIG_STD_C99 and CONFIG_STD_C90 were removed, so a project that pins one of them fails at build time. Remove the option and build with C17 or newer.
Generated headers need the zephyr/ prefix. Write #include <zephyr/version.h>, not <version.h>. The legacy include path that allowed the short form, CONFIG_LEGACY_GENERATED_INCLUDE_PATH, is deprecated and now off by default.
The ring buffer API changed. The zero-copy claim and finish calls give way to ring_buf_put_ptr() and ring_buf_get_ptr(). Code still using the old calls or the item API fails to compile without a helpful message. Enabling CONFIG_RING_BUFFER brings the legacy API back while you migrate. Also, ring_buf_get() no longer takes a NULL buffer to throw data away, unless CONFIG_RING_BUFFER is enabled; use ring_buf_consume() for that.
ninja flash and friends are gone. The CMake flash, debug, debugserver, attach and rtt targets were removed. Use the west equivalents. The run and debugserver targets for emulators such as QEMU still work.
Two kernel behaviours changed. k_sem_reset() no longer wakes threads polling on the semaphore, and CONFIG_SMP_BOOT_DELAY is replaced by a per-CPU zephyr,deferred-start flag in devicetree.
Some Bluetooth callbacks run in another thread. Some host callbacks, such as disconnected(), now run in the Bluetooth RX thread instead of the system workqueue. Check your locking and CONFIG_BT_RX_STACK_SIZE.
Old Mbed TLS options are gone. Deprecated Kconfig names such as CONFIG_MBEDTLS_TLS_VERSION_1_2 were removed. Use the names that match Mbed TLS’s own settings, here CONFIG_MBEDTLS_SSL_PROTO_TLS1_2. Unlike the old ones, they do not enable their dependencies for you.
Espressif boards get signed, revertible images by default. Sysbuild now builds MCUboot with swap using offset and RSA-2048 signatures, using MCUboot’s development key unless you set your own. The new bootloader rejects unsigned images, so flash the bootloader and the application together when you move a device over. Swap using scratch is no longer available on boards that use Espressif’s shared partition tables, unless a board overlay adds the scratch partition back.

Board maintainers should check three more things. Revision fragments named <board>_<revision>.conf are no longer read, so rename them to <board>_<revision>_defconfig. NXP’s devicetree include files for LPC, Kinetis, MCX and i.MX RT have moved into per-series folders, which breaks out-of-tree board includes. And Espressif’s per-module devicetree files are gone: an out-of-tree Espressif board now includes the plain SoC file and describes its own flash.

How to get ready

Build your project against main now, or against RC1 once it is tagged, and read the deprecation warnings. Most of the changes above fail loudly: at build time or, for the Espressif bootloader, at first boot. Three do not: k_sem_reset() used together with k_poll(), ring_buf_get() called with a NULL buffer in the default build, and the Bluetooth callbacks that changed threads. Check those by hand.

Then read the migration guide for the subsystems you actually use. It is organised by area, so you rarely need the whole thing.

Sources

Zephyr® is a registered trademark of The Linux Foundation. This post is independent and not endorsed by the Zephyr Project.

On embedded, the worst bugs are often not in your code

Tue, 15 Sep 2026 00:00:00 GMT

This month a thread hit the top of r/embedded with a simple prompt: share the embedded bug that cost you hours. It drew hundreds of replies. I read through about ninety of them looking for a pattern, and the pattern surprised me.

Almost none of the bugs were logic errors.

That thread asked for the most memorable bugs, so it is not a random sample. Most day-to-day firmware bugs are still ordinary code bugs. But the ones that eat days tend to look like these.

Three real stories

One engineer spent a day hunting ten or twenty microamps of current draw that would not go away. The reading was maddeningly random. At one point a colleague walked over to help and the extra current vanished; they stepped away and it came back. The cause was sunlight from a window landing on a chip with an exposed die, generating a small photocurrent. A shadow fixed it. Several other people replied with the same class of story, including an ASIC that refused to power up until someone shone a flashlight on the die.

Another described a board that stopped transmitting serial data whenever the air got humid. Breathe on it and it would go quiet. They suspected the humidity sensor and pulled it out entirely. The board still failed. The real cause was a cold solder joint on the enable line of the RS-232 transceiver. With the joint barely connected, the pin was effectively floating, and in humid air the leakage across the board surface pulled it to the wrong level.

A third shipped a batch of devices with the wrong crystal, a few percent fast. Everything worked except a routine that detected a tone, because that was the one thing that depended on the exact sample rate. Weeks went into tracing it, because the crystal was nowhere near where the symptom showed up.

A separate post the same month came from someone so tired of chasing I²C problems with an oscilloscope that they built a dedicated diagnostic tool. The comments turned into a catalogue of the ways a two-wire bus lies to you: a target holds the clock low longer than the controller tolerates and the transaction fails as if the device were not there; the processor resets mid-byte and leaves a target holding the data line low until someone clocks it free or power-cycles it. As one commenter put it, when the data line is stuck low the fix is completely different depending on which chip is holding it, and right now everyone guesses. Another summed the bus up: I²C is barely a standard. The spec exists; the trouble is how loosely devices follow it.

The pattern

Read enough of these and the shape is always the same. The fix, when it finally arrives, is trivial. A shadow. A reflow. The right crystal. The cost was never the fix. It was the search. And the search was long because the fault was not where the symptom showed up.

This is what makes embedded debugging feel different, and why it humbles people who are strong software engineers. In application software, most bugs are in logic you can inspect. You can read it, log it, step through it, reproduce it. Your whole toolkit assumes the fault lives somewhere you can look.

Embedded systems break that assumption. The system is not just your code. It is your code plus a physical world your code cannot see: light, heat, humidity, a marginal solder joint, a clock a few percent off, a bus that half the devices on it implement differently. The symptom appears in software, so that is where you start looking, but the cause is usually a layer or two below, in a place your instincts never point you.

That gap, between where the symptom shows and where the cause lives, is the entire debugging cost.

What actually helps

You cannot make the physical world stop misbehaving. What you can do is shrink the gap, by making the invisible parts of the system visible. That is really what firmware observability is: not a product category, but the practice of getting the system to tell you what it is doing so you spend less time guessing.

A few things move the needle, roughly in the order they start helping:

See the physical layer directly. A logic analyzer on the bus turns “the sensor is flaky” into decoded transactions you can read, and a scope shows the analog faults a logic analyzer hides, like slow edges from weak pull-ups. The person who built that I²C tool was doing exactly this, just packaged so they never had to set up the scope again.
Capture the crash instead of losing it. In the field, a fault usually ends in a reset, from a watchdog or a reset-on-fault handler, and the RAM state that would explain it is gone. A fault handler that saves a coredump to flash means the one crash you did catch still tells you something after the reset. On Zephyr, the coredump subsystem writing to a flash partition, plus GDB on the host, gets you a backtrace after the device has rebooted, as long as you kept the zephyr.elf from the build that crashed. On the bench, a probe channel like SEGGER RTT lets you watch the device live without a spare UART.
Get logs off the device without changing the timing. The classic embedded trap is that adding a print statement moves the bug. Loggers that move formatting off the device, such as Rust’s defmt or Zephyr’s dictionary-based logging, send references to the format strings and the raw arguments, and let the host build the strings, which keeps the on-device cost small. The host can only do that with a file from the exact build running on the device: the ELF for defmt, and for Zephyr the log_dictionary.json that the build writes next to the image. Zephyr’s logging documentation says the dictionary only works with the build that produced it, so archive it with every image you ship; rebuilding the same source later is not a safe substitute. It also pays to have each device log an identifier for its build, for example at boot, so a log from the field points straight to the right archived files. Trace tools like SEGGER SystemView or Percepio Tracealyzer show you the ordering of interrupts and tasks that a print can never capture.
For the bugs that only happen in the field, bring the field to you. The hardest stories above share a trait: they showed up on one unit, in one place, under conditions you cannot reproduce on the bench. This is where firmware observability platforms earn their place. They ship crash reports, metrics, and logs home from deployed hardware, so you can see the state that led to a fault without standing next to the device. Memfault collects coredumps, metrics, and logs, and adds OTA updates. Golioth is a broader device platform that covers remote logs, diagnostics, and OTA, and hands crash analysis to Memfault through an integration. Spotflow, where I work, collects logs, metrics, and core dumps with stack traces, with ready-made integrations for Zephyr, ESP-IDF, and Nordic’s nRF Connect SDK. It sends data over MQTT and buffers it on the device while the connection is down, which suits devices that are only online now and then, and it also handles OTA updates and tracks known CVEs in your firmware. I am telling you that I work there so you can weigh the recommendation accordingly.

None of this stops the wrong-crystal bug from happening. What it changes is how long you spend in the dark before you find it.

The real skill

So here is the thing I would tell someone new to embedded, and the reason that thread stuck with me. The engineers who are fast at this are not the ones who write bug-free firmware. Nobody does. They are the ones who have learned, usually the hard way, that the bug is probably not where they are looking, and who have built enough visibility into the system that the search is short.

You cannot add that visibility at three in the morning, with a customer’s device failing in a building you cannot get to. You add it before, on purpose, while everything still works. That is the discipline. The debugging skill is really a seeing skill.

Updated 4 October 2026: thanks to @ManBoEmbedded on X for pointing out that the logging dictionary has to be archived with every build, and that logs should name the build they came from. The logging and coredump advice above now covers both.

Cloudflare Pages already keeps your preview deploys out of Google

Thu, 06 Aug 2026 00:00:00 GMT

I wanted to review every change to this site on a real URL before it went public. Not localhost. The actual rendered page, deployed, so I could catch the layout problems a dev server hides.

Cloudflare Pages gives you that: push a branch, get a preview deployment at its own URL. But those preview URLs are public, and my first thought was the obvious one. I don’t want half-finished drafts turning up in Google. So I reached for an Astro conditional to stamp noindex on preview builds.

Then I checked whether I actually needed it. I didn’t. Cloudflare already does it, one layer below my application, and the reason my clever conditional was pointless is the interesting part of this post.

The setup: two systems, one job each

Cloudflare Pages deploys. Production from main, a preview for the other branches it is configured to build. It deploys every branch that builds, good change or bad, because a preview is for looking at. It runs no checks beyond the build command.
GitHub Actions is the quality gate. It runs format, type-check, and build on every pull request, and deploys nothing. It is what blocks a bad merge, once its job is a required status check in a branch protection rule or ruleset.

Connect the repo, set the build command (pnpm build) and output directory (dist), and choose the production branch (main here, but that is a project setting, not a rule). By default Cloudflare deploys your non-production branches as previews, and a pull request opened from the repository gets a preview URL posted on it. You can scope this to all branches, none, or a chosen set. Each preview gets an immutable hash URL and a per-branch alias.

That is the whole deploy configuration. Now the part I got wrong.

The noindex I didn’t need to write

Here is the code I was about to add to my base layout:

---
const isPreview =
  process.env.CF_PAGES === '1' && process.env.CF_PAGES_BRANCH !== 'main';
---

<head>
  {isPreview && <meta name="robots" content="noindex" />}
</head>

It is not wrong. Cloudflare injects CF_PAGES=1, CF_PAGES_BRANCH, CF_PAGES_URL, and CF_PAGES_COMMIT_SHA into every Pages build, so at build time a static Astro site can tell it is a preview and emit the tag. The mechanism is real.

It is just unnecessary, because Cloudflare already handles this a layer down. From their docs:

By default, every preview deployment generated by Cloudflare Pages includes the X-Robots-Tag: noindex HTTP response header.

You can watch it happen. Curl a preview URL and the production URL and compare headers:

$ curl -sI https://<hash>.my-project.pages.dev | grep -i robots
x-robots-tag: noindex

$ curl -sI https://my-project.pages.dev | grep -i robots
# (nothing)

Preview deployments carry noindex. Production does not. I had not written a line of code, and the exact behavior I wanted was already there.

Why the header is the right place and my meta tag was the wrong one

There are two ways to tell a crawler to skip a page:

<meta name="robots" content="noindex" />

X-Robots-Tag: noindex

They mean the same thing to Google, but they live at different layers. The meta tag exists only inside HTML that you generated. The HTTP header applies to the response itself, every response, whatever your app rendered and whether or not it is even HTML.

That difference is the whole point. Cloudflare knows a deployment is a preview because it created the preview. It does not need my application to re-derive that fact from an environment variable and act on it. The system that owns the fact applies the correct HTTP semantics, and my app never has to care.

That is the lesson worth keeping: do not solve an infrastructure problem inside your application. My isPreview check was pulling a fact that belongs to the deploy platform up into my page templates. It would only have covered HTML rendered through that layout, not images, PDFs, or any page that skips it. Cloudflare already answered the question, once, at the edge, for every response.

A static _headers file can also set X-Robots-Tag by hostname, using placeholders: https://:project.pages.dev/* for the production pages.dev address and https://:version.:project.pages.dev/* for previews, if you ever need indexing rules the defaults do not cover. For keeping previews out of search, you do not need it.

The layers, in one picture

                    git push / PR
                          │
             ┌────────────┴────────────┐
             ▼                         ▼
       GitHub Actions            Cloudflare Pages
       (quality gate)               (deploy)
             │                    ┌────┴────┐
   format / check / build         ▼         ▼
             │                  main      branch
             ▼                    │         │
        pass → merge              ▼         ▼
                              production  preview
                                  │         │
                              indexable   X-Robots-Tag:
                                            noindex

Cloudflare deploys and decides indexing. GitHub Actions decides whether a commit is allowed to become production. Neither job belongs in my page templates.

The one thing Cloudflare doesn’t do for you

Cloudflare noindexes previews, but your production *.pages.dev stays indexable. If you also serve the site on a custom domain, my-project.pages.dev and mydomain.com are now the same content at two addresses, which is a duplicate-content problem. The fix is not a preview conditional. It is a canonical URL on every page pointing at your real domain (this site sets one in its base layout), which search engines treat as a strong hint, or, to settle it, a Bulk Redirect from the pages.dev hostname to your domain. The _redirects file cannot match on hostname, so it cannot do this one.

And noindex is not access control. Anyone with a preview URL can still open it. If a draft must stay private, put the previews behind Cloudflare Access.

The quality gate

The deploy side does none of the checking, so a separate workflow runs the same commands I run locally, and a red check blocks the merge once the job is marked as a required status check.

name: CI
on:
  push:
    branches: [main]
  pull_request:

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm check-format # prettier --check .
      - run: pnpm check # astro check
      - run: pnpm build

pnpm/action-setup reads the pnpm version from the packageManager field in package.json; without that field, give it a version. --frozen-lockfile fails the install if the lockfile is out of date, so CI builds the exact tree I committed. The three checks are the same scripts in package.json, so pnpm check-format && pnpm check && pnpm build locally means green in CI. cancel-in-progress kills a superseded run, so a burst of commits only spends minutes on the last one.

What I actually learned

I came in ready to write application code to keep previews out of Google, and the useful outcome was not writing it. Cloudflare deploys previews and marks them noindex. GitHub Actions gates the merge. The site sets a canonical URL. Three layers, each owning one job, and none of them my page templates.

The best infrastructure code is often the code you were about to write and then didn’t have to.