Pedro Martins

The 10x Trap: Why AI Made Me Work More, Not Less

Pedro Martins — Wed, 22 Apr 2026 00:00:00 GMT

import Callout from "@/components/Callout.astro";

1. Introduction

If you are reading this, you already know most of what's going on with AI and you follow the scene quite closely. We all thought AI would give us back our time, and life would be a bit easier right? AI would do the boring parts, automate the repetitive work, let us focus on the fun stuff. The list goes on and on.

Well, yeah, not quite. After 2 years of using AI daily, i must admit i've been actually working more, not less. Keep in mind not everything is negative, i've been doing more projects, more open source, learning more, so its not all bad. But the hours? The hours went up.

How about you? Do you feel like you're working more with AI? I know its hard to keep up with the "San Francisco mindset" so you don't feel left behind, but is there a better way? Lets dig in.

<Callout type="info"> Scientific American (March 2026) reported that out-of-hours code commits rose 19.6% among engineers using AI, and engineers scored 17% lower on comprehension quizzes compared to the control group. We are working more AND understanding less. Something is off. </Callout>

So lets talk about why this is happening, what i've been feeling on my own machine, and where i think we're heading.

2. The Parallelism Trap 🪤

Well, if you are a developer you're probably using some agentic workflow tool like [[Cursor|https://cursor.com]], [[Claude Code|https://claude.com/claude-code]], [[Superset|https://superset.sh]], [[Conductor|https://conductor.build]], [[Codex|https://github.com/openai/codex]], or similar. These tools let you multiplex your workflow across multiple worktrees, multiple projects, and multiple agents all running in parallel. Looks crazy right? Are we in the future? Yes we are!

But there is a catch (there is always a catch, right?). While doing all this can be a massive productivity boost if you planned things perfectly beforehand, it also increases the amount of attention and context you need to hold in your valuable brain.

This often leads to a lot of context switching, and your mental bandwidth is constantly getting drained. You will probably:

Feel like you have done more, when you actually have done less.
Stop paying attention to details, flow control, code quality, possible bugs, etc.
End up feeling way more tired at the end of the day, because there is a lot to ingest at all times.
Make poor architecture decisions without realising it.

<Callout type="info"> The 2025 DORA Report backs this up, developers using AI interact with 67.4% more PR contexts per day, work restarts are up 13.8%, and 26% more in-progress tasks show no activity for 7+ days. Parallelism has a real cost. </Callout>

Personally, i've been doing a maximum of 2 worktrees per project and 2 to 3 agents per worktree. The only exception where i scale more is when its repetitive work, like implementing a test suite for a bunch of modules at the same time.

BUT there is still a catch, lets check on the next section!

3. The Review Bottleneck 🔍

So, given all the above, you're producing code like crazy, and a lot of companies have been sold this dream of "10x productivity". But well, not quite the 10x we were thinking of.

Because we produce more code now (and the [[GitHub Octoverse 2025 report|https://github.blog/news-insights/octoverse/octoverse-a-new-developer-joins-github-every-second-as-ai-leads-typescript-to-1/]] shows this clearly, nearly 1 billion commits in 2025, up 25.1% year over year, with ~100 million commits in August alone), it means developers (mediors and seniors) are also now reviewing way more code. So not only are we writing more code, we are also reviewing more code. Yeah, MORE work for us!!! 😅

And if you want the scariest datapoint, there's a public tracker showing that [[Claude Code|https://claude.com/claude-code]] alone is responsible for around 9.7% of all public GitHub commits as of mid-March 2026, up from 4% in February. AI agent PRs jumped from roughly 4M in September 2025 to 17M in March 2026. Someone still has to read all of that.

<Callout type="info"> According to Faros AI research, developers are completing 21% more tasks, 98% more PRs merged, but PR review time is up 91% and PRs are 154% larger. The 2025 Stack Overflow Developer Survey also found that 45% of devs say debugging AI-generated code is the most time-consuming part of their day, and 66% are frustrated by AI output that is "almost right, but not quite". </Callout>

Companies are also not helping here, because they are doing massive layoffs thinking a developer can now do the work of 3 developers. When in fact, in my opinion, they are just putting more work on the shoulders of the remaining developers.

Eventually those developers will either:

Get burned out and leave the company.
Start letting sloppy code pass, because they are under pressure to deliver and can't properly review all of it.

And this is simply because we don't fully trust AI code yet, but lets check on the next section!

4. The Trust Gap 🤖

We are getting to the point where models are becoming more and more capable of doing the work of a developer (or so we think). As time goes by, i believe in about 2 years models will be able to produce actually good code that we can somewhat trust a bit more.

But lets not forget that AI is still JUST a next-token predictor. There's a lot of things that aren't there yet, models still have a "tunnel vision" about your project, they create unnecessary helpers, and a bunch of other things we call slop.

Developers currently use codebase indexers, semantic search, and greps to power up the AI workflow, but its still not enough. If you're solo vibing with AI for coding, you already know you're playing a gambling game every time you throw a new session in. There's a good chance you get something NICE, and also a good chance you get something BAD.

That's why we humans still need to keep a close eye on the output, not just blindly trust it. The ones doing that are the so-called vibe coders, the same ones who will then cry 3 days later that their [[Supabase|https://supabase.com]] credentials got leaked, or can't figure out why the website is not working, burning a zillion hours and tokens trying to understand what went wrong.

And yes, you can use [[Replit|https://replit.com]], [[CodeRabbit|https://coderabbit.ai]], or pass your code to 10 different AI models, and all of them will still let slop code pass. As of today, at least.

According to the 2025 Stack Overflow Developer Survey (49,000+ devs across 177 countries), 84% of developers use or plan to use AI tools, but only 29% trust the output, down from 40% the year before. Even worse, just 3% say they "highly trust" it, and the more experienced the developer, the lower the trust (senior devs report the highest "highly distrust" rate at 20%). So yeah, we might not be writing as much code ourselves, but we still need to understand code, and how to validate it. Thats on us.

5. Wrap Up 🧘

AI is still one of the best things happening at the moment, no doubt. But lets not forget (including myself) that there is still life outside the terminal, don't burn yourself out, its ok to take a break and do a bit less.

Lets also try to spread the word about this. Its all new, not only for us developers but also for companies and managers thinking AI will magically solve every problem and that they can "tokenmaxx" their way to success. The tool doesn't fix broken systems, it amplifies them. If your team ships fast and reviews slow, AI won't save you, it will just expose the cracks.

We developers are here to stay for a few more years at least! Stay positive, keep learning, keep building, and keep sharing your knowledge with the community. Thank you! 🙏

Links

[[Scientific American (March 2026), Why developers using AI are working longer hours|https://www.scientificamerican.com/article/why-developers-using-ai-are-working-longer-hours/]]
[[HBR (February 2026), AI Doesn't Reduce Work, It Intensifies It|https://hbr.org/2026/02/ai-doesnt-reduce-work-it-intensifies-it]]
[[Stack Overflow (February 2026), Closing the AI trust gap for developers|https://stackoverflow.blog/2026/02/18/closing-the-developer-ai-trust-gap/]]
[[2025 Stack Overflow Developer Survey, Press Release|https://stackoverflow.co/company/press/archive/stack-overflow-2025-developer-survey/]]
[[Larridin, Developer Productivity Benchmarks 2026|https://larridin.com/developer-productivity-hub/developer-productivity-benchmarks-2026]]
[[GitHub Octoverse 2025, 986M commits and AI leads TypeScript to #1|https://github.blog/news-insights/octoverse/octoverse-a-new-developer-joins-github-every-second-as-ai-leads-typescript-to-1/]]
[[CoreMention, Claude Code GitHub Commit Share Tracker|https://coremention.com/blog/claude-code-tracker/]]
[[Faros AI (July 2025), The AI Productivity Paradox Research Report|https://www.faros.ai/blog/ai-software-engineering]]
[[O'Reilly, AI Is Writing Our Code Faster Than We Can Verify It|https://www.oreilly.com/radar/ai-is-writing-our-code-faster-than-we-can-verify-it/]]
[[2025 DORA Report, State of AI-assisted Software Development|https://dora.dev/dora-report-2025/]]
[[VentureBeat, 43% of AI-generated code changes need debugging in production|https://venturebeat.com/technology/43-of-ai-generated-code-changes-need-debugging-in-production-survey-finds]]

Inside Mobile Apps - The Reverse Engineering Rabbit Hole

Pedro Martins — Tue, 10 Mar 2026 00:00:00 GMT

import CodeTabs from "@/components/CodeTabs.astro"; import CodeTab from "@/components/CodeTab.astro"; import Callout from "@/components/Callout.astro";

1. Introduction

Part of my life was also investigating mobile apps & their APIs, sometimes for security reasons & curiosity, and sometimes to do a few projects that required private APIs that were not publicly available. In this post i'll be using Instagram as the main example, since it was the app i spent the most time poking at, but the techniques apply to pretty much any mobile app.

While im not super proud of it, and it could as well be considered "illegal" or "Black Hat" practices, it was a great learning experience and a lot of fun to do. I also got a lot of help from the community & some of the greatest engineers in the scene.

<Callout type="warning"> I'm not affiliated with Instagram, im not a professional Penetration Tester or anything related to security, im just a hobbyist. The contents of this post are already old and probably not working anymore, still the process is the same for most mobile apps. Please do not try this at home, and do not use this for any illegal purposes. THIS IS FOR EDUCATIONAL PURPOSES ONLY. </Callout>

2. Glossary & Terminology

Reverse Engineering - Deconstructing a compiled app to understand its inner workings — reading decompiled code, tracing network calls, and figuring out undocumented behavior.
Jailbreak - Removing Apple's security restrictions on iOS devices, giving you root-level access and the ability to run unsigned code and tweaks.
Root - The Android equivalent of jailbreaking — gaining superuser (root) access to the OS, bypassing manufacturer restrictions.
JEB - A professional-grade decompiler and debugger for Android APKs. Turns compiled bytecode back into readable Java/Kotlin-like code.
Frida - A dynamic instrumentation toolkit that lets you inject JavaScript into running apps on both Android and iOS — hook functions, intercept calls, and modify behavior at runtime.
Certificate Pinning - A security mechanism where an app only trusts specific certificates for its server connections, rejecting even valid CA-signed certs. This makes intercepting API traffic significantly harder.

3. iOS vs Android: Two Very Different Worlds

<Callout type="warning"> Rooting or jailbreaking your device can brick it, void your warranty, and compromise your security. You may lose data, break OTA updates, or lock yourself out permanently. Always use a secondary device you're ok with losing, never your daily driver. Back up everything before you start. </Callout>

3.1. Root (Android)

Usually when you want to reverse engineer a mobile app, you may want to jailbreak or root the device (in case you want to check the network traffic and get an easy way to explore the app internals at runtime).

For me Android is much easier, since rooting is way more common due to Android being "open source". Phones like Google Pixel and others are really easy to root with tools like [[Magisk|https://github.com/topjohnwu/Magisk]].

You may also find on [[XDA forums|https://xdaforums.com/]] images for different devices, and how to root them. Keep in mind that rooting will: void your warranty in certain cases like Samsung devices, compromise your security, and you may not be able to use some features of the device. Apps might also detect if you are rooted and block you from using some features or using the app at all (like Pokemon Go), requiring you to have a bunch of workarounds to use the app.

3.2. Jailbreak (iOS)

But thats about Android, iOS is wayyyy more tricky to get root access also known as "jailbreaking". Back in the days, iPhones were somehow easier to jailbreak, the community was there, we had tools like Cydia, those were the golden days for iOS. But with the years, Apple has been cracking hard on iOS security and also hardware security, demotivating developers from the jailbreaking process, and even some of them being hired by Apple itself to work on the other side. This is one of the reasons why iOS is one of the safest devices that you can use in 2026.

So here for iOS you have a few options in 2026:

Be on an old iOS version and wait for the community to release a jailbreak for it, but this also means that you will be using a legacy version of the OS and that might cause some red flags to the apps, since 90% of the people usually do update to latest iOS versions.
[[VPPhone|https://github.com/Lakr233/vphone-cli]] - A recently released tool that allows you to run virtual iOS devices on your machine, and then you can jailbreak it.
[[Corellium|https://corellium.com/]] - An online iOS emulator that you can use to jailbreak your device & test for security vulnerabilities.

4. The Toolkit: JEB, Frida & Friends

Ok, we got the first part done, assuming you have your device ready to work, now its time to explore a few tools.

For iOS and Android (or anything really) you can use decompilers to explore binary/object code and get a better understanding of the app itself, while apps that care about security will make life harder for you, by having obfuscated code, tampering protection, and the list goes on. You may want to use this to find a few magic strings across the codebase ex: signature_key or whatever you see in the requests (more on that later at section 7).

4.1. JEB & IDA Pro

These are the two heavy hitters when it comes to static analysis, taking an app apart without running it.

[[JEB|https://www.pnfsoftware.com/]] is purpose-built for Android. You throw an APK at it and it decompiles the Dalvik bytecode back into readable Java/Kotlin. The UI lets you navigate classes, cross-reference method calls, and rename obfuscated symbols as you figure out what they do. For something like Instagram, you'd open the APK, search for strings like x-ig-signature or signature_key, and then trace backwards through the code to understand how they're generated. JEB also has a built-in debugger, so you can set breakpoints on a rooted device and step through the code live.

[[IDA Pro|https://hex-rays.com/ida-pro/]] is the industry standard for native code, think C/C++ compiled to ARM. Instagram (and most large apps) ship performance-critical and security-sensitive code as native .so libraries. When you see a Java method calling into libinstagram.so via JNI, that's where IDA comes in. It disassembles the binary into ARM assembly and tries to reconstruct higher-level structures. It's harder to read than JEB's Java output, but it's where the real secrets hide, crypto routines, signature generation, anti-tampering checks.

In practice you use both together: JEB to get the big picture and find entry points, IDA to dig into the native layers where the interesting logic lives.

Here is a small set of notes on how i used IDA Pro to get the Instagram Signature Key for iOS.

# 1. The iphone must be Jailbroken with Cydia, OpenSSH, and Mobile Substrate
# 2. Download and Install Clutch 2.0 for Cydia on the following repository:
#    http://cydia.iphonecake.com/
# 3. Connect to your Phone via SSH and type Clutch2,
#    it should show the apps installed and their IDs
# 4. Dump the IPA:
Clutch2 -d 1  # (use the ID of your app)
# 5. Check the path where the IPA got extracted,
#    usually at /private/var/mobile/Documents/Dumped/com.xxxxx
# 6. Copy the IPA file to your desktop and rename to .zip to extract it
# 7. Find the file at Payload/AppName.app/AppName (no extension)
#    and drag & drop it into IDA Pro
# 8. Wait for the automatic analysis to finish
# 9. In the functions window, Right Click -> "Quick Filter" -> type "hmac"
# 10. Find NSSString(HMAC)HMACWithSecret
# 11. Find the line of code above CCHmacInit — it should be "sub_xxxx"
# 12. Double click to check the sub function,
#     find the lower16/upper16 and navigate to that string
# 13. Select the main string and go to Edit -> Export Data
# 14. Put the HEX data in a script to decode the signing key:

</CodeTab> <CodeTab label="decode-key.php">

<?php
$encryptedKey = pack("H*", "AABBCCDD...");  // hex data exported from IDA
$hexChars     = array(52, 102, 97, 49, 48, 57, 98, 50, 99, 54, 100, 56, 101, 51, 55, 53);
$index        = array(244, 216, 173, 177, 178, 179, 184, 187, 159, 102, 106, 115, 124, 89, 13, 59);
$signingKey   = "";
$keyMap       = array_combine($index, $hexChars);
$encKeyLen    = strlen($encryptedKey);

for ($i = 0; $i < $encKeyLen; $i++) {
    $signingKey .= pack('C', $keyMap[ord($encryptedKey[$i])]);
}

printf("SigningKey: %s\n", $signingKey);
?>

</CodeTab> </CodeTabs>

Fun right? Ofc you have to figure out first, what are the actual "sub_xxxx" functions, and so on, i'll not be covering those in this post.

4.2. Frida

If JEB and IDA are about reading dead code, [[Frida|https://frida.re/]] is about messing with living code. It's a dynamic instrumentation toolkit, you attach it to a running app and inject JavaScript that can hook any function, intercept arguments, change return values, and basically rewrite the app's behavior on the fly.

The workflow is simple: you run frida -U -f com.example.app -l your_script.js on a rooted/jailbroken device connected via USB (-U), and Frida spawns the app with your script injected. From there, your script has full access to the app's memory, symbols, and Objective-C/Java runtime.

In practice, Frida is incredibly versatile, you can use it to extract encryption keys from memory, log function arguments and return values to understand internal logic, dump decrypted payloads, or bypass security checks like certificate pinning and root/jailbreak detection.

Here are two Frida scripts i used back in the day. The first one bypasses certificate pinning at multiple layers so you can intercept the app's HTTPS traffic with a proxy like [[Charles|https://www.charlesproxy.com/]] or [[mitmproxy|https://mitmproxy.org/]]. The second one hooks the HMAC signing process to extract the signing key straight from memory, the dynamic counterpart to the IDA Pro approach from section 4.1.

/**
 * Frida script to bypass SSL/TLS certificate pinning on iOS.
 * Targets multiple layers: custom HTTP framework verification, internal config
 * flags, OpenSSL-based callbacks, and Apple's Security framework.
 *
 * Usage: frida -U -f com.example.app -l ssl-pinning-bypass.js
 */

// ——————————————————————————————————————————————
// 1. Bypass the custom HTTP framework's TLS verification
// ——————————————————————————————————————————————
// Some apps use their own HTTP framework with a custom certificate
// verification step that runs before the standard SSL checks.
// We find it by symbol name and replace it to always succeed.
function bypassCustomTLSVerification() {
  var matches = DebugSymbol.findFunctionsMatching("*validateCertChain*");

  if (matches.length !== 1) {
    console.log("[!] Expected exactly one validateCertChain symbol, found " + matches.length);
    return;
  }

  var original = new NativeFunction(
    matches[0], "int",
    ["uint64", "pointer", "pointer", "pointer", "pointer", "pointer", "pointer"]
  );

  Interceptor.replace(matches[0], new NativeCallback(function (
    _flag, _x509ctx, _str, _failCb, _successCb, _clock, _trace
  ) {
    // Call original but swap the fail callback with the success callback,
    // then force return 1 (success) regardless
    original(_flag, _x509ctx, _str, _successCb, _successCb, _clock, _trace);
    return 1;
  }, "int", ["uint64", "pointer", "pointer", "pointer", "pointer", "pointer", "pointer"]));

  console.log("[+] Custom TLS verification bypassed");
}

bypassCustomTLSVerification();

// ——————————————————————————————————————————————
// 2. Disable internal TLS/SSL config flags
// ——————————————————————————————————————————————
// The app's internal config has several flags that enable enhanced
// TLS features (custom TLS stack, SSL session caching, cert compression).
// We force all of them to return 0 (disabled).

var configFlags = [
  "persistentSSLCacheEnabled",
  "crossDomainSSLCacheEnabled",
  "customTLSEnabled",
  "customTLSPersistentCacheEnabled",
  "quicEarlyDataEnabled",
  "tlsEarlyDataEnabled",
  "enableCertCompression",
];

function disableInternalTLSConfig() {
  var resolver = new ApiResolver("objc");

  for (var i = 0; i < configFlags.length; i++) {
    var flag = configFlags[i];
    var results = resolver.enumerateMatchesSync(
      "-[InternalTLSConfig " + flag + "]"
    );

    if (results.length < 1) {
      console.log("[!] Could not find getter for " + flag);
      continue;
    }

    Interceptor.attach(results[0]["address"], {
      onLeave: function (retval) {
        retval.replace(0);
      },
    });

    console.log("[+] " + flag + " disabled");
  }
}

disableInternalTLSConfig();

// ——————————————————————————————————————————————
// 3. Neutralize OpenSSL certificate callbacks
// ——————————————————————————————————————————————
// The underlying SSL library provides multiple hooks for cert
// verification. We replace them all with no-ops so the app
// never registers its custom pinning callbacks.

function neutralizeSSLCallbacks() {
  var callbackNames = [
    "SSL_CTX_set_cert_verify_callback",
    "SSL_CTX_set_cert_verify_result_callback",
    "SSL_CTX_set_verify",
    "SSL_set_verify",
    "SSL_set_cert_cb",
    "SSL_CTX_set_cert_cb",
    "X509_STORE_CTX_set_verify_cb",
  ];

  for (var i = 0; i < callbackNames.length; i++) {
    var name = callbackNames[i];
    var addresses = DebugSymbol.findFunctionsNamed(name);

    for (var j = 0; j < addresses.length; j++) {
      Interceptor.replace(
        addresses[j],
        new NativeCallback(function () {
          return;
        }, "void", [])
      );
    }

    console.log("[+] " + name + " neutralized (" + addresses.length + " instances)");
  }
}

neutralizeSSLCallbacks();

// ——————————————————————————————————————————————
// 4. Override Apple's SecTrustEvaluate
// ——————————————————————————————————————————————
// Last line of defense — Apple's own Security framework.
// We hook SecTrustEvaluate to always write kSecTrustResultProceed
// to the result pointer and return success (0 = errSecSuccess).

function overrideSecTrustEvaluate() {
  var ptr = Module.findExportByName("Security", "SecTrustEvaluate");

  if (ptr === null) {
    console.log("[!] SecTrustEvaluate not found");
    return;
  }

  var original = new NativeFunction(ptr, "int", ["pointer", "pointer"]);

  Interceptor.replace(ptr, new NativeCallback(function (trust, result) {
    original(trust, result);
    // kSecTrustResultProceed = 1
    Memory.writeU8(result, 1);
    return 0; // errSecSuccess
  }, "int", ["pointer", "pointer"]));

  console.log("[+] SecTrustEvaluate bypassed");
}

overrideSecTrustEvaluate();

console.log("\n[*] All SSL pinning bypasses active. Ready to intercept traffic.\n");

</CodeTab> <CodeTab label="extract-signing-key.js">

/**
 * Hooks the app's HMAC signing method and the underlying SHA256 calls
 * to extract the HMAC key material (ipad/opad XOR'd key) from memory.
 *
 * Usage: frida -U -f com.example.app -l extract-signing-key.js
 *        Then trigger a request in the app (e.g. try to log in).
 */

var currentThreadId = 0;
var requestBody = "";
var sha256CallCount = 0;
var hasShownSignedBody = false;
var lastDump = "";

function extractSigningKey() {
  var resolver = new ApiResolver("objc");
  var matches = resolver.enumerateMatchesSync("-[NSString computeHMAC:]");

  if (matches.length !== 1) {
    console.log("[!] Expected exactly one computeHMAC method, found " + matches.length);
    return;
  }

  Interceptor.attach(matches[0]["address"], {
    onEnter: function (args) {
      if (currentThreadId === 0) {
        currentThreadId = Process.getCurrentThreadId();
        requestBody = ObjC.Object(args[0]);

        // Now hook the underlying SHA256 update function to capture key material
        var moduleResolver = new ApiResolver("module");
        var sha256Matches = moduleResolver.enumerateMatchesSync("exports:*!CC_SHA256_Update");

        for (var i = 0; i < sha256Matches.length; i++) {
          Interceptor.attach(sha256Matches[i]["address"], {
            onEnter: function (args) {
              if (currentThreadId === Process.getCurrentThreadId()) {
                var dump = hexdump(args[1], { length: 0x40, ansi: false, header: false });

                if (dump !== lastDump) {
                  sha256CallCount++;

                  // HMAC internally does two rounds of hashing:
                  // 1st call: ipad XOR'd with the key
                  // 3rd call: opad XOR'd with the key
                  // From these two values you can recover the original key
                  if (sha256CallCount === 1) {
                    console.log("[*] ipad_xor_key =\n" + dump);
                  }
                  if (sha256CallCount === 3) {
                    console.log("[*] opad_xor_key =\n" + dump);
                  }

                  lastDump = dump;
                }
              }
            },
          });
          console.log("[+] CC_SHA256_Update hooked at " + sha256Matches[i]["address"]);
        }
      }
    },

    onLeave: function (retval) {
      if (Process.getCurrentThreadId() === currentThreadId && !hasShownSignedBody) {
        console.log("[*] Signed body example: " + ObjC.Object(retval) + "." + requestBody);
        hasShownSignedBody = true;
        Interceptor.detachAll();
      }
    },
  });

  console.log("[+] HMAC signing method hooked");
  console.log("[*] Now trigger a request in the app (e.g. try to log in)...\n");
}

extractSigningKey();

</CodeTab> </CodeTabs>

The SSL pinning bypass works in 4 layers because apps like these don't just pin certificates in one place, they stack multiple verification mechanisms on top of each other. If you only bypass one, the others will still reject your proxy's certificate. You need to get all of them. Once this script is running, you can point the device's traffic through a proxy and finally see the actual API requests in cleartext.

The key extraction script hooks the HMAC signing function and listens for the underlying CC_SHA256_Update calls. The output gives you the ipad and opad XOR'd keys, the two halves of the HMAC construction. Since HMAC XORs the key with known constants (0x36 for ipad, 0x5c for opad), recovering the original key is trivial, just XOR it back. The static IDA approach from section 4.1 requires you to reverse engineer the key obfuscation in the binary, while this dynamic approach just waits for the app to decrypt the key itself and grabs it from memory.

5. The Cat and Mouse Game

So you rooted your device, installed Frida, and you're ready to go. You open the app and... it crashes. Or it opens but refuses to load. Or it works but all the requests fail. Welcome to the cat and mouse game.

5.1. Root & Jailbreak Detection

Big apps like Instagram don't just sit there and let you poke around. They actively check if your device is compromised. On Android, Google's Play Integrity API (formerly SafetyNet) lets apps verify the device hasn't been tampered with. On iOS, apps check for common jailbreak artifacts like Cydia, /etc/apt, or the ability to write to system paths.

The thing is, these checks are well known and the community has built workarounds for most of them. On Android, Magisk has Zygisk modules (previously MagiskHide) that hide root from specific apps by running them in an isolated environment where root binaries and modified system files are invisible. On iOS, tweaks like [[Shadow|https://github.com/jjolano/shadow]] or [[A-Bypass|https://repo.co.kr/]] patch the detection routines at runtime.

But here's the catch, apps update their detection methods constantly. You might get it working today and then an app update two weeks later breaks everything again. Its a never-ending cycle.

5.2. Frida Detection

This one is sneaky. Some apps specifically look for Frida itself. They'll scan for the frida-server process, check if the default Frida port (27042) is open, look for Frida's agent library in the app's memory, or even scan for known Frida strings in loaded modules.

There are a few ways around this:

Rename frida-server to something random, some detection just looks for the process name
Use Frida Gadget instead of frida-server. Instead of attaching to the app from outside, you embed Frida directly into the app as a library (.dylib on iOS, .so on Android). This avoids the server entirely and is way harder to detect
Timing your injection, attach after the detection code has already run, or hook the detection functions themselves before they execute (yeah, using Frida to bypass Frida detection, its recursive like that)
Use [[frida-stealth|https://github.com/alphaSeclab/anti-debug]] or community scripts that patch known detection patterns

In my experience, Frida Gadget was the most reliable approach for heavily protected apps. It takes more setup (you need to repackage the app with the gadget library embedded), but once its in there, the app doesn't know the difference.

6. Reading the Requests

Now that you got everything that you need (or you should by this time) you can continue your journey to explore the app's HTTP layer. You can use tools like [[Wireshark|https://www.wireshark.org/]], [[Proxyman|https://proxyman.io/]], [[Fiddler|https://www.telerik.com/fiddler]], [[Charles|https://www.charlesproxy.com/]], [[mitmproxy|https://mitmproxy.org/]] to capture the network traffic and analyze the data. I usually use mitmproxy when i need flexibility to hook into the request (filter, etc) and Proxyman when i need something really quick to capture. Take the one that fits your needs best.

For apps that don't have Certificate Pinning, usually the process is as simple as:

Get the certificate from the proxy app and install it on your mobile device as a trusted certificate.
Set the WiFi settings to proxy to your proxy server like: 192.168.1.100:8080
You can try opening Google or any site and it shouldn't be blocked, if it is, you may have to check the certificate again.
Open the app and start clicking around and see the requests being logged. Keep in mind that for some apps you will get a TON of requests, most of them about telemetry, analytics, etc.

Once you're capturing traffic, the trick is knowing what to look for. Most of what you'll see is noise, telemetry pings, analytics batches, ad SDK calls, config fetches. The interesting stuff is usually the authenticated API calls, look for custom headers like x-ig-signature, x-ig-app-id, or whatever the app uses for request signing. Pay attention to the request body format too, some apps send JSON, others use protobuf or custom binary formats. If the body looks like gibberish, it's probably signed or encrypted, and thats where the signing key from section 4 comes into play.

A good workflow is to filter by domain first (in Instagram's case, i.instagram.com), then sort by endpoint to see which APIs are being called. Login flows, feed loading, story viewing, each one hits different endpoints with different payloads. Once you map out the main ones, you start to see the patterns.

7. Data Samples & Privacy Concerns

Well, im betting here that if you do happen to actually get to see some of the mainstream apps like Instagram, Twitter, TikTok etc you will be surprised by the amount of data that is being sent to their servers. Its actually INSANE! This is why most of these apps are locked down and try to make it as hard as possible for the regular user to see this data. Some of the data i saw across multiple apps includes:

User Location Data (GPS, IP Address, etc)
Device Hardware Data including: CPU, RAM, Free RAM, Storage, Battery Percentage (YES!)
SIM Card - Carrier Name, Country, etc
Time spent on the App, time spent on each photo/video, clicking points, scrolls, etc
Time spent with the finger over a certain photo, video or post
If your phone is rooted or not, time since you "booted" the device, also first boot, etc

The list goes on and on, while this data could be used for internal analytics, it can also be used for tracking, fingerprinting & ads. Remember the famous sentence, if its free, you are the product? Yeah, we often forget about it, but when you get to see the actual data, you gonna start thinking twice about it.

Here's a redacted sample of a single telemetry batch captured from just opening the Instagram app and navigating to the login screen, this is what gets sent before you even type anything. You will get probably 10s of these batches per minute & everytime you wake up your device or make it sleep.

8. Conclusion

Reverse engineering mobile apps is one of those things that teaches you more about software than most courses ever will. You learn how apps really work under the hood, how security is (or isn't) implemented, and just how much data flows between your phone and someone else's servers without you ever knowing.

I hope this post gave you a decent overview of the process and the tools involved. Whether you're into security research, building tools that interact with private APIs, or just curious about what your favourite apps are doing behind the scenes, the skills are the same. Root/jailbreak, decompile, hook, intercept, analyze.

Just remember, use this knowledge responsibly. The line between "security research" and "getting yourself in trouble" is thinner than you think. Stay curious, stay ethical, and don't do anything stupid.

Links

[[Magisk|https://github.com/topjohnwu/Magisk]] - Root your Android device
[[VPPhone|https://github.com/Lakr233/vphone-cli]] - Virtual iOS devices
[[Corellium|https://corellium.com/]] - Online iOS emulator
[[JEB|https://www.pnfsoftware.com/]] - Android APK decompiler & debugger
[[IDA Pro|https://hex-rays.com/ida-pro/]] - Industry standard disassembler for native code
[[Frida|https://frida.re/]] - Dynamic instrumentation toolkit
[[Wireshark|https://www.wireshark.org/]] - Network protocol analyzer
[[Proxyman|https://proxyman.io/]] - macOS HTTP debugging proxy
[[Charles|https://www.charlesproxy.com/]] - HTTP proxy / monitor
[[mitmproxy|https://mitmproxy.org/]] - Open-source interactive HTTPS proxy
[[Fiddler|https://www.telerik.com/fiddler]] - Web debugging proxy
[[XDA Forums|https://xdaforums.com/]] - Android development community

Bookmarkjar ®

Pedro Martins — Sat, 14 Feb 2026 00:00:00 GMT

AI-powered bookmark manager that saves, organizes, and lets you search your bookmarks with semantic understanding. Find faster, organize less.

Prompt Book

Pedro Martins — Wed, 11 Feb 2026 00:00:00 GMT

Store, search & instantly copy AI prompts from your macOS menu bar — built with Tauri v2 + React.

i18n with TanStack Start: A Complete Guide 2026

Pedro Martins — Tue, 27 Jan 2026 00:00:00 GMT

1. Introduction 🌍

Everyone hates doing i18n for apps, usually its way faster to just hardcode the strings in the code and call it a day, and thats totally valid depending on the project and how fast you need to get it done.

But specially today if you want to market your product to other countries that are not so "English speaking" friendly you might want to consider doing i18n, not only its a great benefit for your users, but also for your SEO and marketing. Even if you want to start just with English, having the strings in a single place might be a good idea to avoid duplication and keep your codebase clean.

BUT, this seems like a daunting task, and usually its a pain to implement in all frameworks that i have tried, specially with the routing logic.

2. Requirements 📋

You might think that this is a simple task right? Or that is probably a package that will just work out of the box? Well, yes and no. i18n can be tricky to implement in any framework, mostly because of the routing logic.

So here is what i usually want as a good i18n implementation:

Single source of truth for the strings for any language
Quickly add new languages with mostly zero effort.
NO prefix for the default language, and prefix for the other languages.
Ability to ignore certain routes to not be prefixed at all ( ex: /dashboard )
Small in Bundle size, and fast to load.
Support SSR, Async loading of the strings.
Ability to store in cookies or local storage, accept the language from the browser or from the user. Choose the best strategy for the job for your use case.

3. How frameworks handle locale prefixes 🛤️

Before diving into strategies, let's see how different frameworks approach optional locale prefixes in routes.

Laravel handles this with route groups, but it's not as simple as it looks:

Route::group(['prefix' => '{locale?}', 'where' => ['locale' => 'es|fr|de']], function () {
    Route::get('/about', [PageController::class, 'about']);
});

The {locale?} is optional and the where constraint ensures only valid locales match. But here's the catch: /random-page would 404 because random-page doesn't match the constraint—but you still need middleware to actually set the default locale when no prefix is provided, and you need to be careful with route ordering.

[[TanStack Router|https://tanstack.com/router]] handles this with optional path parameters using the {-$param} syntax:

// app/routes/{-$locale}.tsx
export const Route = createFileRoute("/{-$locale}")({
  beforeLoad: ({ params }) => {
    const locale = params.locale;
    if (locale && !isValidLocale(locale)) {
      throw notFound();
    }
  },
  component: LocalizedLayout,
});

The - prefix makes the param optional. So /{-$locale}/about matches both /about (no locale) and /es/about (with locale). This is exactly what we need for section 4.3.

The key difference from Laravel: you need to validate in beforeLoad that the param is actually a valid locale, otherwise /random-page would be interpreted as a locale instead of a 404.

4. Prefixing or not to prefix? 🤔

This is one of the most important decisions you'll make, and it affects SEO, user experience, and your routing complexity. There are typically three strategies:

4.1 Always prefix all languages (`/en/about`, `/es/about`)

This is the "easy" approach from a routing perspective—every language gets a prefix, no exceptions.

The problem? Your root / becomes useless. You need a redirect to /en (or detect the language and redirect). This means:

Extra redirect hop = slower initial load
Google sees / as a redirect, not your actual content
Your "main" URLs look ugly: example.com/en/pricing instead of example.com/pricing
Users sharing links always share the prefixed version

From an SEO perspective, Google handles redirects fine, but you're essentially wasting your cleanest URL (/) on a 302/301 redirect instead of actual content.

4.2 Never prefix (detect via cookies/headers)

Clean URLs everywhere! Just /about for everyone, and you detect the language from:

Accept-Language header
A cookie from a previous visit
User's account settings

Why this is terrible for SEO:

Google crawls your site without cookies and with Accept-Language: en. So Google only ever sees your English content. Your Spanish pages? They don't exist to search engines. You can't have proper hreflang tags pointing to different URLs because... there are no different URLs.

Also, CDN caching becomes a nightmare. Same URL, different content based on headers? You need Vary: Accept-Language headers and your cache hit rate drops significantly.

4.3 No prefix for default, prefix for others (`/about`, `/es/about`)

This is the sweet spot, but also the hardest to implement correctly:

/about → English (default, no prefix)
/es/about → Spanish
/fr/about → French

Why it's hard:

Your router needs to handle two different URL patterns for the same page. In most frameworks, routes are defined once. Now you need:

/about           → AboutPage (lang: en)
/es/about        → AboutPage (lang: es)
/fr/about        → AboutPage (lang: fr)

This means your routing logic needs to:

Check if the first segment is a known locale
If yes, extract it and route to the rest of the path
If no, assume default locale and route normally
Handle links generation differently based on target language
Not break when someone adds a page called /essays (is that a locale or a page?)

Most i18n libraries either don't support this, or require you to duplicate every route definition. TanStack Router makes this manageable, but it's still not trivial.

Why it's worth it:

Your primary audience gets clean URLs
Full SEO support with proper hreflang tags
Each language has its own indexable URL
No redirect tax on your most important pages
CDN caching works perfectly (different URL = different cache entry)

This is the strategy we'll implement in this guide.

5. Redirecting the user to the correct language 🔀

Once you got the previous section sorted out we will need to decide, what we do when the user first visits our website?

Let's say a Spanish-speaking user lands on example.com/about (your English default). Should you:

Redirect them to /es/about?
Show English and let them switch manually?
Something in between?

There's no universally correct answer. Let's break down the options:

5.1 Redirect based on `Accept-Language` header

The browser sends an Accept-Language header with every request (e.g., es-ES,es;q=0.9,en;q=0.8). You can read this server-side and redirect accordingly.

Pros:

Feels magical—users see their language immediately
No user action required

Cons:

SEO disaster waiting to happen. Googlebot sends Accept-Language: en. If you redirect based on this header, Google might never index your default language pages properly. You could end up with Google indexing /es/about as your canonical when you wanted /about.
CDN caching breaks. Same URL, different redirects based on headers. You need Vary: Accept-Language which tanks your cache hit rate.
VPN and travel users get wrong language. Someone from Spain traveling in Germany might get German. Someone using a US VPN gets English even though they want Spanish.
Corporate/shared browsers lie. Many corporate machines are set to en-US regardless of the actual user.

The gotcha: If you MUST redirect based on Accept-Language, only do it on the FIRST visit and immediately set a cookie. Never redirect if a cookie already exists. And never, ever redirect if the user explicitly navigated to a prefixed URL—they chose that language.

5.2 Redirect based on cookie (returning visitors)

Store the user's language preference in a cookie when they:

Manually switch languages
Visit a prefixed URL (implicit preference)

On subsequent visits to non-prefixed URLs, redirect based on this cookie.

Pros:

Respects explicit user choice
Works great for returning visitors
No header-based guessing

Cons:

First-time visitors always see default language
Cookie might be stale (user changed preference on another device)
Still has CDN caching implications if you redirect server-side

The gotcha: Be careful with the cookie scope. If you set it on /es, it might not be readable on /. Always set cookies on the root path with path=/.

5.3 No redirect, just show the content

User lands on /about? Show English. User lands on /es/about? Show Spanish. No automatic redirects ever.

Pros:

SEO-perfect. Google sees exactly what you want it to see. No redirect chains, no confusion.
CDN-perfect. Every URL is deterministic. Cache everything aggressively.
Predictable. Users always get what the URL says.
Shareable links work correctly. When someone shares /about, everyone sees English regardless of their browser settings.

Cons:

First-time visitors might see the "wrong" language
Requires clear language switcher UI
Some users expect automatic detection

The gotcha: If you go this route, make your language switcher VERY visible. Don't bury it in a footer dropdown. Consider a banner for detected language mismatch: "This page is available in Español →"

5.4 Hybrid approach (recommended)

Here's what I recommend for most production apps:

Never redirect on page load based on headers alone
Store preference in a cookie when user switches language or visits a prefixed URL
On root / only (not other pages), consider a soft redirect for returning users with a cookie
Show a non-intrusive language suggestion banner for first-time visitors when their Accept-Language doesn't match the current page

┌─────────────────────────────────────────────────────────┐
│ 🌐 This page is available in Español. [Switch] [✕]     │
└─────────────────────────────────────────────────────────┘

This gives you:

Clean SEO (no redirects on content pages)
Good UX for returning visitors
Helpful hint for first-time visitors without being aggressive
Full CDN cacheability (banner can be client-side rendered)

5.5 What about localStorage?

Don't use localStorage for language preference. It's not accessible server-side, so you can't use it for SSR. You'd end up with a flash of wrong language on every page load while the client-side code fixes it. Cookies are the way to go.

5.6 TL;DR - Quick comparison

My preference: No redirect on public pages. The URL dictates the language, period. But I still save the user's preference to a cookie when they switch languages or visit a prefixed URL—this comes in handy for authenticated areas like /dashboard where SEO doesn't matter and you can freely use the cookie to serve the right language without URL prefixes.

6. TanStack Start i18n Integration 🔧

Now that we've covered the theory—prefixing strategies, redirect approaches, and SEO considerations—let's build the actual implementation.

Why a custom solution?

Most i18n libraries focus on translations: loading strings, pluralization, formatting. They assume you'll figure out the routing yourself. The few that do handle routing often make assumptions that don't match our requirements:

They want to prefix all languages (we don't want /en)
They don't support ignored paths (we need /dashboard without prefixes)
They don't integrate well with TanStack Router's rewrite system
They want to control the middleware layer in ways that conflict with TanStack Start

So we're building a lightweight integration layer on top of [[use-intl|https://github.com/amannn/next-intl]]. The translation library handles translations. We handle everything else: routing, URL rewriting, cookie management, and the glue between server and client.

Here's what we're building:

packages/i18n/
├── src/
│   ├── core/
│   │   ├── shared.ts    # Config, types, utilities (used by both)
│   │   ├── client.ts    # URL rewriting, locale detection
│   │   └── server.ts    # Middleware, cookie handling
│   ├── messages/
│   │   ├── en.ts        # English translations
│   │   ├── pt.ts        # Portuguese translations
│   │   └── index.ts     # Message registry
│   ├── entry.client.ts  # Client-side exports
│   └── entry.server.ts  # Server-side exports

Let's break it down piece by piece.

6.1 Why a Separate Package?

Before we dive into code, let's talk about project structure. In our monorepo, we keep i18n in a separate package: packages/i18n.

Why not just a folder in the app?

Server and client need completely different code paths:

Server code imports @tanstack/react-start/server (Node-only APIs)
Client code uses window.location, document.cookie
Mixing them causes bundler errors or bloated client bundles

By creating a package with separate entry points, we keep things clean:

{
  "name": "@app/i18n",
  "exports": {
    "./client": "./src/entry.client.ts",
    "./server": "./src/entry.server.ts",
    "./messages": "./src/messages/index.ts"
  }
}

Now the app imports exactly what it needs:

// In client code
import { getCurrentLocale, localizeUrl } from '@app/i18n/client'

// In server code (middleware)
import { handleLocaleMiddleware } from '@app/i18n/server'

The bundler never pulls server code into the client bundle. No runtime errors, no bloat.

6.2 Why `use-intl`?

There are many i18n libraries out there: [[i18next|https://www.i18next.com/]], [[react-intl|https://formatjs.io/docs/react-intl/]], [[lingui|https://lingui.dev/]], [[paraglide|https://inlang.com/m/gerre34r/library-inlang-paraglideJs]]. We went with [[use-intl|https://github.com/amannn/next-intl]] for a few reasons:

Lightweight — ~2kb gzipped, minimal footprint
TypeScript-first — Full type inference for translation keys
SSR-friendly — No hydration mismatches when used correctly
Simple API — Just useTranslations() and you're done

import { useTranslations } from 'use-intl'

function SignInPage() {
  const t = useTranslations('auth')

  return (
    <div>
      <h1>{t('signIn')}</h1>
      <p>{t('noAccount')}</p>
    </div>
  )
}

The messages are plain objects, easy to maintain:

const en = {
  auth: {
    signIn: 'Sign In',
    signUp: 'Sign Up',
    noAccount: "Don't have an account?",
  },
  common: {
    loading: 'Loading...',
    error: 'An error occurred',
  },
}

Nothing fancy, nothing magical. Just objects and functions.

6.3 What About Paraglide?

[[Paraglide.js|https://inlang.com/m/gerre34r/library-inlang-paraglideJs]] is an excellent i18n solution worth considering. It offers compile-time extraction, a tiny runtime, and great DX. Check out their [[documentation|https://inlang.com/]] for the latest features.

Update (January 27, 2026): Paraglide now has official support for multiple frameworks including TanStack Start, SvelteKit, Astro. Their routing integration supports flexible strategies like no-prefix for default language and ignored paths—exactly what we needed for this project.

Why we went with use-intl for this guide:

When we originally wrote this guide, we chose use-intl (from the [[next-intl|https://next-intl.dev/]] author) because we were already familiar with its patterns and wanted to demonstrate how to build custom routing integration from scratch. It's a solid library with good community support.

That said, Paraglide is a great choice for TanStack Start projects. If you prefer:

Automatic string extraction from code
Compile-time optimizations for the smallest possible bundle
Official framework adapters that handle routing for you
Excellent TypeScript support

...then Paraglide might be the better fit for your project. Both libraries will get the job done well.

6.4 The Shared Foundation

Everything starts with shared.ts—the config and utilities used by both server and client.

// packages/i18n/src/core/shared.ts

export const defaultLocale = 'en'
export const supportedLocales = ['en', 'pt'] as const
export const LOCALE_COOKIE = 'locale'

// Paths that bypass locale handling entirely
export const ignoredPathsRegex = /^\/(?:api|rpc|dashboard)(?:\/|$)/

export type Locale = (typeof supportedLocales)[number]

export function isValidLocale(locale: string | undefined): locale is Locale {
  return supportedLocales.includes(locale as Locale)
}

export function shouldIgnorePath(pathname: string): boolean {
  return ignoredPathsRegex.test(pathname)
}

export function extractLocaleFromPath(pathname: string): Locale | null {
  const match = /^\/([a-z]{2})(?:\/|$)/.exec(pathname)
  const locale = match?.[1]
  return locale && isValidLocale(locale) && locale !== defaultLocale ? locale : null
}

Why ignoredPathsRegex?

Some routes shouldn't have locale prefixes:

/api/* — API endpoints don't need localization in the URL
/rpc/* — Same for RPC handlers
/dashboard/* — Authenticated area, SEO doesn't matter, reads from cookie

This regex lets us skip locale handling for these paths entirely.

6.5 TanStack Router URL Rewriting

Here's where the magic happens. TanStack Router has a rewrite option that transforms URLs:

// apps/web/src/application/router.tsx
import { deLocalizeUrl, localizeUrl } from '@app/i18n/client'

const router = createTanStackRouter({
  routeTree,
  rewrite: {
    input: ({ url }) => deLocalizeUrl(url),
    output: ({ url }) => localizeUrl(url),
  },
})

What does this do?

input (deLocalizeUrl): Strips the locale prefix before routing. User visits /es/about, router sees /about.
output (localizeUrl): Adds the locale prefix when generating links. <Link to="/about"> becomes /es/about.

Why do we need this?

Without rewriting, you'd have two problems:

Every route would need to handle both /about and /es/about explicitly
All your <Link> components would generate wrong URLs

The rewrite functions:

export function deLocalizeUrl(url: URL): URL {
  if (shouldIgnorePath(url.pathname)) return url

  const locale = extractLocaleFromPath(url.pathname)
  if (locale) {
    const newUrl = new URL(url)
    newUrl.pathname = url.pathname.replace(`/${locale}`, '') || '/'
    return newUrl
  }
  return url
}

export function localizeUrl(url: URL): URL {
  if (shouldIgnorePath(url.pathname)) return url

  const locale = getCurrentLocale()
  if (locale === defaultLocale) return url

  const newUrl = new URL(url)
  newUrl.pathname = `/${locale}${url.pathname === '/' ? '' : url.pathname}`
  return newUrl
}

Notice how both functions respect shouldIgnorePath(). Links to /dashboard stay as /dashboard, never /es/dashboard.

6.6 The Layout Route

The /{-$locale} layout route is where we validate the locale param:

// apps/web/src/routes/localized.layout.tsx
import { isValidLocale } from '@app/i18n/client'
import { createFileRoute, notFound, Outlet } from '@tanstack/react-router'

export const Route = createFileRoute('/{-$locale}')({
  beforeLoad: ({ params }) => {
    const locale = params.locale
    if (locale && !isValidLocale(locale)) {
      throw notFound()
    }
  },
  component: LocalizedLayout,
})

function LocalizedLayout() {
  return <Outlet />
}

Why do we need both this AND server middleware?

They handle different things:

The layout route runs inside React, after routing. It can throw notFound() but can't do redirects before HTML is sent. Server middleware runs before React, so it handles redirects and cookie syncing.

6.7 Server Middleware

The server middleware handles everything that must happen before React renders:

// packages/i18n/src/core/server.ts

export function handleLocaleMiddleware(request: Request): LocaleMiddlewareResult {
  const url = new URL(request.url)
  const pathname = url.pathname

  // Skip for ignored paths
  if (shouldIgnorePath(pathname)) {
    return {}
  }

  // Redirect /en/* to /* (default locale shouldn't have prefix)
  if (pathname.startsWith(`/${defaultLocale}/`) || pathname === `/${defaultLocale}`) {
    url.pathname = pathname.replace(`/${defaultLocale}`, '') || '/'
    return { redirect: Response.redirect(url.toString(), 301) }
  }

  const urlLocale = extractLocaleFromPath(pathname)

  if (urlLocale) {
    // Strip locale from ignored paths: /es/dashboard → /dashboard
    const strippedPath = pathname.replace(`/${urlLocale}`, '') || '/'
    if (shouldIgnorePath(strippedPath)) {
      url.pathname = strippedPath
      return { redirect: Response.redirect(url.toString(), 301) }
    }

    // Sync cookie when URL has explicit locale
    const cookieLocale = parseLocaleCookie(request.headers.get('cookie'))
    if (urlLocale !== cookieLocale) {
      return { setCookie: { name: LOCALE_COOKIE, value: urlLocale } }
    }
  }

  return {}
}

Integration with TanStack Start:

// apps/web/src/application/server.ts
import { handleLocaleMiddleware, createCookieHeader } from '@app/i18n/server'
import handler, { createServerEntry } from '@tanstack/react-start/server-entry'

export default createServerEntry({
  async fetch(request) {
    const { redirect, setCookie } = handleLocaleMiddleware(request)

    if (redirect) {
      return redirect
    }

    const response = await handler.fetch(request)

    if (setCookie) {
      const cookieValue = createCookieHeader(setCookie.name, setCookie.value)
      response.headers.append('Set-Cookie', cookieValue)
    }

    return response
  },
})

What this handles:

/en/about → 301 redirect to /about
/es/dashboard → 301 redirect to /dashboard (ignored path)
/es/about → Sets cookie to es if not already set
/about → No action needed

6.8 Client-Side Locale Detection

Getting the current locale needs to work identically on server (SSR) and client. We use TanStack's createIsomorphicFn():

// packages/i18n/src/core/client.ts
import { getRequest } from '@tanstack/react-start/server'
import { createIsomorphicFn } from '@tanstack/react-start'

export const getCurrentLocale = createIsomorphicFn()
  .server(() => {
    const request = getRequest()
    const url = new URL(request.url)

    // Dashboard reads from cookie
    if (shouldIgnorePath(url.pathname)) {
      return parseLocaleCookie(request.headers.get('cookie')) ?? defaultLocale
    }
    // Public pages read from URL
    return extractLocaleFromPath(url.pathname) ?? defaultLocale
  })
  .client(() => {
    // Dashboard reads from cookie
    if (shouldIgnorePath(window.location.pathname)) {
      return parseLocaleCookie(document.cookie) ?? defaultLocale
    }
    // Public pages read from URL
    return extractLocaleFromPath(window.location.pathname) ?? defaultLocale
  })

Why the split logic?

Public pages (/about, /es/about): Locale comes from URL. This is the source of truth for SEO.
Dashboard (/dashboard): No locale in URL, so we read from cookie. User's preference persists across the authenticated area.

This is how we satisfy our original requirement: public pages use URL prefixes for SEO, but dashboard ignores prefixes and uses cookies.

6.9 The Provider Setup

The IntlProvider wraps the app and provides translations via React context:

// apps/web/src/components/context/context.providers.tsx
import { IntlProvider, getClientLocale } from '@app/i18n/client'
import { useSuspenseQuery } from '@tanstack/react-query'
import { useRouterState } from '@tanstack/react-router'

export function Providers({ children }: { children: ReactNode }) {
  const routerPathname = useRouterState({ select: (s) => s.location.pathname })
  const locale = getClientLocale(routerPathname)

  const { data: messages } = useSuspenseQuery(
    rpc.i18n.messages.queryOptions({
      input: locale,
      staleTime: Infinity,
      gcTime: Infinity,
    })
  )

  return (
    <IntlProvider locale={locale} messages={messages}>
      {children}
    </IntlProvider>
  )
}

Why useRouterState?

The provider needs to react to route changes. When navigating from /about to /es/about, the locale changes and we need to fetch Spanish messages.

Why async loading via RPC?

Messages are loaded on-demand per locale. English users never download Spanish strings. With staleTime: Infinity, messages are cached forever (until page refresh).

Setting the lang attribute:

// apps/web/src/routes/root.tsx
function RootDocument({ children }: { children: ReactNode }) {
  const locale = getCurrentLocale()
  return (
    <html lang={locale}>
      <head><HeadContent /></head>
      <body>{children}</body>
    </html>
  )
}

6.10 Type-Safe Localized Links

Regular <Link to="/about"> works but loses type safety for localized routes. We created a LocalizedLink component:

// apps/web/src/components/misc/localized-link.tsx
import { Link } from '@tanstack/react-router'
import type { FileRouteTypes } from '@/application/routes.tree'

type LocalizedFullPaths = Extract<FileRouteTypes['to'], `/{-$locale}${string}`>

type StripLocalePrefix<T extends string> = T extends '/{-$locale}'
  ? '/'
  : T extends `/{-$locale}${infer Rest}`
  ? Rest
  : never

export type LocalizedTo = StripLocalePrefix<LocalizedFullPaths>

export function LocalizedLink<TTo extends LocalizedTo>({
  to,
  ...props
}: LocalizedLinkProps<TTo>) {
  const fullPath = to === '/' ? '/{-$locale}' : `/{-$locale}${to}`
  return <Link to={fullPath} {...props} />
}

Usage:

// Type-safe! Only accepts routes that exist under /{-$locale}/*
<LocalizedLink to="/auth/sign-up">Sign up</LocalizedLink>

// TypeScript error: "/invalid-route" doesn't exist
<LocalizedLink to="/invalid-route">Nope</LocalizedLink>

The router's rewrite.output handles adding the actual locale prefix. You write /auth/sign-up, users see /es/auth/sign-up.

6.11 Adding a New Language

With everything in place, adding a new language is trivial:

1. Create the message file:

// packages/i18n/src/messages/es.ts
const es = {
  auth: {
    signIn: 'Iniciar Sesión',
    signUp: 'Registrarse',
    noAccount: '¿No tienes una cuenta?',
  },
  common: {
    loading: 'Cargando...',
    error: 'Ocurrió un error',
  },
}

export default es

2. Add to supported locales:

// packages/i18n/src/core/shared.ts
export const supportedLocales = ['en', 'pt', 'es'] as const

3. Register in messages index:

// packages/i18n/src/messages/index.ts
import en from './en'
import pt from './pt'
import es from './es'

export const messages: Record<Locale, Messages> = { en, pt, es }

That's it. No route changes, no middleware updates, no config files. The routing, links, and cookie handling all just work.

7. Wrapping Up 🎉

We built a complete i18n solution for [[TanStack Start|https://tanstack.com/start]] that:

✅ No prefix for default language (/about)
✅ Prefix for other languages (/es/about)
✅ Ignored paths read from cookie (/dashboard)
✅ SEO-friendly with proper URLs per language
✅ Type-safe translations and links
✅ SSR-compatible with no hydration issues
✅ Easy to add new languages

The key insight: i18n isn't just about translations. It's about routing, redirects, cookies, and making all these pieces work together. By building on [[use-intl|https://github.com/amannn/next-intl]] and [[TanStack Router|https://tanstack.com/router]]'s rewrite system, we get a solution that's both flexible and maintainable. Now its time to get that SEO score up!

Browser Clutch

Pedro Martins — Sat, 24 Jan 2026 00:00:00 GMT

A browser picker for macOS. Route URLs to different browsers based on app or domain rules. Open work links in Chrome, personal in Safari — you decide.

Twenty Years Building for the Web: From PHP's Simple Server Rendering to TypeScript's Modern Complexity

Pedro Martins — Sun, 26 Oct 2025 00:00:00 GMT

1. Introduction

I have been a PHP & Laravel Developer since I wrote my first lines of code almost 2 decades ago. I always loved doing things for the web, share it, and see it online. Languages like C++, Java, Python never really appealed to me because they were mostly used for backend or visual "offline" projects. I wanted to build for the web, for people to see and use.

If you are reading this and you are old enough, you know how good it was to mix and match PHP on top of your templates & files, interpolate variables, and just call it a day. HTML was there for you, SIMPLE! I miss those days honestly! And it was totally "safe" cough cough. 😅

As we move on over the years we start to take care of more things: SQL injection, XSS, CSRF. We continue our journey to be more secure, more performant, more maintainable, more scalable. The list goes on.

Then we start to see "frameworks" like Yii, CodeIgniter, Symfony, Laravel, etc. which were more "modular" and "opinionated" but still had a lot of flexibility and control over the code. This way we could benefit from their already done functionalities, but still have the ability to customize and extend them to our own needs. How amazing is that?

<?php 
$title = 'Hello World';
$description = 'This is a description';
$items = mysqli_query($conn, "SELECT * FROM items");
?>
<div>
    <h1>{$title}</h1>
    <p>{$description}</p>
    <ul>
        <?php foreach ($items as $item): ?>
            <li>{$item['name']}</li>
        <?php endforeach; ?>
    </ul>
</div>

2. PHP + Laravel Golden Age

There was a time when Laravel offered the BEST developer experience you could find (and still does!). Why? Because we had little to no JavaScript on our projects. Things just worked.

We'd use [[jQuery|https://jquery.com/]] + [[Bootstrap|https://getbootstrap.com/]], render Blade templates, make a few Ajax calls, and call it a day. Database, Queues, Events. Everything in ONE language and ONE framework. No mental overhead, no context switching, no learning multiple ecosystems. Just PHP and Laravel.

We might have peaked here.

// Routes
Route::get('/', [ItemController::class, 'index']);
// Controller
public function index()
{
    $title = 'Hello World';
    $description = 'This is a description';
    $items = Item::all();
    return view('index', compact('title', 'items'));
}

<div>
    <h1>{{ $title }}</h1>
    <p>{{ $description }}</p>
    <ul>
        @foreach ($items as $item)
            <li>{{ $item['name'] }}</li>
        @endforeach
    </ul>
</div>

3. The Rise of Javascript

But the world never stops. For good or bad, we got pushed into doing MORE on the client side. More JavaScript! Interactive websites became the "standard". While jQuery lasted a long time, frameworks like [[React|https://react.dev/]], [[Vue|https://vuejs.org/]], and [[Angular|https://angular.dev/]] took over the frontend world. The reasoning? Browsers could handle the heavy rendering, freeing up server resources for more requests.

This brought the era of APIs: JSON, GraphQL, REST. Now you needed to write API endpoints to serve data to different clients, not just browsers. Developers split into camps. Backend folks handled APIs and business logic, while Frontend devs crafted interactive UIs, real-time dashboards, and modern web applications.

JavaScript was still manageable at this point. We had task runners like [[Gulp|https://gulpjs.com/]] and [[Grunt|https://gruntjs.com/]] to bundle, compress, and minify our files into single or multiple outputs. Simple enough.

But as you'll see in the next section, things were about to get way more complicated. 😬

// Gulp file example
gulp.task('build', function() {
    return gulp.src('src/**/*.js')
        .pipe(gulp.dest('dist'))
        .pipe(uglify())
        .pipe(rename({ suffix: '.min' }))
        .pipe(gulp.dest('dist'));
});

4. Frontend Complexity with Javascript

Well, you think everything was wonderful, right? 😅 Not really! Engineers always find ways to complicate things (job security, am I right?).

With the rise of JavaScript came a tsunami of complexity. We needed to figure out bundling, optimization, rendering strategies, and package distribution. Enter [[Webpack|https://webpack.js.org/]], [[Rollup|https://rollupjs.org/]], [[Parcel|https://parceljs.org/]], and later [[Vite|https://vitejs.dev/]]. And with them? The legendary node_modules folder! The heaviest object in the universe, deeper than the Mariana Trench! 🌊

But why all this complexity? Gulp and Grunt were just task runners that merged and minified files. Modern bundlers are smarter (and way more complicated): code splitting, tree shaking, dead code elimination, minification, source maps, hot module replacement. The list goes on and on and on.

And don't forget the browser wars! You had to support Chrome, Firefox, Safari, and god forbid... IE11. Your code needed transpiling (hello [[Babel|https://babeljs.io/]]!), polyfills for older browsers, and different builds for different targets. What worked in Chrome might break in Safari. Fun times!

The build process went from "save and refresh" to "save, wait 30 seconds for Webpack to rebuild, pray it doesn't error, then refresh." The DX we had with PHP's instant feedback? Gone. Welcome to the world of build times and configuration hell.

Webpack configs became 500+ lines of cryptic magic nobody understood. Just copy-paste from StackOverflow and pray. NPM brought its own drama: the left-pad incident that broke the internet, package hijacking, security vulnerabilities 15 levels deep in dependencies you didn't know existed. 💀

And the tooling fatigue! Every 6 months a new bundler claiming to be "10x faster": Webpack → Parcel → Snowpack → Vite → Turbopack → ??? Even CSS got complicated: plain files → Sass/Less → CSS Modules → CSS-in-JS → [[Tailwind|https://tailwindcss.com/]]. Styling became a build step!

The framework wars didn't help: React vs Vue vs Angular vs Svelte. Each with their own ecosystem, build tools, and "best practices" that changed yearly. Exhausting! 😮‍💨

5. Node.js Enters the Chat

Then came [[Node.js|https://nodejs.org/]]. Ryan Dahl took Chrome's V8 engine and brought JavaScript to the server. The pitch was seductive: "Write JavaScript everywhere! Share code between frontend and backend! One language for everything"

[[Express.js|https://expressjs.com/]] made it simple to build APIs. Later came [[Fastify|https://fastify.dev/]] for performance, [[NestJS|https://nestjs.com/]] for structure (heavily inspired by Angular), and countless other frameworks. The ecosystem exploded. NPM became the largest package registry in the world. JavaScript was no longer just a browser language. It was a legitimate backend contender.

For me as a Laravel and PHP developer, this created an interesting dilemma. Do we keep Laravel & PHP for the backend while still benefiting from the JS ecosystem for the frontend? That's what I have done for a few years till now and still do. We have clear boundaries between the two, and we can still benefit from the JS ecosystem for the frontend.

But we also get the overhead of managing two different ecosystems, two different languages, two different "build" tools, and so on. Not very bueno!

On the other side, the promise of "JavaScript everywhere" was appealing, but it came with trade-offs. Node's async/callback hell (before async/await), different paradigms, and the lack of Laravel's batteries-included approach meant you were building everything from scratch or stitching together dozens of packages. This is where the complexity really starts to kick in.

5.1 The SSR Complexity

With Node.js came the possibility of Server-Side Rendering (SSR). Remember how simple PHP was? Write your template, render on the server, send HTML to the browser. Done.

SSR in JavaScript? Not so simple. Now you need to render React/Vue on the server, send HTML to the browser, then "hydrate" it on the client so it becomes interactive. Sounds easy? Well, you need to handle:

Server and client builds (two separate bundles)
Hydration mismatches (server HTML doesn't match client)
window is not defined errors everywhere
Memory leaks on the server
Data fetching on both server and client

Meta-frameworks like [[Next.js|https://nextjs.org/]] and [[Nuxt|https://nuxt.com/]] eventually made this easier, but the complexity is still there under the hood. What used to be simple server rendering in PHP became a complex dance of server/client coordination. We gained interactivity but lost simplicity. 😅

6. Laravel Inertia JS - Bridging the Gap

Laravel wasn't going to sit still while the JavaScript world took over. [[Inertia.js|https://inertiajs.com]] by Jonathan Reinink is a clever solution that lets you build modern single-page applications using classic server-side routing and controllers. No need to build a separate API. No REST endpoints. No GraphQL schemas. 🎯

Inertia acts as the glue between your Laravel backend and your React, Vue, or Svelte frontend. You return data from your controllers, and Inertia handles the client-side rendering. It feels like traditional server-side rendering but with the interactivity of an SPA. You get the best of both worlds: Laravel's elegant backend with modern JavaScript frameworks on the frontend.

For many Laravel developers, this is the sweet spot. You could keep your PHP expertise, maintain your existing Laravel patterns, and still deliver the modern UX that clients demanded. No need to rewrite everything in Node.js. No need to maintain two separate applications. Just Laravel doing what it does best, with JavaScript sprinkled on top where it matters.

I'm a BIG fan of InertiaJS, being one of the early adopters of the framework, contributing to the community and helping others to get started with it. If you have any questions about InertiaJS, feel free to join our [[Discord Server|https://discord.gg/inertiajs]] and ask away! ❤️

Here's a quick example of how Inertia works:

// Laravel Controller
class UserController extends Controller
{
    public function show(User $user)
    {
        return Inertia::render('Users/Show', [
            'user' => $user,
            'posts' => $user->posts()->latest()->get(),
        ]);
    }
}

// React Component (Users/Show.tsx)
import { Head } from '@inertiajs/react'

// Option 1: No types 😢
interface Props {
  user: any
  posts: any[]
}

// Option 2: Manual types - but you need to keep them in sync! 🔄
interface User {
  id: number
  name: string
  email: string
}

interface Post {
  id: number
  title: string
  content: string
}

interface PropsTyped {
  user: User
  posts: Post[]
}

export default function Show({ user, posts }: PropsTyped) {
  return (
    <>
      <Head title={user.name} />
      <h1>{user.name}</h1>
      <p>{user.email}</p>
      
      <div>
        {posts.map(post => (
          <div key={post.id}>
            <h2>{post.title}</h2>
          </div>
        ))}
      </div>
    </>
  )
}

Simple and elegant! But notice the problem? You can write your own types manually, but now you need to keep them in sync with your backend. Add a field in your Laravel model? You need to remember to update the TypeScript interface. Rename a property? Better not forget to change it in both places! This manual sync is error-prone and tedious. 😓

But how do we keep things typesafe automatically? How do we close the gap between our PHP Backend and our Javascript frontend STILL being typesafe? Let's jump into typescript section for a while and come back to this topic later.

7. TypeScript - JavaScript That Scales

In 2012, Microsoft released [[TypeScript|https://www.typescriptlang.org/]], led by Anders Hejlsberg (the creator of C#). The pitch? JavaScript with optional static typing. At first, many developers were skeptical. "Why would I need types in JavaScript? It's supposed to be flexible!"

But as JavaScript applications grew larger and more complex, the cracks started to show. Refactoring was terrifying. You'd rename a property and hope you caught all the references. Runtime errors that could've been caught at compile time. No autocomplete or IntelliSense worth mentioning. The developer experience was rough for large codebases.

TypeScript changed that. Suddenly you had type safety, interfaces, generics, and incredible tooling. Your IDE could catch errors before you even ran the code. Refactoring became safe. Large teams could work on the same codebase without stepping on each other's toes.

The adoption was gradual but steady. Angular 2+ went all-in on TypeScript. React added first-class support. Vue 3 was rewritten in TypeScript. [[Next.js|https://nextjs.org/]], [[Remix|https://remix.run/]], NestJS. All TypeScript by default. Even Node.js now has built-in TypeScript support with type stripping.

Today, TypeScript isn't just popular, it's the default. Most new JavaScript projects start with TypeScript. It's become what JavaScript should have been from the start: a language that scales from small scripts to massive applications. For me coming from typed languages like PHP (with its type hints), TypeScript feels like coming home.

But it's not perfect. Typescript also brings additional complexity to the table with false sense of security and type safety, while bloating part of your codebase with types everywhere :p

8. Full Stack Laravel + Typescript = The perfect combo?

While working with Inertia, I felt the need to also have my frontend fully typesafe. So when I changed a DTO or a Request/Response, it would reflect on the frontend that the property was not there anymore or it was changed. How cool is that for developers?

This is where [[Laravel Data|https://spatie.be/docs/laravel-data]] by Spatie comes in. It pairs perfect with [[Spatie Typescript Transformer|https://github.com/spatie/laravel-typescript-transformer]], so everytime you change your Data Object it would generate a typescript file with all your definitions and types for your data objects that you can use in your frontend! Yay! We got it right? Yeah partially!

Here is an example of a Data Object in Laravel → Laravel Data → Typescript Transformer:

<?php
namespace App\Data;

use Closure;
use Spatie\LaravelData\Data;
use Spatie\LaravelData\Lazy;

/**
 * The data shared from the server to the client
 * when the user is logged in, includes wallet,
 * notifications, and everything about the user
 */
final class UserAuthenticatedData extends Data
{
    public function __construct(
        public readonly ?UserData $user,
        public readonly ?WalletData $wallet,
        public readonly Lazy|int|Closure $notifications_count = 0,
    ) {}
}

// UserAuthenticatedData.ts
export interface UserAuthenticatedData {
    user: UserData | null;
    wallet: WalletData | null;
    notifications_count: number | Lazy<number> | Closure;
}

// vite.config.ts
import laravel from 'laravel-vite-plugin';
import { run } from 'vite-plugin-run'
export default defineConfig(({ isSsrBuild }) => {
    return {
    plugins: [
      laravel({
        input: [
          'resources/application/main.tsx',
          'resources/application/css/app.css'
        ],
        ssr: 'resources/application/ssr.tsx',
        refresh: true,
      }),
      run({
        silent: true,
        input: [
          {
            name: 'Generate TypeScript Types',
            run: ['php', 'artisan', 'typescript:transform'],
            pattern: [
              'app/**/*Data.php',
              'app/**/Enums/**/*.php',
              'app/**/Http/Requests/**/*Request.php',
              'app/**/Http/Responses/**/*Response.php',
              'app/**/Http/Views/**/*View.php',
            ],
            onFileChanged: () => console.info('[Generators] Generating TypeScript Types 🎨')
          },
        ]
      })
    ],
  }
});

But this also comes at a cost. While you could use the generated types, you will also be required to create a Laravel Data DTO or a form request for EVERY piece that you send to the frontend. This could quickly become a PITA = Overhead! Also it's not out-of-the-box. You would still need to setup all the packages, transforms, get vite dev server to work, etc.

But at least, we got types and the best of both worlds! We have closed the gap between our PHP Backend and our Javascript frontend and we can still benefit from the JS ecosystem for the frontend. But we STILL not there yet in terms of developer experience!

There are also a few issues with this approach:

We get only types, what if we want to [[Zod|https://zod.dev/]] Schemas or [[Standard Schemas|https://github.com/standard-schema/standard-schema]]? humm
What if we need to derive certain types? Omit, Pick, etc? We would still need to write types on the frontend.
How about Generics? We can't use them in PHP because we don't really have generics. So we would need to type the generics on the DTOS with some weird string syntax that is not typesafe :(

Well we got to a point here. While it's not a perfect solution, for me it's a good sweet spot if you wanna keep yourself in the Laravel ecosystem and still benefit from the JS ecosystem for the frontend. I would love to see an official "solution" from Laravel to make this even better. Let's hope so!

9. FullStack Typescript

Well, I have tried a ton of JS/TS full stack approaches in the past 3 years in attempt to mimic our good beloved Laravel. While it's not possible to fully mimic it, I have found a few approaches that are very close to Laravel in terms of DX and developer experience.

While it's easy to fall into the hype train of certain frameworks and tools specially if you are active on [[X|https://x.com]] (twitter), I have tried to stay away from it and focus on trying out myself.

Here is what I have tried so far and what I have found:

[[Next.js|https://nextjs.org/]]: The #1 Framework for React, Huge Ecosystem, great docs, avg DX. But Next lost me with all the unnecessary complexity with the RSC approach, feels like a step back from the "old" React. Also a bit of vendor lock-in with Vercel, while some might say otherwise, that's a fact.
[[Hono|https://hono.dev/]]/[[Elysia|https://elysiajs.com/]]: Both are GREAT! You can build a really nice API in no time, fully typed, OpenAPI spec compliant, Swagger Docs ready for you, it's fast, and it's simple yet powerful.
[[Tanstack Start|https://tanstack.com/start]]: The goat of the frameworks for me, super flexible, fully typed end to end, doesn't get in your way, easy mental model, great community & fully open-source to the core.
[[Vue|https://vuejs.org/]]/[[Nuxt|https://nuxt.com/]]: Pretty amazing also, I would honestly pick Vue/Nuxt any day over React if the ecosystem was the same. Here I said it :p

So my current sweet spot is Tanstack Start + Elysia for the API with RPC calls to the backend. This way we can have the best of both worlds, fully typed end to end. You still have an API if you need it, still can call it from the frontend, full SSR without any overhead, streaming, server actions, one single language, one single codebase in a monorepo using [[Turborepo|https://turbo.build/]], etc.

Here's a quick example of how beautiful the DX is with Elysia + Treaty RPC:

// Backend API with Elysia
import { Elysia, t } from 'elysia'

const app = new Elysia()
  .get('/users/:id', async ({ params }) => {
    const user = await db.user.findUnique({ 
      where: { id: params.id } 
    })
    return { user }
  }, {
    params: t.Object({
      id: t.String()
    })
  })
  .post('/users', async ({ body }) => {
    const user = await db.user.create({ data: body })
    return { user }
  }, {
    body: t.Object({
      name: t.String(),
      email: t.String()
    })
  })
  .listen(3000)

export type App = typeof app

// Frontend with Treaty RPC in Tanstack Router - Fully typed!
import { createFileRoute } from '@tanstack/react-router'
import { treaty } from '@elysiajs/eden'
import type { App } from './server'

const api = treaty<App>('localhost:3000')

export const Route = createFileRoute('/users/$id')({
  beforeLoad: async ({ params }) => {
    // Autocomplete and type safety everywhere! 🎉
    const { data } = await api.users({ id: params.id }).get()
    //     ^? { user: User }
    
    return { user: data.user }
  },
  component: UserProfile
})

function UserProfile() {
  const { user } = Route.useLoaderData()
  //      ^? User - fully typed!
  
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  )
}

This is what I mean by fully typed end to end. Change the backend, and your frontend immediately knows about it. No code generation, no build steps, just pure TypeScript magic! The data flows from your API through your router loader directly into your components, all with perfect type safety.

What do I miss here from Laravel? Queues we got to install [[BullMQ|https://docs.bullmq.io/]] or [[Trigger.dev|https://trigger.dev/]], Auth with [[better-auth|https://www.better-auth.com/]], etc. So you need to glue different pieces together to get the same DX, but once your "boilerplate" is done, I would say it's a tie!

10. PHP ( Laravel ) vs Javascript/Typescript

This is a tough one, because both ecosystems are great and I can't really stand with one side or another. Laravel ecosystem is perfect, and while smaller vs Javascript, this is not a problem if you see it from a different perspective. Because it's not fragmented like Javascript, you will get first party support for most of the things you need but you will also miss some things or get a few things "late" compared to Javascript.

I'll keep this short and give my honest opinion on both ecosystems: ⚖️

10.1 PHP ( Laravel ) Pros ✅

Batteries included: Queues, Events, Jobs, Notifications, ORMs, Auth, Mail etc
Top-tier Documentation
Amazing DX & tooling: [[Telescope|https://laravel.com/docs/telescope]], [[Horizon|https://laravel.com/docs/horizon]], [[Forge|https://forge.laravel.com/]], [[Vapor|https://vapor.laravel.com/]], etc
Scales pretty well with large projects
PHP is mature and very organized in terms of code structure and best practices.
Dependency Injection is a first class citizen, you can easily inject dependencies into your controllers, services, etc
If you embrace the framework and its patterns, you will be able to build very maintainable and scalable applications, buttery smooth!
[[Eloquent|https://laravel.com/docs/eloquent]] is THE ORM!

10.2 PHP ( Laravel ) Cons ❌

It's still PHP, so you still get that gap if you wanna use Javascript for the frontend.
Things tend to come a bit "late" compared to Javascript, say AI tools, etc. Example: [[Prism|https://github.com/echolabsdev/prism]] is amazing but it's not yet comparable to [[Vercel AI SDK|https://sdk.vercel.ai/]] for example.
Serverless is not as mature as Javascript, but it's getting there
Local Env is still meh, you need to rely on [[Herd|https://herd.laravel.com/]], Brew to install PHP, nginx, fpm etc. You could also go with php artisan serve, but yeah, you get the point here.
Smaller community means also less packages, etc.
No generics in PHP, we need to rely on [[PHPStan|https://phpstan.org/]] to get that perfect static analysis and type safety.
While you can, if you go out of the "laravel-way" you will be a bit on your own. If that's the case use Symfony, there I said it.

10.3 Javascript/Typescript Pros ✅

Huge Ecosystem: Millions of packages, frameworks, tools, libraries, etc.
AI tools are first party in Javascript + Python, so we get them first here
Universal, with correct shared code and setup, you can share parts of your codebase between frontend and backend. Example types, little utilities, etc. This is a huge advantage!
Deployment + Serverless is more mature than Laravel, you can deploy to [[Vercel|https://vercel.com/]], [[Netlify|https://www.netlify.com/]], AWS, GCP, etc. First party support for most of the platforms, unlike PHP :(
One file is enough to start with, example with [[Bun|https://bun.sh]] + index.ts you're ready to go!
Fully typed end to end with typescript, zod, standard schemas, etc.
HMR is really nice, get instant feedback while you change a file.
SSR, Sockets, Streaming out of the box
More jobs and higher salaries (could be wrong here but that's what we see so far)

10.4 Javascript/Typescript Cons ❌

Fragmented Ecosystem: Hard to pick a winner sometimes, lots of options also makes it harder to choose and learn.
New boy in the block is common, new framework pops up and then a year later it's gone, risky takes.
Composability is a double edged sword, you can build very modular and reusable code, but you can also build very complex and hard to maintain code if you don't do it right.
Harder to do Dependency Injection, tools like [[Effect|https://effect.website/]] will probably solve this, but still babies in the scene :p
NPM is great but the latest supply chain attacks and vulnerabilities are a bit of a pain, so we need to be careful with what we install and what we use.
Multiple runtimes, you can use Bun, [[Node.js|https://nodejs.org/]], [[Deno|https://deno.com/]], but also pitfalls when using one over the other.
Error Handling & Stack traces are a pain compared to PHP.

11. Conclusion

Like many said, we should avoid framework dramas. At the end of the day being an engineer, you should be able to pick the right tool for the job.

If I would still need a quick app or dashboard I would probably pick Laravel + [[Filament|https://filamentphp.com/]] because it gets the job done fast and easy. But if I would need a more complex application with fancy UI & realtime capabilities I would probably pick Tanstack Start + Elysia.

I really hope PHP will get more "modern" features like Generics and gets closer to the Javascript DX. Also I would love if the Javascript ecosystem would focus on being more mature and laravel-like for a defacto standard (I see you [[AdonisJS|https://adonisjs.com/]]!) 👀

At the end, both ecosystems are amazing, and we should be grateful to have such great tools at our disposal. Keep learning, keep building, and most importantly, keep having fun!

12. Credits & Links

[[Laravel|https://laravel.com/]]
[[Inertia.js|https://inertiajs.com]]
[[Laravel Data|https://spatie.be/docs/laravel-data]]
[[Spatie Typescript Transformer|https://github.com/spatie/laravel-typescript-transformer]]
[[Filament|https://filamentphp.com/]]
[[PHPStan|https://phpstan.org/]]
[[Telescope|https://laravel.com/docs/telescope]]
[[Horizon|https://laravel.com/docs/horizon]]
[[Forge|https://forge.laravel.com/]]
[[Vapor|https://vapor.laravel.com/]]
[[Eloquent|https://laravel.com/docs/eloquent]]
[[Herd|https://herd.laravel.com/]]
[[jQuery|https://jquery.com/]]
[[Bootstrap|https://getbootstrap.com/]]
[[React|https://react.dev/]]
[[Vue|https://vuejs.org/]]
[[Angular|https://angular.dev/]]
[[Gulp|https://gulpjs.com/]]
[[Grunt|https://gruntjs.com/]]
[[Webpack|https://webpack.js.org/]]
[[Rollup|https://rollupjs.org/]]
[[Parcel|https://parceljs.org/]]
[[Vite|https://vitejs.dev/]]
[[Babel|https://babeljs.io/]]
[[Tailwind|https://tailwindcss.com/]]
[[TypeScript|https://www.typescriptlang.org/]]
[[Node.js|https://nodejs.org/]]
[[Express.js|https://expressjs.com/]]
[[Fastify|https://fastify.dev/]]
[[NestJS|https://nestjs.com/]]
[[Next.js|https://nextjs.org/]]
[[Nuxt|https://nuxt.com/]]
[[Remix|https://remix.run/]]
[[Bun|https://bun.sh]]
[[Deno|https://deno.com/]]
[[Tanstack Start|https://tanstack.com/start]]
[[Elysia|https://elysiajs.com/]]
[[Hono|https://hono.dev/]]
[[Zod|https://zod.dev/]]
[[Standard Schemas|https://github.com/standard-schema/standard-schema]]
[[BullMQ|https://docs.bullmq.io/]]
[[Trigger.dev|https://trigger.dev/]]
[[better-auth|https://www.better-auth.com/]]
[[Effect|https://effect.website/]]
[[Vercel AI SDK|https://sdk.vercel.ai/]]
[[Prism|https://github.com/echolabsdev/prism]]
[[Vercel|https://vercel.com/]]
[[Netlify|https://www.netlify.com/]]
[[AdonisJS|https://adonisjs.com/]]
[[Turborepo|https://turbo.build/]]
[[InertiaJS Discord|https://discord.gg/inertiajs]]
[[Laracasts|https://laracasts.com/]]
[[TanStack Discord|https://discord.gg/tanstack]]

The restless mind of thinkers, how obsession, curiosity, and chaos can be a gift

Pedro Martins — Sat, 11 Oct 2025 00:00:00 GMT

1. Introduction

You know the feeling when your brain just can't shut up? Or time is never enough for what you want to learn or do? Well, that's my story as well. While this article might look weird or out of place, it's a story of how obsession, curiosity, and chaos can be a gift sometimes, but also a curse.

Did it happen that you close your laptop but you're still coding in your mind endlessly? Recently I finished watching [[Queen's Gambit|https://www.imdb.com/title/tt10048342/]] and I could relate myself to it, but unfortunately I can't visualize [[VSCode|https://code.visualstudio.com/]] or [[PHPStorm|https://www.jetbrains.com/phpstorm/]] on the roof of my room. Instead, I can plan, architect, design, and build something in my mind. Maybe prepare what I'm doing the next day? Solve problems in my mind or just think about what I will learn next?

Is this a problem? Or is it just the art of being a thinker & the love for learning? Well, I don't know, but do whatever drives you forward. If it makes you happy, it's a gift. 🧠

2. The Storm

Sometimes it starts with something small, a random idea that hits you while you're doing something completely unrelated. Maybe in the shower, maybe drinking coffee, or even taking a shit, and suddenly you need to open your laptop or grab your phone to search for something. It's like a spark that won't leave you alone.

Did you ever want to stop a movie because your brain was somewhere else and all you wanted to do was pause and get that database schema aligned, fearing you might not have the same clean thinking tomorrow? Or have you started to refactor a little bit of your code and ended up in a pile of code, [[GitHub|https://github.com]] issues, pull requests, and an amazing deep dive into the codebase? Well, that's fun!

I know it sounds chaotic, but that chaos is also where the best ideas are born. It's the moment where logic meets obsession and suddenly, you're not forcing creativity, but instead you're riding it. You don't even feel like you're working anymore.

Yeah, it drains us sometimes. But honestly? I live for those moments. That feeling when everything clicks, when you're in that unstoppable flow, that's what keeps me coming back. Maybe that's what the creative storm really is: proof that you care deeply about what you're doing. It's messy, it's loud, it's exhausting, but it's real, and for me that's where the real magic happens.

3. Learning - The Real Oxygen

I don't really "decide" to learn, it just happens. I'll be scrolling on [[X|https://x.com]], or watching a video, and something grabs me. Next thing I know, I've got ten tabs open, half a [[Notion|https://notion.so]] page filled with notes, and a new course I probably won't finish (but at least I started it).

For me it's not about needing to know everything, it's about not being able to ignore curiosity. I feel restless if I go too long without learning something new. Some people relax by watching a show or going out. I relax by discovering, by figuring out how something works, by knowing the internals of something.

I know it sounds intense, but for me, learning feels like breathing. It resets me. Even when I'm tired, if I find something that sparks my curiosity, it gives me energy again. It's like my mind goes, "Oh well! Finally, something to chew on." Sometimes I wonder if I'm chasing too much: new tools, new frameworks, new ideas. But then I remember that curiosity is what keeps me moving. It's what keeps me alive.

Is learning just a skill? Or is it a pulse?

4. AI - Infinite Learning

Something that completely changed how I learn was realizing how much AI can help me stay curious forever. A lot of people see AI as a shortcut or a threat, but I see it as a partner. It's not here to replace thinking, it's here to remove friction.

When I get stuck, I no longer waste hours searching or waiting for the right moment. I can just ask, explore, and keep moving. Whether it's debugging code, understanding a concept, or brainstorming an idea, AI helps me stay in motion. It keeps curiosity alive. 🤖

The best part is that it never judges. You can ask the same question ten times in ten different ways until it clicks. You can go deep into topics that used to feel out of reach and actually understand them at your own pace.

AI doesn't make you less human, it makes you more capable of focusing on what truly matters: creating, learning, and thinking. It keeps the fire of curiosity burning and turns every question into a path forward.

We finally live in a time where learning never really ends, and that might be the greatest gift of all.

There are no excuses anymore!

5. Stopping = Weakness?

One thing I've learned the hard way: stopping doesn't mean you've lost momentum or you are weak per se. I used to think that if I wasn't working, learning, or creating, I was falling behind. That if I stopped, someone else out there was already doing the thing I just paused. It's easy to fall for the trap, especially if you are on [[X|https://x.com]] or [[Bluesky|https://bsky.app]] where you see the community moving forward with a zillion ideas getting implemented. That mindset pushed me forward for a while, until it started to eat me alive.

There are nights when I'm deep in a problem, exhausted, but still pushing because I feel like I should finish it. And every time I do that, I end up making twice as many mistakes and rewriting everything the next day. Funny thing, when I finally step away, take a walk, smoke a cigarette, or even just sleep on it, the answer shows up like it was waiting for me to shut up for five minutes. Step back to go forward!

It took me a long time to realize that rest isn't weakness, it's strategy. The brain keeps working in the background even when we stop forcing it. Sometimes stepping away is the most productive thing you can do.

Now, when I feel that inner voice telling me to push harder, I try to ask myself: am I pushing forward, or just running on fumes? If it's the latter, I shut it down and let things breathe. Because real growth doesn't come from nonstop motion, it comes from rhythm.

Stopping isn’t giving up. It’s making space for your next move.

6. Burnout or Laziness?

This one is confusing because they often look the same. You feel unmotivated, you slow down, and you start wondering what’s wrong with you. But burnout and laziness come from two very different places.

When I'm burned out, I still want to work. I still care. I just can't get my mind to click on something. My focus is gone, my brain feels heavy, and even simple things start to feel impossible. That's not lack of effort, that's just your system shutting down after running too long. It's your body saying "enough."

Laziness is different. Laziness happens when I could do something, but I choose not to. When I tell myself I’m “resting” or “waiting for inspiration,” but really I’m just avoiding the hard parts of the process. Learning is uncomfortable. Growth feels awkward. And sometimes people disguise that fear as burnout because it sounds better than admitting they don’t want to struggle.

It took me a while to admit that to myself. There were times I said I was tired, but deep down I was just scared to start. Scared to be bad at something new, scared to open that documentation, or scared because Jared from [[Bun|https://bun.sh]] knows [[Zig|https://ziglang.org/]] and I would never get there! lol

Now I try to ask myself two simple questions:

Am I tired because I’ve given my all?

Or am I avoiding something because it’s hard?

If I’m tired, I rest. If I’m avoiding, I start. Even small progress is better than waiting for the “right moment.”

Because real burnout needs healing, but laziness needs honesty. One asks for recovery, the other asks for courage.

7. Curiosity > Talent

I’ve never seen myself as naturally talented. Most of the things I know today came from falling into rabbit holes, breaking stuff, and figuring out how to fix it again. Curiosity did what talent couldn’t.

I'm a self-taught developer, and all I did was to start toying around with small [[OGame|https://lobby.ogame.gameforge.com/]] Scripts back in the 2000s, and here we are today, still learning, still exploring, still building. Sometimes it's easier to just sit down and watch a football match or a movie than to actually build something.

Talent helps, sure, but curiosity never runs out. It doesn't care if you're the smartest person in the room. It just wants to understand. That's what keeps you moving forward when others stop. The people who grow the fastest aren't always the most gifted, they're the ones who keep asking "why" long after everyone else has moved on.

I’ve met people way more talented than me who gave up because learning got hard or slow. But curiosity doesn’t care about perfect conditions. It doesn’t wait for motivation. It just pulls you in until you find your own way through.

That's the thing for me: talent might give you a head start, but curiosity keeps you in the race. It's what makes you explore one more idea, read one more page, or test one more version of something that still doesn't work.

Curiosity isn't about being the best. It's about staying interested. And if you stay interested long enough, you eventually become the best at what you love, not because of talent, but because you never stopped learning.

8. There are people around you

When you are obsessed with learning and building, it is easy to disappear into your own world. You start chasing progress so hard that you forget life is happening around you. I have been there and I'm still there sometimes, skipping calls, ignoring texts, telling people "I'm busy" for weeks that turn into months. It is not intentional, it is just that the mind gets stuck in its own loop of goals and ideas. ❤️

But every time I take a break and meet a friend, talk to family, or just share a meal, I realize how much I have been missing. Those small moments recharge something that no tutorial, project, or bit of progress ever could.

It is not about choosing between your passion and the people around you, it is about remembering that both can exist together. The same curiosity that drives you to learn can also help you connect. Ask people about their stories, listen, pay attention. Sometimes the best ideas and the deepest motivation come from those simple conversations.

At the end of the day, success means nothing if you have no one to share it with. The people who care about you are part of your journey too. They remind you to laugh, to slow down, and to stay human.

Keep learning, keep building, but remember to look up once in a while. Send that message. Call that friend. The world outside your thoughts matters just as much as the one you are creating inside them.

IMPORTANT: Re-read this twice please.

9. Conclusion

At the end of the day, the restless mind isn't something to fix. It is something to understand and live with. Curiosity, obsession, chaos, they are not flaws, they are signals that you care deeply about what you do.

If you feel tired, rest. If you feel stuck, learn. If you feel alone, reach out. The balance is never perfect, and it never will be. But maybe that's the point. The storm, the silence, the breakthroughs, the people, it's all part of the same rhythm. ✨

So keep thinking, keep learning, and keep creating. Not to be the best, but to stay alive in the process of becoming.

PS: This article was brought to you in a late night, by a restless mind.

Programming with AI using Claude Code, Roo Code & Cursor 🤖

Pedro Martins — Wed, 27 Aug 2025 00:00:00 GMT

import Callout from "@components/Callout.astro"; import Button from "@components/Button.astro";

1. Introduction ✍️

It feels like ages ago, but the "first" release of [[ChatGPT|https://openai.com/chatgpt]] by [[OpenAI|https://openai.com]] was just a year and a half ago—crazy, isn't it? 🤯 While some people still deny or try to avoid AI because they don't yet see much value in it, I was actually one of the first, among my small group of developers, to embrace it. At the beginning, some of them actually laughed at me, but now all of them use some sort of AI daily 😂

I was super motivated since day one by how even the early versions of ChatGPT could help me out with repetitive tasks. Remember converting a PHP array to JavaScript manually? Crazy, isn't it? Just paste it in GPT and ask! Remember wasting hours finding that missing comma that made your project break so hard? Those days are long gone! 🎉

So let's deep dive into part of my workflow using AI—how I use it, how I approach it, and how I set up my tools. I'll probably miss some topics, but I'll try to keep this article up-to-date.

2. Tools 🛠️

It's 2025, August, and we have a couple of tools available for us to use. There are a TON of them available, but honestly, I don't have "time" yet to test them all. Some of them are also prototypes or not well-polished yet, so I'll use whatever I feel is polished and saves my time! ⚡

I'll focus on 3-4 important tools that I use daily: [[Cursor|https://cursor.com]], [[Claude Code|https://claude.ai/code]], [[Roo Code|https://roocode.com]] (Cline) & [[GPT|https://openai.com]].

2.1. Cursor 💻

[[Cursor|https://cursor.com]] was AMAZING when it was released, but the VC money needs to be paid at some point 💸. I can't deny that I really ENJOYED the first days of Cursor, when it was still used by a small subset of people, where we actually had the chance to even debate prices with the CEO himself! As time went by and with the "Vibe Coding" hype that was going on [[Twitter|https://twitter.com]], it was a matter of time before the price was raised, and they would start capping people who were abusing the free and paid tiers.

[[Cursor|https://cursor.com]] is my main editor at the moment, and I still believe it's a good tool for the price that we pay, even with the 500 requests per month, but unfortunately, it doesn't last me for the whole month if I use it daily.

Here's what I love about Cursor:

Autocomplete - For me, this is worth $10 alone. I was previously using [[Supermaven|https://supermaven.com]] (now part of Cursor too) and was paying $10 per month for it, so yeah, the Tab + Autocomplete is just out of this world and there's no competition so far. [[GitHub Copilot|https://github.com/features/copilot]] is nice, but Cursor tab is just nuts 🔥
UI + Agent UI - This is really nice. While Claude Code is a nice agent, I love being able to simply drag files, tag files, see what we edited, accept changes, and so on. Some people are nerdy enough to say you could do everything in a terminal, yeah, but we're in 2025—let's use UIs too! They're great and save us time 💫
VSCode Ecosystem - Being able to use Cursor with [[VSCode|https://code.visualstudio.com]] extensions is just great. You still benefit from the HUGE VSCode ecosystem. No brainer for me 🧠
Agent - Okay-ish. While there's still a lot of room to improve, the Agent looks okay and does the job most of the time.
Codebase Indexing + Docs - This is a really nice feature! You can index your codebase and your docs, so when you ask or delegate a task, it actually knows exactly how to search "files" and "docs" to find the best answer, making it way better instead of including all the codebase/files in the context.

What I don't like about Cursor:

The price - 500 requests that include tool calls and whatnot might be gone fast if you push it too much. Use your requests wisely! 💸
No support (or partial support) for your own models/API keys. While this isn't a big deal for everyone, I would love to see this happening at some point, but it's not likely to happen soon since it's their core business.
A bit slow and laggy sometimes 🐌
Wish there was better support for multiple mode switching and sub-tasks, etc., so we could use the context in a smarter way.
Context cap - Cursor charges more for the "Max" model, which are basically the same models but with higher context.

I believe after the backlash from the community following the price raise, Cursor started to listen more to the community, and they're actually trying to ship some nice features these days, so let's keep an eye on this one 👀.

2.2. Claude Code 🧠

Well, well, this is the big boy as of today (time of this post). [[Anthropic|https://anthropic.com]] really nailed it with [[Claude Code|https://claude.ai/code]]! I must admit, initially I didn't like the idea of having it in the terminal and was actually expecting a VSCode extension, but I was wrong—this is actually a really nice tool! 🎯

[[Anthropic|https://anthropic.com]] has been leading the AI coding models for a while now, and they did it again with Claude Code + [[Claude Sonnet|https://www.anthropic.com/claude]]. I would say most of the time it does the tasks that I ask perfectly, with very few exceptions.

Here's what I love about Claude Code:

Minimalist - Being in a terminal fits well. It can work with "any" IDE because it's not an actual addon, so it just works—it's fast and easy to use ⚡
Can be installed anywhere you want. Need to code while traveling or at the coffee shop? You bet! Install Claude Code on your old MacBook or [[Raspberry Pi|https://www.raspberrypi.org]] and you're good to go! (I actually do this behind a [[Tailscale|https://tailscale.com]] VPN) 🏖️
Agent - I'm still not sure what they did here with Claude Code, but the agent is just so nice. I actually ran the same task with Sonnet 4 in different tools, and Claude Code did it better most of the time. They have some black magic behind it 🪄
"Unlimited" - They claim unlimited for the max plan. If you do "fair" usage, you could probably use this all day long without being rate limited. Just make sure you edit your button colors yourself and don't delegate it to the agent... PLEASE! 😅

What I don't like about Claude Code:

Nothing? - Nothing really. I'm not sure what to say here. Its just great!
A UI please? - I would love to see a UI for Claude Code.

2.3. Roo Code 🦘

[[Roo Code|https://roocode.com]] (fork of [[Cline|https://github.com/cline/cline]]) is a VSCode Extension that's getting more and more popular, and for good reason. It's open-source, it doesn't opine about the models, fully customizable, and it has a really nice agent as well! 🎨

Here's what I love about Roo Code:

Open-source - Yeah, you can actually contribute and help shape the future of Roo Code, fork it, or do whatever you want with it! 🔓
Customizable - You can customize the agent rules, prompts, create new modes, and so on.
Bring your own keys! - This is really nice! You can plug your [[OpenRouter|https://openrouter.ai]] keys, [[Anthropic|https://anthropic.com]] keys, and even connect it to Claude Code!! 🔑
Mode Switching - This is really a killer feature I would like to see in Cursor. You can basically Plan in the Architect mode, make it perfect, and then it will switch automatically to the Code mode and start executing the task. Here you have the chance to actually use nice models for the planning and then switch to a cheaper model for the actual coding—you could save some nice money here! 💰
Tasks - Roo Code can also "divide" a bigger scope into multiple small tasks while still retaining part of the context of what it has done and what's remaining to do. This is really nice and avoids polluting the context with too much stuff when you're trying to implement a feature that contains a lot of things to do. It can fully go auto-pilot mode, do the small tasks, switch back, and continue where it left off with mostly zero effort! Really nice feature here! 🚗
Codebase Indexing - Recently added, you can index your codebase with [[Qdrant|https://qdrant.tech/]]. It will be like Cursor in this case.
Cost Control - Since you bring your own keys, you can control the cost, how much you spend, etc.

What I don't like about Roo Code:

The UI still needs some work—it could be a bit more polished, but it's getting better, and hey, it's open-source, okay? We can contribute to it! 🛠️
Laggy sometimes 🐌

2.4. OpenAI - GPT 🤖

While I don't use [[OpenAI Codex|https://openai.com/codex]] or [[GPT|https://openai.com/gpt-4]] often for coding or hard-core coding, I tend to use GPT in the browser to investigate quick things, quick questions, let it "web-search" for me topics that I'm curious about, compare choices like frameworks, libraries, and so on. I would say it's my new "[[Google|https://google.com]]" 😄

2.5. Why not VSCode, Copilot, Devin, Windsurf, etc? 🤷‍♂️

Well, at some point you gotta pick what you're comfortable with and stick with something. If you keep jumping between a zillion tools, you won't be actually productive. So nothing against other tools—I'm sharing here what I use personally and what I think is the best fit for me.

I also created [[Days Since Last VSCode Fork|https://dayssincelastvscodefork.com/]] if you're curious about how long it's been since the last time some VC-backed company forked VSCode 😂

2.6. Picking the right tool—how do I do it? 🎯

Well, usually I do the following:

Claude Code - Actual features (important ones), bootstrap projects, and ideas. Bug finding, complex tasks.
Cursor - Quick tasks in a file or two, trying to save up some requests, or when I need to tag a few files and I'm bored to actually do it on Claude Code.
Roo Code - When I want a proper plan + execution and I want to explore some ideas while giving Claude Code some time to breathe.
Often I could delegate different tasks (as long as they don't touch the same files) to Claude Code + Cursor + Roo Code at the same time.

3. Prompting 📝

This is a very important topic! Most of the time, people are lazy enough to prompt. It's known that if you don't prompt correctly, you will probably also get bad results. LLMs are not magic—they need context, and you need to clearly explain what you want to achieve and what's your goal with a specific task. Sometimes you need to give it a little "hint" to point it in the right direction, and that makes a lot of difference in the results! 🎯

Some people debate whether you waste more time prompting and battling the AI while you could do the code yourself—that's correct! It happened to all of us. Sometimes you just wish you would have written the code yourself and you would probably spend less time, but I also think, how much time did I actually save? I would probably end up net positive! 😛

If you're lazy, ensure that you have some prompts saved somewhere that you could easily copy and paste or get ideas from! 💡

Here are some examples of basic prompts I do often:

 Ensure methods are single worded lower case if possible. If we are in "Browser", you dont need a method called "browserCleanup" -> cleanup() simple!!!
- You will be taking advantage of typescript return types and things that are infered by typescript without needing to define the return types unless its really needed.
- You will ensure best pratices for async patterns and promise patterns in JS, so avoiding awaits in for loops and prefer Promise.all()
- Avoid redundant Variables
- Ensure we dont do .push for example in async patterns that could lead to weird behaviour.
- Organize the types, avoid nesting types and extract smaller pieces like Arrays or Array of Objects into a new type to ensure we can read the types better.
- Dont create unecessary functions, unless we really need. Keep it inline whenever possible.
- Avoid more then 3 nested ?? null coalesce for example.
- Prefer ?? over || 
- Document methods with what they do, but dont write the params types on the signature. Keep it short.
- Remove any useless comments in the code that provide no value
- Avoid esle if and prefer early returns.
- If you need a lot of ifs, probably use ts-pattern package so we can use a "match"
- Lint and typecheck the file in question to ensure it gets passed the check tests

You will streamline this extractor, in a standard way so every other extract would follow the same patterns.

Here are some rules:

- Ensure if the map is complex, to see if we could streamline it
- attempt to avoid for loops, prefer promisses
- If always follow the same pattern for returning errors for example create a createError() for example.
- We want the following api clean!
- If needed you can create a file for each mapper, in this case create a folder next to the instagram, leaving the crawler a minimal "interface":
-- src/crawlers/api/github-crawler.ts
-- src/integrations/github/github-post.ts
-- src/integrations/github/github-profile.ts
With the way above, the code is really clean and each extractor as its own place.

That's about it—you don't need to write a full and super-duper detailed prompt, just the minimum effort to get the job done.

4. Project Rules 📋

Well, with 3 different tools and probably more to come during this year, and all of them having their own rules file (which is a bad idea, to be honest), we want to make sure that our project rules are the same for all of them at all times.

You probably already know what project rules are, but they basically define the "base" instructions that you want AI to follow in each conversation/agent/session. This will guarantee that you will get greater results, and AI will follow (hopefully 😅) these rules.

I really hope [[agents.md|https://agents.md/]] will be a thing in the future so we can stop this madness of having to create a rules file for each tool. If just .env, vite.config.ts, .eslintrc, .prettierrc, etc., are not enough—just 3 more files, bro! PLEASE! 😩

To overcome this (and because sometimes you don't want to ask your teammates to add 30 files and folders to .gitignore, or you're scared they will fire you because you're using AI tools), you can:

Add a global gitignore that will ignore the .roo, CLAUDE.md, and .cursor for every project you touch.
Or you can convince them to use [[Ruler|https://github.com/intellectronica/ruler]], a nice tool that will apply your rules to all other "tools" that you might want. So you have a single file that is kept in "sync" with all other tools.

Here's my config for Ruler:

# .ruler/ruler.toml
[agents.claude]
enabled = true
output_path = "CLAUDE.md"

[agents.cursor]
enabled = true
output_path = ".cursor/rules/global.mdc"

[agents.cline]
enabled = true
output_path = ".roo/rules/global.md"

---
description: My Monorepo - Project Structure & Rules
globs: **/*
alwaysApply: true
---
# My Monorepo - Project Structure & Rules 📑

## Overview

A Turbo monorepo for a web app to save and search stuff from various sources using AI

Then on your package.json you can add the following command to apply the rules:

"scripts": {
  "ruler": "ruler apply --agents claude,cursor,cline"
}

That's it! When you change your base instructions, you can just run bun ruler and it will apply the rules to all other tools.

4.1. Generating Project Rules ⚙️

This is probably "basic" for most people (probably). You should use /claude init or ask Cursor to generate the rules for you, BUT never forget to give it a look and tweak it to your own taste and needs. Sometimes these rules are quite generic and contain a lot of stuff that is probably useless for your project. Tokens are not free, so you should be smart about it! 💸

Here's a small example of what I usually do:

Psst. This is a secret project I'm releasing soon! 🤫

---
description: Bookmarks Monorepo - Project Structure & Rules
globs: **/*
alwaysApply: true
---

# Bookmarks Monorepo - Project Structure & Rules 📑

## Overview

A Turbo monorepo for a web app to save and search bookmarks from various sources (Twitter, GitHub, etc.) using AI

## Monorepo Structure

- **Package Manager**: Bun (v1.2.20)
- **Build System**: Turbo + Vite (using rolldown-vite)
- **Frontend Framework**: React 19 + TanStack Router/Start
- **Database**: PostgreSQL + Drizzle ORM
- **Styling**: Tailwind CSS v4 + Shadcn UI
- **Search**: Meilisearch
- **Background Jobs**: Trigger.dev
- **Real-time**: Pusher/Laravel Echo (WebSockets)
- **AI**: Vercel AI SDK, OpenAI
- **Authentication**: Better Auth
- **Storage**: S3/R2 compatible storage

### Root Level

- `turbo.json` - Turbo pipeline configuration with task dependencies
- `package.json` - Root workspace with Turbo scripts and version overrides
- `bun.lock` - Bun lockfile for dependencies

### Applications (`apps/`)

- `apps/web/` - Main bookmarks web application (React + TanStack Start)
- `apps/browser-extension/` - Browser extension for bookmarks (active development)

### Shared Packages (`packages/`)

- `packages/ai/` - AI utilities and prompt building
- `packages/attempt/` - Error handling utilities with tryCatch patterns
- `packages/cli/` - Command line interface utilities
- `packages/crawler/` - Web crawling functionality
- `packages/database/` - Drizzle ORM schema and migrations
- `packages/env/` - Environment variable validation
- `packages/eslint-config/` - Shared ESLint configuration with custom rules
- `packages/indexer/` - Meilisearch indexing utilities
- `packages/integrations/` - External service integrations (GitHub, Twitter)
- `packages/logger/` - Logging utilities
- `packages/monitoring/` - Performance and error monitoring
- `packages/sockets/` - WebSocket authentication and types
- `packages/storage/` - File storage abstractions (S3, R2, local)
- `packages/types/` - Shared TypeScript types and Zod schemas
- `packages/typescript-config/` - Shared TypeScript configurations (base + react)
- `packages/ui/` - Shadcn UI components and hooks
- `packages/utils/` - General utility functions

## Web App Structure (`apps/web/src/`)

src/
├── components/    # React UI components
├── console.ts     # CLI commands entry point
├── css/          # Tailwind CSS styles
├── entry-points/ # App entry points (client, server, router)
├── hooks/        # React hooks
├── jobs/         # Trigger.dev background jobs
├── lib/          # Utilities and configurations
├── prompts/      # AI prompt templates
├── routes/       # TanStack Router route components
├── routes.ts     # Route configuration
└── services/     # Business logic and API layer

## Tech Stack

- **Frontend**: React 19 + TanStack Router/Start
- **Database**: Drizzle + Postgres
- **Styling**: Tailwind CSS v4 + Shadcn
- **Package Manager**: Bun
- **AI**: Vercel AI SDK, Meilisearch
- **Build System**: Turbo + Vite
- **Jobs**: Trigger.dev
- **Architecture**: Laravel inspired MVC

## Key Commands

- `bun run build` - Build all packages
- `bun run dev` - Run main app in development
- `bun run lint:fix` - Lint all packages with shared config
- `bun run typecheck` - Run typescript Checks
- `bun lint:fix && bun typecheck`- Run both

## Package Dependencies

- Apps use workspace packages via `workspace:*` protocol
- TypeScript version consistency enforced via root overrides
- ESLint configuration shared across all packages
- Caching handled by Turbo in `.turbo/` folder

## Development Rules

### TypeScript & Types

- **Zod Types**: Use `z.infer<typeof Schema>` for Zod-derived types
- **Imports**: Use `import * as` for namespace imports (services, Radix/Shadcn)
- **Type Safety**: Prefer type inference, interfaces over types, no TS enums
- **Coercion**: Use `z.coerce.number()` for ID fields that may come as strings
- **Return Types**: Let TypeScript infer return types when possible. Only add explicit return types when:
  - External APIs return `any` (chrome/browser APIs, fetch responses)
  - Type inference breaks due to complex logic
  - Public API methods that need documented return types
- **Type Organization**: Extract shared types to dedicated files in `src/types/` folder
- **No ANY**: Never use `any` type except when dealing with external API responses where typing is impossible

### Code Organization

- **Services**: Export plain functions, use classes sparingly
- **Actions**: TanStack Server Functions with `attempt.try()` error handling
- **Components**: Extend component props with `ComponentProps<typeof Component>`
- **File Naming**: kebab-case for files/directories
- **Method Naming**: Use single-word method names when possible (e.g., `sync()` instead of `syncBookmarks()`)
- **Business Logic**: Keep business logic out of React components - use service classes/functions
- **State Management**: Centralize state operations within service methods, not in components
- **Utilities**: Prefer static methods within service classes over separate utility files

### Error Handling

- **Result Pattern**: Use `attempt.try()` for [error,data] patterns instead of try/catch
- **Client Errors**: Set `client: true` in attempt options for user-facing errors
- **Custom Errors**: Use `ErrorException('ERROR_CODE')` for known error types
- **Error Mapping**: Provide error mappers in attempt options

### Code Style

- **Early Returns**: Always prefer early returns over nested conditions
- **No Nested Ternaries**: Keep conditionals readable
- **Destructuring**: Destructure props and options at function start
- **Nullish Coalescing**: Use `??` over `||` for nullable values
- **Pattern Matching**: Use `ts-pattern` for complex conditionals
- **React Conditionals**: Use ternary operators (`condition ? <Component /> : null`) instead of `&&` pattern to avoid leaked values
- **Comments**: Remove useless comments, keep code self-documenting
- **Function Organization**: Remove unused methods, inline browser API calls when single-use
- **Generic Functions**: Use generic types with proper constraints for reusable utilities (e.g., `sort<T extends Bookmark>(bookmarks: T[])`)
- **No Comments**: Do not add comments unless explicitly requested by the user

### Database

- **Query Builder**: Use Drizzle ORM with `db.query` syntax
- **Transactions**: Support optional `tx` parameter for transaction support
- **Relations**: Use `with` clause for eager loading related data
- **Validation**: Always question new columns, prefer defaults over null-checking

### Performance

- **Parallel Processing**: Use `Promise.all()` for concurrent operations
- **Batching**: Batch database queries and API calls when possible
- **Caching**: Cache expensive operations with appropriate TTL

### Package Manager

- **Bun**: Use `bun` for all package management tasks

### Key Dependencies

- **Zod v4**: All validation (`import { z } from 'zod/v4'`)
- **TanStack**: Router, Query, Start for full-stack patterns
- **Drizzle ORM**: Database with type safety (`db.query` syntax)
- **ts-pattern**: Functional pattern matching with `match()`
- **react-hook-form**: Form management with Zod validation
- **Motion**: Animations (`motion/react`)
- **Radix UI**: Headless components via `radix-ui`
- **CVA**: Component styling variants

### Database Schema Workflow

- **Tables**: Define in `packages/database/src/schema.ts`
- **Schemas**: Mirror in `packages/types/src/database.schema.ts` with Zod
- **Sync**: Keep database and Zod schemas synchronized
- **Relations**: Export tables and relations separately

### Tasks & Jobs

- Interate on lints, first do everything then on the end run `bun lint:fix && bun typecheck`
- Dont attempt to run tests or anything unless asked, ask me to test and ill do it and paste the output
- Once your are done with a task, please also give a double "check" to make sure everything is done and working as expected

### Development Server & Debugging

🚨 **CRITICAL**: **NEVER** run `bun run build` or `bun run dev` commands when debugging or pair programming! This interferes with the user's development workflow.

**Rules for Development Server:**

- **User controls the dev server** - Always ask the user to start/stop development servers
- **Never build for production** during debugging - it creates cached files that break HMR
- **Ask for logs** - Request console output, error logs, or debugging information from the user
- **Let user test** - Ask user to test functionality and paste results/logs
- **HMR workflows** - Respect that users may be running Hot Module Reload and your builds can break their workflow

**When debugging browser extensions:**

- Ask user to reload extension in browser after code changes
- Request specific console logs from extension devtools vs browser console
- Never run build commands - let the user's dev server handle file updates

**Correct debugging approach:**

❌ bun run build
❌ bun run dev
✅ "Can you start the dev server with bun run dev?"
✅ "Please reload the extension and paste the console logs"
✅ "Can you test this and share what logs you see?"


#### Naming Conventions

- **Files/Directories**: kebab-case (e.g., `user-service.ts`)
- **Classes**: PascalCase (e.g., `UserService`)
- **Variables/Methods**: camelCase (e.g., `getUserById`)
- **Database Tables**: snake_case (e.g., `user_bookmarks`)
- **Database Columns**: camelCase with snake_case for timestamps (e.g., `userId`, `created_at`)
- **Service Methods**: Single-word names when possible (e.g., `sync()`, `get()`, `set()`, `clear()`)
- **Integration Methods**: Domain validation (`isValid()`), data operations (`sync()`, `fetch()`, `parse()`)
- **Avoid Verbose Names**: Prefer `twitter()` over `syncTwitterBookmarks()`, `browser()` over `syncBrowserBookmarks()`

5. Controlling the Output and Code Quality 🎨

Well, as we've seen before, we can do a lot to make our output better, instruct AI better, and try to save time. While this could look like it's really easy to get on the right track, after you're done with a setup that you like, you'll probably just copy-paste or tweak to other projects or tasks that you're doing daily.

BUT, while AI can do a lot of code, it's important to keep monitoring the output and code quality. We are not "vibe coding" here—we're actually trying to get AI to do creative work, help us save time, and unblock real-world problems. If you're not getting the results you want, try switching your prompt, the way you ask, or the way you instruct AI to do something. That's often the problem. It could also happen that AI models are being nerfed, and you should just go touch grass 😛 or actually do code, because that's what you're paid for? lol 😂

6. What you should not do 🚫

Small Tasks - If you want to change a color or a font-size, please just do it yourself, or at dont cry when your Cursor/Claude requests are gone, if you did you deserve to pay for it:p
Know when when to stop session/chat - There is limited context, so if you feeling like your doing too much on a session/chat, try to start a fresh one!
Stuck in Endless Loop - If you feel like AI is not giving you the results you want, dont get mad! Breath a bit, start a new chat and try to approach it in a different way, explain different things, give more context.
Dont stop being a programmer - You are programmer, so please be creative, while its nice to get AI by your side, dont forget to be creative, understand what your code is doing, what it should do, and how you want to shape it, you are in control!

6. Conclusion 🎉

Well, that's it for now! Just wanted to brain dump some thoughts and ideas, and workflows that I use daily. Things are changing, so it's highly likely that this will be outdated in a few months, but I hope you enjoyed this article and that you'll find it useful.

OH, this article was NOT written by AI btw lol! I just fixed typos sorry for that!

If you're on X or Bluesky make sure to give me a follow! [[@nikuscs|https://x.com/nikuscs]] or [[@nikus|https://bsky.app/profile/nikuscs.bsky.social]] 🐦

7. Resources 📚

[[@anthropic|https://anthropic.com]]
[[Claude Code|https://claude.ai/code]]
[[Roo Code|https://roocode.com]]
[[Cursor|https://cursor.com]]
[[OpenAI GPT|https://openai.com]]
[[Tailscale|https://tailscale.com]]
[[Qdrant|https://qdrant.tech]]
[[OpenRouter|https://openrouter.ai]]
[[Ruler|https://github.com/intellectronica/ruler]]

Generate Dynamic SEO Images with Vercel OG (Satori) for Tanstack Start, Astro & Laravel

Pedro Martins — Wed, 30 Jul 2025 00:00:00 GMT

import Callout from "@components/Callout.astro"; import Button from "@components/Button.astro";

1. Introduction 🚀

Not too long ago, we created static SEO images for our websites (and that's still valid!). If you're in the SEO game and it matters to you, having an og:image is essential - especially when sharing your website on social media platforms, Discord, Slack, and other platforms.

The og:image should be the "main" image of the page or what you want to highlight, usually related to the page content. If none is provided, search engines like Google will take the first image found on the page and use it as the preview for SERP results.

But you're probably here for a reason 😌 - to generate dynamic SEO images or on-demand images, right?

[[GitHub|https://github.com]] was one of the first to implement this, generating dynamic SEO images on-demand that show current repository stats like forks, stars, and issues, plus Pull Request information and text in real-time. This was amazing because sharing these on Slack or Discord would instantly show what the current Pull Request is about, giving you a clear view in seconds!

Thankfully, [[@shuding|https://github.com/shuding]] 🐐 created [[Satori|https://github.com/vercel/satori]] / [[@vercel/og|https://www.npmjs.com/package/@vercel/og]], a library to generate dynamic SEO images using HTML, JSX, CSS, and even [[Tailwind CSS|https://tailwindcss.com]] support.

In this article, we'll explore how to implement this in TanStack Start and Astro, but the same principles can be applied to any JavaScript framework.

Let's jump into the code:

2. Creating an Image Generator 🎨

Since this can run in any framework, we'll abstract our logic away from the framework and create a generic image generator. In this example, I'll showcase what I've used for my Astro blog, but you can tweak it to your own needs and add more information.

import type { CollectionEntry, CollectionKey } from "astro:content";
import { SITE } from "@consts";
import { ImageResponse } from '@vercel/og';
import fs from 'node:fs'
import path from 'node:path'
import { encode } from "blurhash";
import { getPixels } from "@unpic/pixels";
import { blurhashToCssGradientString } from "@unpic/placeholder";

/**
 * Loads a font from Google Fonts
 * @param font - The font name
 * @param text - The text to load the font for
 * @param weight - The font weight to load
 * @returns The font data
 */
async function loadFont(font: string, text: string, weight: number) {
  const url = `https://fonts.googleapis.com/css2?family=${font}:wght@${weight}&text=${encodeURIComponent(text)}`
  const css = await (await fetch(url)).text()
  const resource = css.match(/src: url\((.+)\) format\('(opentype|truetype)'\)/)
  if (resource) {
    const response = await fetch(resource[1])
    if (response.status == 200) {
      return await response.arrayBuffer()
    }
  }
  throw new Error('failed to load font data')
}


/**
 * Generates a SEO image for a blog post or project
 * @param title - The title of the blog post or project
 * @param text - The text to display in the image
 * @param description - The description of the blog post or project
 * @param tags - The tags of the blog post or project
 * @param image - The image to display in the image
 * @returns The SEO image
 */
export interface SeoImageGeneratorProps {
  title: string;
  text: string
  image?: {
    src: string
    width: number
    height: number
    format: 'png' | 'jpg' | 'jpeg' | 'webp' | 'tiff' | 'gif' | 'svg' | 'avif'
  };
}

export async function generateSeoImage({
  title,
  image,
  text
}: SeoImageGeneratorProps) {

  const assetsPrefix = process.env.NODE_ENV === 'development' ? './public' : './dist'
  const siteImage = fs.readFileSync(path.resolve(assetsPrefix, 'static/avatar.png'))

  const siteImageElement = {
    type: 'img',
    props: {
      tw: 'w-6 h-6 rounded-full mr-2',
      src: siteImage.buffer,
    },
  };

  const siteTitleElement = {
    type: 'div',
    props: {
      tw: ' opacity-70',
      style: {
        fontFamily: 'Geist',
      },
      children: SITE.TITLE,
    },
  }

  const separatorElement = {
    type: 'div',
    props: {
      tw: 'px-2 opacity-70',
      children: '•',
    },
  };

  const siteSubtitleElement = {
    type: 'div',
    props: {
      tw: 'opacity-70',
      style: {
        fontFamily: 'Geist',
      },
      children: title,
    },
  };

  const siteImageAndTitleContainer = {
    type: 'div',
    props: {
      tw: 'flex items-center justify-start w-full mb-2',
      children: [siteImageElement, siteTitleElement, separatorElement, siteSubtitleElement],
    },
  };
 
  let imageElement = null
  let shouldBlur = false
  if (image && shouldBlur) {
    const img = fs.readFileSync(
      process.env.NODE_ENV === 'development'
        ? path.resolve(image.src.replace(/\?.*/, '').replace('/@fs', ''),)
        : path.resolve(image.src.replace('/', 'dist/')),
    );
    const imgData = await getPixels(new Uint8Array(img));
    const data = Uint8ClampedArray.from(imgData.data);
    const blurhash = encode(data, imgData.width, imgData.height, 4, 4);
    const gradient = blurhashToCssGradientString(blurhash, 5, 5);

    imageElement = {
      type: 'div',
      props: {
        tw: 'w-full h-full absolute inset-0 rotate-90',
        style: {
          opacity: 0.07,
          background: gradient,
        },
      },
    };
  }

  const gradientElement = {
    type: 'div',
    props: {
      style: {
        background: 'radial-gradient(circle at bottom right, rgba(255, 255, 255, 0.2), rgba(255, 255, 255, 0.02), rgba(255, 255, 255, 0))',
      },
      tw: 'w-full h-full absolute flex inset-0 opacity-40',
    },
  };

  const mainTextElement = {
    type: 'div',
    props: {
      tw: 'text-5xl leading-none text-left',
      style: {
        fontFamily: 'Geist',
        fontWeight: '400',
      },
      children: text,
    },
  };

  const containerElement = {
    type: 'div',
    props: {
      tw: 'flex flex-col items-center justify-center max-w-3xl w-full',
      children: [
        siteImageAndTitleContainer,
        {
          type: 'div',
          props: {
            tw: 'shrink flex w-full',
            children: [
              mainTextElement,
            ],
          },
        },
      ],
    },
  }

  const footerElement = {
    type: 'div',
    props: {
      tw: 'absolute right-[15px] bottom-[15px] flex items-center justify-center opacity-70 text-xs',
      children: [
        SITE.URL_SHORT,
      ],
    },
  }

  const html = {
    type: 'div',
    props: {
      tw: 'relative w-full h-full flex flex-col items-center justify-center relative relative text-white',
      style: {
        background: '#0a0a0a',
        fontFamily: 'Geist',
        fontSmoothing: 'antialiased',
      },
      children: [
        imageElement,
        gradientElement,
        containerElement,
        footerElement,
      ],
    },
  } as any


  const weights = [100, 200, 300, 400, 900] as const

  const fontConfigs = [
    ...weights.map(weight => ({ name: 'Geist', weight })),
    ...weights.map(weight => ({ name: 'Geist Mono', weight })),
  ]

  const fonts = await Promise.all(
    fontConfigs.map(async ({ name, weight }) => ({
      name,
      data: await loadFont(name, text, weight),
      style: 'normal' as const,
      weight,
    }))
  )

  return new ImageResponse(html, {
    width: 1200,
    height: 630,
    fonts,
    debug: false,
  })
}

/**
 * Generates a SEO image for a blog post or project
 * @param entry - The entry to generate the SEO image for
 * @param type - The type of the entry
 * @returns The SEO image
 */
export interface SeoImageGeneratorForContentProps {
  entry: CollectionEntry<"blog"> | CollectionEntry<"projects">;
  type: CollectionKey
}

export async function generateSeoImageForContent({ entry, type }: SeoImageGeneratorForContentProps) {
  const {
    title: text,
    ...rest
  } = entry.data;

  const title = {
    blog: 'Blog',
    projects: 'Projects',
  }[type]

  return generateSeoImage({
    title,
    text,
    image: entry.data.cover,
    ...rest,
  })
}

Let's break down what we've done in this file to keep it simple and maintainable:

Create multiple elements, we could inline everything, but to keep it easy to manage iv went this way
Use tailwindcss classes to style the elements ( keep in mind not every utility is supported, but most of them are )
We can also pull and attach images from the entry data, like the cover image, a logo or favicon if needed.
Blurhash to generate a gradient background for the image, this is optional, but it looks nice and gives a nice touch to the image without looking always the same color/style.
Loading Fonts from Google Fonts directly, we using Geist here. You can also load local fonts if needed.
Finally, we return the ImageResponse, which is the image that will be used as the SEO image.

This is all it takes to create a generic image generator, you can tweak it to your own needs and get more information going on.

Now lets see how we serve this image, probably the easiest part!

3. Serving the Image 🚀

3.1. TanStack Start

With [[@tanstack|TanStack Start|https://tanstack.com/start]], you'll want to create a server route to serve the image.

For a blog post, we could create a route under src/routes/blog/$slug[.]png.ts

Note: If you're using virtual routes, don't forget to add it to your routes configuration.

// src/routes/blog/$slug[.]png.ts
import { generateSeoImageForContent } from '@/lib/seo-image-generator'

export const ServerRoute = createServerFileRoute().methods({
  GET: async ({ request, params }) => {
    // Call your database to get article by the slug for example
    const article = await db.query.articles.findFirst({where: and(eq(tables.articles.slug, params.slug))})

    if (!article) {
      return new Response('Article not found', { status: 404 })
    }
    
    return await generateSeoImageForContent({ entry: article, type: 'blog' })
  }
})

That's it! We have a server route that generates the image and returns it as a response. We'll explore below what we can do to optimize this further.

3.2. Astro

With [[@astro|Astro|https://astro.build]], you'll want to create a server route to serve the image.

For a blog post, we could create a route under src/pages/blog/[slug].png.ts

import { getCollection, type CollectionEntry } from 'astro:content'
import type { APIRoute } from 'astro'
import { generateSeoImageForContent } from "@lib/seo-image-generator"

type MaybeCollectionEntry = CollectionEntry<"blog"> | CollectionEntry<"projects">

export async function getStaticPaths() {
	const posts = await getCollection('blog')
	return posts.map((post) => ({
		params: { id: post.id },
		props: post,
	}))
}

export const GET: APIRoute = async ({ props }) => {
	const image = await generateSeoImageForContent({
		entry: props as MaybeCollectionEntry,
		type: 'blog',
	})
	return image
}

That's it! When you generate your Astro site, you'll have a route that generates the image and copies your images to the dist folder.

3.3. Laravel / PHP

While this could be more challenging in PHP land, there are a few options. We can still achieve this with [[@laravel|Laravel|https://laravel.com]]. In this case, we'll create a Bun script to generate the image, then use the [[Spatie Media Library|https://spatie.be/docs/laravel-medialibrary]] to store the image.

For a blog post, we could create an action under app/Actions/GenerateBlogPostOGImageAction.php

<?php

namespace App\Actions;

use App\Enums\MediaCollectionEnum;
use App\Enums\System\FilesystemDiskEnum;
use App\Models\Media;
use App\Models\BlogPost;
use Illuminate\Support\Str;
use Spatie\MediaLibrary\MediaCollections\Exceptions\FileDoesNotExist;
use Spatie\MediaLibrary\MediaCollections\Exceptions\FileIsTooBig;
use Symfony\Component\Process\Process;

final class GenerateBlogPostOGImageAction
{
    /**
     * @throws FileDoesNotExist
     * @throws FileIsTooBig
     */
    public function handle(BlogPost $blogPost): void
    {
        // Remove any existing og images
        // @phpstan-ignore-next-line
        $blogPost->getMedia(MediaCollectionEnum::OGImage->value)->each(fn (Media $media) => $media->delete());

        $avatar = $blogPost->getFirstMedia(MediaCollectionEnum::Avatar->value)?->getUrl();
        $temporaryFile = tempnam(sys_get_temp_dir(), MediaCollectionEnum::OGImage->value);

        $parameters = [
            config('app.bun_path', 'bun'), base_path('scripts/og-image.ts'),
            '--output', $temporaryFile,
            '--title', $blogPost->title,
            '--description', $blogPost->description,
            ...($avatar ? ['--avatar', $avatar] : []),
        ];

        $process = new Process($parameters, env: [
            'NODE_TLS_REJECT_UNAUTHORIZED' => '0',
        ]);

        $process->run();
        if ($process->isSuccessful()) {
            $blogPost
                ->addMedia($temporaryFile)
                ->usingName($blogPost->uuid)
                ->usingFileName($blogPost->uuid.'.png')
                ->toMediaCollection(MediaCollectionEnum::OGImage->value, FilesystemDiskEnum::OGImages->value);
        } else {
            logger($process->getErrorOutput());
        }
        @unlink($temporaryFile);
    }
}

4. Optimizing & Performance ⚡

While this is great and super fast, and we've got our dynamic image sorted out, sometimes we can optimize this further - especially if the image doesn't change often.

With Astro, you can use the getStaticPaths() function to generate the paths for images. When you build to a static site, Astro will generate these images beforehand, so no further requests will be made to the server.

For TanStack Start with a more "dynamic" approach, I'd recommend a few strategies:

Generate or cache the image on the server - serve cached version if it already exists
Set caching headers so the image is cached longer in the browser
Use a CDN to cache the image globally for faster delivery

5. Conclusion

That's about it! I hope you enjoyed this article, and if you have any questions, feel free to reach out to me on [[@nikuscs|https://x.com/nikuscs]].

Thanks for reading! Special thanks to [[@shuding|https://github.com/shuding]] for creating [[Satori|https://github.com/vercel/satori]] 🙏

6. Resources 📚

[[@shuding|https://github.com/shuding]]
[[satori|https://github.com/vercel/satori]]
[[@vercel/og|https://www.npmjs.com/package/@vercel/og]]
[[@tanstack|TanStack Start|https://tanstack.com/start]]
[[@astro|Astro|https://astro.build]]
[[@laravel|Laravel|https://laravel.com]]
[[@spatie|Spatie Media Library|https://spatie.be/docs/laravel-medialibrary]]

WebSockets with Pusher - Real-time Events, Notifications with Laravel & TanStack Start

Pedro Martins — Mon, 21 Jul 2025 00:00:00 GMT

import Callout from "@components/Callout.astro"; import Button from "@components/Button.astro";

1. Introduction

WebSockets are an excellent way to build real-time applications, but they can be tricky to implement. It's been a while since I've used WebSockets in my projects, especially with [[Laravel|https://laravel.com/]] and [[@tanstack|TanStack Start|https://tanstack.com/start]], so I thought it would be a good idea to write about it.

If you're using [[Laravel|https://laravel.com/]] like I did for a long time, dispatching jobs and notifying users in real-time can provide a nice UX improvement, and it's probably the only "clean" way to handle this. Of course, you could always use polling, but that's not the best solution in the long run. Let's explore how to implement this in Laravel (PHP) and [[@tanstack|TanStack Start|https://tanstack.com/start]] (JavaScript).

2. WebSocket Servers ⚡

While you could build your own WebSocket servers, sometimes it's just not worth the effort—you want to ship your app without worrying about maintaining another service.

There are several solutions you can choose from. I'm biased toward Pusher because of my Laravel background, but that doesn't mean you can't use other solutions. In this article, I'll explore the Pusher solution, but other solutions like [[socket.io|https://socket.io/]] are also excellent, and I might update this article in the future.

Here are a few you can pick from:

[[Pusher|https://pusher.com/]] ( Paid as a service )
[[Sockudo|https://sockudo.app/]] ( Pusher compatible, Open source, self-hosted, Rust )
[[Soketi|https://soketi.app/]] ( Pusher compatible, Open source, self-hosted )
[[Socket.io|https://socket.io/]] ( Open source, self-hosted )
[[Partykit|https://partykit.io/]] ( Open source, self-hosted )
[[Laravel Reverb|https://reverb.laravel.com/]] ( Pusher compatible, Laravel specific, Open source )
[[Crossws|https://unjs.io/packages/crossws/]] ( Open source, barebones )
[[uWebSockets|https://github.com/uNetworking/uWebSockets]] ( Open source, barebones )
[[ws|https://github.com/websockets/ws]] ( Open source, barebones )

There are tradeoffs to each solution, and you should pick the one that fits your needs best. For me, most of the time I don't need super high performance or blazing-fast solutions, so I would just pick Pusher-compatible solutions because they're easy to integrate, include authentication, and you can use the Pusher JS SDK and call it a day.

I'll explore some self-hosted solutions here, but you can also use Pusher as a service—it's an excellent solution if you're not interested in self-hosting.

2.1 - Laravel Reverb 📡

[[Laravel Reverb|https://reverb.laravel.com/]] is a Pusher-compatible solution for Laravel. If you're a Laravel user, it's probably the best solution for you, as it pairs perfectly with your current deployment pipeline and integrates with Laravel.

I'll cover the basic installation and setup here, but you can find more information in the [[Laravel Reverb documentation|https://laravel.com/docs/12.x/reverb]].

php artisan install:broadcasting

In your environment file:

REVERB_APP_ID=my-app-id
REVERB_APP_KEY=my-app-key
REVERB_APP_SECRET=my-app-secret

php artisan reverb:start --host="0.0.0.0" --port=8080 --hostname="laravel.test"

Yes, it should be this easy! 🎉

2.2 - Sockudo 🦀

[[Sockudo|https://sockudo.app/]] is a new project written in Rust. It's a Pusher-compatible solution that's very easy to set up because it ships as a single binary—you can just download it and run it. While I previously used [[Soketi|https://soketi.app/]], it seems Soketi has been abandoned, so for me this is the best solution right now for a "plug-and-play" approach, especially if you're in the JavaScript ecosystem where Reverb isn't an option.

First, grab the latest release from the [[Sockudo GitHub|https://github.com/RustNSparks/sockudo/releases]] and run it as follows:

sockudo --config=./config.json

Here's an example config.json I use locally. For production, you should use environment variables. Please refer to the [[Sockudo documentation|https://sockudo.app/guide/configuration/app-manager.html#environment-variables-for-app-manager]] for more information about setting up default apps.

{
  "debug": true,
  "adapter": {
    "driver": "redis",
    "redis": {
      "requests_timeout": 5000,
      "prefix": "sockets_",
      "redis_pub_options": {
        "url": "redis://127.0.0.1:6379"
      },
      "redis_sub_options": {
        "url": "redis://127.0.0.1:6379"
      }
    }
  },
  "app_manager": {
    "driver": "memory",
    "array": {
      "apps": [
        {
          "id": "my-app-id",
          "key": "my-app-key",
          "secret": "my-app-secret",
          "max_connections": "10000",
          "enable_client_messages": true,
          "max_client_events_per_second": "200",
          "enabled": true
        }
      ]
    }
  },
  "cache": {
    "driver": "redis",
    "redis": {
      "redis_options": {
        "url": "redis://127.0.0.1:6379",
        "prefix": "sockets_cache"
      }
    }
  },
  "port": 6001
}

3. Server-Side Implementation 🛠️

Now that we have our Pusher service up and running, we can implement the server-side components like authentication, event dispatching, and more.

3.1 - Server-Side with Laravel 🐘

If you're using Laravel, this is provided for you. You can use Laravel Events and implement traits like ShouldBroadcast and ShouldBroadcastNow on your events. Let's explore how to do it.

If you ran the php artisan install:broadcasting command, you should have a BroadcastingServiceProvider and a route file called channels.php that handles authentication for different channels.

<?php

use App\Models\User;
use App\Services\Cart\CartService;
use Illuminate\Support\Facades\Broadcast;

/*
|--------------------------------------------------------------------------
| Broadcast Channels
|--------------------------------------------------------------------------
|
| Here you may register all of the event broadcasting channels that your
| application supports. The given channel authorization callbacks are
| used to check if an authenticated user can listen to the channel.
|
*/

Broadcast::routes(['middleware' => ['web']]);

Broadcast::channel('App.Models.User.{id}', function (User $user, $id) {
    return $user->id === (int) $id;
});

// Example of a channel for a cart
// In this case a guest-authenticated middleware should be used.
Broadcast::channel('App.Models.Cart.{uuid}', function (User $user, string $uuid) {
    return (new CartService)->get()->uuid === $uuid;
});

3.1.1 - Dispatching Events & Notifications 📢

Now that we have our authentication endpoint and channels set up, we can start dispatching events and notifications. I'll cover how to do this in JavaScript later, but for now let's explore how to do it in PHP.

This simple event broadcasts to the currently logged-in user with the event refresh:xxxx, where xxx can be anything you want—a table ID, cart ID, dialog ID, etc.

<?php

namespace App\Events;

use App\Helpers\Broadcast;
use App\Models\User;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Broadcasting\PrivateChannel;

final class RefreshUIEvent implements ShouldBroadcastNow
{
    use Dispatchable;
    use InteractsWithSockets;
    use Queueable;
    use SerializesModels;

    public function __construct(
        protected User $user,
        protected string $uniqueKey,
    ) {}

    public function broadcastOn(): PrivateChannel
    {
        return [
            new PrivateChannel('user.'.$this->user->id),
        ];
    }

    public function broadcastAs(): string
    {
        return 'refresh:'.$this->uniqueKey;
    }

    public function broadcastWith(): array
    {
        return [];
    }
}

</CodeTab> <CodeTab label="usage.php">

use App\Events\RefreshUIEvent;

event(new RefreshUIEvent($user, 'my-unique-key'));

</CodeTab> </CodeTabs>

We can then dispatch this event from anywhere in our codebase, like a job, a controller, a service, etc.

There's much more to cover here, but nothing beats diving into the [[Laravel Broadcasting documentation|https://laravel.com/docs/12.x/broadcasting#main-content]]. You can implement this in many ways—handy aliases, presence channels, and more. I want to keep this article focused on the WebSocket implementation, so I won't cover all the other features.

3.2 - Server-Side with TanStack Start (JavaScript) ⚡

While Laravel does all the heavy lifting for us (and we're spoiled), in JavaScript land we need to do a bit more work. But fear not! This is where this article and the community shine.

First, let's see how we can mimic Laravel's authentication part by creating a simple auth service. I'll try to replicate Laravel's channel registration pattern that we're familiar with: user.{userId}.

authenticator.channel<UserChannelParams>('user.{userId}', (user, params) => {
  //logger.info('🔑 Authenticating user', user, params)
  return Number(user.id) === Number(params.userId)
})

The following code is a bit complex but does the job and ensures several things:

Validates pattern syntax and matches channel names to patterns
Supports presence channels and private channels in a Pusher-like interface
Uses [[Better Auth|https://better-auth.com/]] to get user sessions and inject user data into channels
That's probably all we need for now, but you can extend it to your needs!
Compatible with [[Laravel Echo|https://github.com/laravel/echo]]

// src/services/sockets/sockets.auth.ts
import { logger } from '@bookmarks/logger'
import { auth } from '@/services/auth/auth.better-auth'
import type { SocketsChannelConfig, SocketsChannelParams, SocketsAuthCallback, SocketsMatchedChannelInfo, SocketsAuthOptions, SocketsAuthResponse, SocketsAuthErrorResponse, SocketsChannelPrefix, SocketsAuthUser } from './sockets.types'
import type Pusher from 'pusher'

interface StoredPatternInfo<
  TParams extends SocketsChannelParams,
  TPresenceData extends Pusher.PresenceChannelData
> {
  config: SocketsChannelConfig<TParams, TPresenceData>;
  patternParts: string[];
}

export class SocketAuthenticator<TUser extends SocketsAuthUser = SocketsAuthUser> {

  private channelPatternsByLength = new Map<number, StoredPatternInfo<any, any>[]>()

  private options: Required<SocketsAuthOptions>

  constructor(opts?: SocketsAuthOptions) {

    if (!opts?.pusher) {
      throw new Error('Pusher instance is required')
    }

    this.options = {
      privateChannelsPrefix: opts.privateChannelsPrefix ?? 'private-',
      presenceChannelsPrefix: opts.presenceChannelsPrefix ?? 'presence-',
      pusher: opts.pusher
    }
  }

  /**
   * Register a channel pattern with its auth callback
   */
  public channel<
    TParams extends SocketsChannelParams = SocketsChannelParams,
    TPresenceData extends Pusher.PresenceChannelData = Pusher.PresenceChannelData
  >(
    name: string,
    callback: SocketsAuthCallback<TParams, TPresenceData>,
  ): void {
    const normalizedName = name.replace(/^\.+|\.+$/g, '')

    // Validate pattern syntax
    this.validatePattern(normalizedName)

    const config: SocketsChannelConfig<TParams, TPresenceData> = { pattern: normalizedName, callback }
    const patternParts = normalizedName.split('.').filter(Boolean)

    const entry: StoredPatternInfo<TParams, TPresenceData> = {
      config,
      patternParts,
    }

    const len = patternParts.length
    if (!this.channelPatternsByLength.has(len)) {
      this.channelPatternsByLength.set(len, [])
    }
    const entries = this.channelPatternsByLength.get(len)
    if (entries) {
      logger.info(`✅ Registered auth callback for channel pattern: ${normalizedName} (Segments: ${len})`)
      entries.push(entry)
    }
  }

  /**
   * Clear all registered patterns (useful for testing)
   */
  public clearChannels(): void {
    this.channelPatternsByLength.clear()
  }

  /**
   * Validate pattern syntax
   */
  private validatePattern(pattern: string): void {
    // Check for balanced braces
    const braces = pattern.match(/[{}]/g) ?? []
    if (braces.length % 2 !== 0) {
      throw new Error(`❌ Invalid pattern syntax: unbalanced braces in "${pattern}"`)
    }

    // Check for empty parameter names
    const paramMatches = pattern.match(/\{[^}]*\}/g) ?? []
    for (const param of paramMatches) {
      if (param === '{}') {
        throw new Error(`❌ Invalid pattern syntax: empty parameter in "${pattern}"`)
      }
    }

    // Check for invalid characters in parameter names
    for (const param of paramMatches) {
      const paramName = param.slice(1, -1)
      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(paramName)) {
        throw new Error(`❌ Invalid pattern syntax: invalid parameter name "${paramName}" in "${pattern}"`)
      }
    }
  }

  /**
   * Handle the socket auth request
   */
  public async handle(request: Request): Promise<SocketsAuthResponse> {
    const user = await this.session(request)

    if (!user) {
      return this.forbidden('❌ Unauthorized: user not found, banned or invalid')
    }

    const formData = await request.formData()
    const socketId = formData.get('socket_id') as string | null
    const channelName = formData.get('channel_name') as string | null

    if (!socketId) {
      return this.error('Socket ID is required')
    }

    // We dont have a channel but we have a user, i guess its ok.
    if (!channelName) {
      const userData = this.getUserPresenceData(user)
      const response = this.options.pusher.authenticateUser(socketId, userData)
      return this.ok(response)
    }

    // Attempt to match a channel for the given channel name prefixed
    const channel = this.matchChannel(channelName)

    if (!channel) {
      logger.warn(`❌ Forbidden: Channel ${channelName} (socket: ${socketId}) doesn't exist`)
      return this.forbidden('Channel not found or invalid')
    }

    const {
      config,
      params,
      prefix,
    } = channel

    try {
      // Here we call the provided registered callback to see if the user is authorized to join the channel
      // Similar to how laravel does it.
      const result = await config.callback(
        user as Pusher.UserChannelData,
        params,
        socketId,
        channelName,
      )

      // A special case here for the presence channel, where we can return additional data, but also the user presence data
      if (prefix === this.options.presenceChannelsPrefix && typeof result === 'object' && result !== null) {
        const response = this.options.pusher.authorizeChannel(socketId, channelName, {
          ...result,
          ...this.getUserPresenceData(user),
        })
        return this.ok(response)
      }

      // If the callback returns true, we authorize the channel
      if (result === true) {
        logger.info(`✅ Authorized channel "${channelName}". User: ${user.id}, Socket: ${socketId}, Pattern: "${config.pattern}"`)
        const response = this.options.pusher.authorizeChannel(socketId, channelName)
        return this.ok(response)
      }

      logger.warn(`❌ Forbidden: Access denied by callback for channel "${channelName}". User: ${user.id}, Socket: ${socketId}, Pattern: "${config.pattern}"`)
      return this.forbidden('Access denied')
    } catch (error) {
      logger.error(`❌ Error in channel auth callback for "${config.pattern}" (channel: ${channelName}):`, error)
      return this.error('Internal server error during auth callback')
    }
  }

  /**
   * Resolve the user session from the request ( in this case better-auth )
   */
  private async session(request: Request) {
    const authSession = await auth.api.getSession({ headers: request.headers })

    if (!authSession?.session || !authSession.user.id) {
      return null
    }
    return authSession.user as unknown as TUser
  }

  /**
   * Get the user presence data
   */
  private getUserPresenceData(user: TUser) {
    return {
      id: String(user.id),
      user_info: { name: user.name ?? user.username ?? 'Anonymous' },
    }
  }

  /**
   * Return a forbidden error
   */
  private forbidden(message: string): SocketsAuthErrorResponse {
    return { body: { message }, status: 403 }
  }

  /**
   * Return an error
   */
  private error(message: string): SocketsAuthErrorResponse {
    return { body: { message }, status: 500 }
  }

  /**
   * Return a success response
   */
  private ok(response: Pusher.ChannelAuthResponse): SocketsAuthResponse {
    return { body: response, status: 200 }
  }

  /**
   * Match the channel name to the channel config
   */
  private matchChannel<
    TParams extends SocketsChannelParams,
    TPresenceData extends Pusher.PresenceChannelData
  >(name: string): SocketsMatchedChannelInfo<TParams, TPresenceData> | null {

    let prefix: SocketsChannelPrefix | null = null
    let channelToMatch: string

    if (name.startsWith(this.options.privateChannelsPrefix)) {
      prefix = this.options.privateChannelsPrefix as SocketsChannelPrefix
      channelToMatch = name.substring(this.options.privateChannelsPrefix.length)
    } else if (name.startsWith(this.options.presenceChannelsPrefix)) {
      prefix = this.options.presenceChannelsPrefix as SocketsChannelPrefix
      channelToMatch = name.substring(this.options.presenceChannelsPrefix.length)
    } else {
      return null
    }

    if (!channelToMatch || !prefix) {
      return null
    }

    const match = this.findChannelMatch<TParams, TPresenceData>(channelToMatch)

    if (!match) {
      return null
    }

    return {
      config: match.config,
      params: match.params,
      prefix,
      name,
    }
  }

  /**
   * Find matching channel pattern for the given channel name
   */
  private findChannelMatch<
    TParams extends SocketsChannelParams,
    TPresenceData extends Pusher.PresenceChannelData
  >(channelToMatch: string): { config: SocketsChannelConfig<TParams, TPresenceData>; params: TParams } | null {
    const requestParts = channelToMatch.split('.').filter(Boolean)
    const relevantPatternEntries = this.channelPatternsByLength.get(requestParts.length)

    if (!relevantPatternEntries) {
      return null
    }

    for (const entry of relevantPatternEntries) {
      const { config, patternParts } = entry

      const params: SocketsChannelParams = {}
      let match = true

      for (let i = 0; i < patternParts.length; i++) {
        const patternPart = patternParts[i]
        const requestPart = requestParts[i]

        if (patternPart.startsWith('{') && patternPart.endsWith('}')) {
          const paramName = patternPart.substring(1, patternPart.length - 1)
          params[paramName] = requestPart
        } else if (patternPart !== requestPart) {
          match = false
          break
        }
      }

      if (match) {
        return {
          config,
          params: params as TParams,
        }
      }
    }
    return null
  }

}

Here are the type definitions for the auth service:

import type { UserChannelData } from 'pusher'
import type Pusher from 'pusher'

export interface SocketsAuthOptions {
  pusher: Pusher
  privateChannelsPrefix?: string
  presenceChannelsPrefix?: string
}

export interface SocketsAuthUser {
  id: string | number
  [key: string]: any
}

export interface SocketsPresenceChannelData {
  user_id: string | number
  user_info?: Record<string, any>
}

export type SocketsChannelParams = Record<string, any>

export type SocketsChannelPrefix = 'private-' | 'presence-'

export type SocketsAuthCallback<
  TParams extends SocketsChannelParams = SocketsChannelParams,
  TPresenceData extends SocketsPresenceChannelData = SocketsPresenceChannelData,
  TUser extends UserChannelData = UserChannelData,
> = (
  user: TUser,
  params: TParams,
  socketId: string,
  channelName: string,
) => Promise<boolean | TPresenceData> | boolean | TPresenceData

export interface SocketsChannelConfig<
  TParams extends SocketsChannelParams = SocketsChannelParams,
  TPresenceData extends SocketsPresenceChannelData = SocketsPresenceChannelData,
> {
  pattern: string
  callback: SocketsAuthCallback<TParams, TPresenceData>
}

export interface SocketsMatchedChannelInfo<
  TParams extends SocketsChannelParams = SocketsChannelParams,
  TPresenceData extends SocketsPresenceChannelData = SocketsPresenceChannelData,
> {
  config: SocketsChannelConfig<TParams, TPresenceData>
  params: TParams
  prefix: SocketsChannelPrefix
  name: string
}

export interface SocketsAuthResponse {
  body: any
  status: number
}

export interface SocketsAuthErrorResponse {
  body: {
    message: string
  }
  status: number
}

Great! Now that we can authenticate channels, let's also have an entry point. Every time we call the WebSocket server, we need to ensure our callback is registered somewhere.

Note: Make sure this is done only once!

import Pusher from 'pusher'
import { env } from '@/env'
import { SocketAuthenticator } from '@/services/sockets/sockets.auth'
import type { User } from '@/types'

export const pusher = new Pusher({
  appId: env.PUSHER_APP_ID ?? '',
  key: env.PUSHER_APP_KEY ?? '',
  secret: env.PUSHER_APP_SECRET ?? '',
  host: env.PUSHER_HOST ?? '',
  port: env.PUSHER_PORT ?? '',
  useTLS: env.PUSHER_SCHEME === 'https',
  cluster: 'mt1',
})

export const authenticator = new SocketAuthenticator<User>({ pusher })

interface UserChannelParams {
  userId: string
}

authenticator.channel<UserChannelParams>('user.{userId}', (user, params) => {
  //logger.info('🔑 Authenticating user', user, params)
  return Number(user.id) === Number(params.userId)
})

Now let's ensure we also have an endpoint like Laravel's. I'll place this in a file called broadcast.auth.ts in our API routes. This file ensures that when the frontend connects to the WebSocket server, it will be authenticated and can join channels (regardless of which channel it is).

// src/routes/api/broadcast.auth.ts
import { json } from '@tanstack/react-start'
import { authenticator } from '@/services/sockets/sockets.server'

export const ServerRoute = createServerFileRoute().methods({
  POST: async ({ request }) => {
    const { body, status } = await authenticator.handle(request)
    return json(body, { status })
  },
})

Now we can finally dispatch demo events to connected clients. Here's a simple example:

import { pusher } from '@/services/sockets/sockets.server'
const userId = '1'
await pusher.trigger(`private-user.${userId}`, 'article.created', { articleId: '1' })

In this example and in my apps, I use this to trigger events from [[Trigger.dev|https://trigger.dev]] jobs. When a job finishes, I can notify the user and invalidate the [[@tanstack|TanStack Start|https://tanstack.com/start]] router cache to reload the results.

4. Client-Side Implementation 🎯

Now that we have our server-side implementation fairly complete, let's see how to implement the client-side part. For simplicity, I'll use Laravel Echo. You could use the Pusher JS SDK if you prefer—just make sure to adjust the authentication and channel prefixes accordingly.

4.1 - Client-Side with Laravel Echo & React ⚛️

In this example, I'll use a React Context Provider to ensure we can wrap our Layout with it, so the socket connection is available everywhere, connects once, and is available for registering new listeners anywhere.

Let's break down the code before we start, so you can understand what's happening:

Create a Context Provider
Initialize the Echo client once
Clean up channels/connections when the component unmounts
Store the connection state in context
Provide a clean way to join new channels

import { createContext, useContext, useState, useRef, useEffect } from 'react'
import type { ReactNode, Dispatch, SetStateAction } from 'react'
import { env } from '@/env'
import type Echo from 'laravel-echo'

interface SocketOptions {
  encrypted?: boolean;
}

type EchoType = Echo<'reverb' | 'pusher'>

interface SocketState {
  connected: boolean;
  reconnecting: boolean;
  socketId: string | null;
  channels: string[];
}

interface SocketContextType {
  client: EchoType | null;
  connect: () => void;
  disconnect: () => void;
  addChannel: (channel: string) => void;
  removeChannel: (channel: string) => void;
  state: SocketState;
  setState: Dispatch<SetStateAction<SocketState>>;
}

const SocketContext = createContext<SocketContextType | null>(null)

export interface SocketProviderProps {
  children: ReactNode
  options?: SocketOptions
}

export function SocketProvider({
  children,
}: SocketProviderProps) {

  const [state, setState] = useState<SocketState>({
    connected: false,
    reconnecting: false,
    socketId: null,
    channels: [],
  })

  const clientRef = useRef<EchoType | null>(null)
  const didBoundInitialEvents = useRef(false)

  const initializeClient = async () => {
    if (typeof window !== 'undefined') {
      // @ts-expect-error
      window.Pusher = await import('pusher-js').then(m => m.default)
    }

    const { default: Echo } = await import('laravel-echo')

    clientRef.current = new Echo({
      broadcaster: 'pusher',
      key: env.VITE_PUSHER_APP_KEY,
      wsHost: env.VITE_PUSHER_HOST,
      wsPort: env.VITE_PUSHER_PORT ? Number(env.VITE_PUSHER_PORT) : 6001,
      wssPort: env.VITE_PUSHER_PORT ? Number(env.VITE_PUSHER_PORT) : 6001,
      disableStats: true,
      cluster: 'mt1',
      forceTLS: env.VITE_PUSHER_SCHEME === 'https',
      encrypted: env.VITE_PUSHER_ENCRYPTED === 'true',
      enabledTransports: ['ws', 'wss'],
      authEndpoint: '/api/broadcast/auth',
    })

  }

  const bindEvents = () => {
    if (didBoundInitialEvents.current || !clientRef.current) return

    const client = clientRef.current
    setState(prev => ({
      ...prev,
      connected: client.connector.pusher.connection.state === 'connected',
      socketId: client.socketId() ?? null
    }))

    client.connector.pusher.connection.bind('connected', () => {
      setState(prev => ({
        ...prev,
        connected: true,
        reconnecting: false,
        socketId: client.socketId() ?? null
      }))

      console.info('⚡ Socket was Connected with ID: ', client.socketId())
    })

    client.connector.pusher.connection.bind('disconnected', () => {
      setState(prev => ({
        ...prev, connected: false,
        reconnecting: false,
        socketId: null
      }))

      console.info('⚡ Socket Disconnected')
    })

    client.connector.pusher.connection.bind('reconnecting', (attemptNumber: number) => {
      setState(prev => ({
        ...prev, connected: false,
        reconnecting: true,
        socketId: null
      }))

      console.info('⚡ Socket is Trying to reconnect', attemptNumber)
    })

    didBoundInitialEvents.current = true
  }

  const unbindEvents = () => {
    if (!clientRef.current) {
      return
    }
    const client = clientRef.current
    client.connector.pusher.connection.unbind('connected')
    client.connector.pusher.connection.unbind('disconnected')
    client.connector.pusher.connection.unbind('reconnecting')
    didBoundInitialEvents.current = false
  }

  const connect = async () => {
    if (!clientRef.current) {
      await initializeClient()
    }

    if (state.connected) {
      return
    }

    if (!clientRef.current) {
      return
    }

    const client = clientRef.current

    if (client.connector.pusher.connection.state === 'connected') {
      bindEvents()
      return
    }

    client.connect()
    bindEvents()
  }

  const disconnect = () => {
    if (!clientRef.current || !state.connected) return
    clientRef.current.disconnect()
    unbindEvents()
  }

  const addChannel = (channel: string) => {
    setState(prev => ({
      ...prev,
      channels: prev.channels.includes(channel) ? prev.channels : [...prev.channels, channel],
    }))
  }

  const removeChannel = (channel: string) => {
    setState(prev => ({
      ...prev,
      channels: prev.channels.filter(c => c !== channel),
    }))
  }

  useEffect(
    () => {
      void connect()
      return () => disconnect()
    },
    // eslint-disable-next-line react-hooks/exhaustive-deps
    []
  )

  const contextValue: SocketContextType = {
    state,
    setState,
    client: clientRef.current,
    connect,
    disconnect,
    addChannel,
    removeChannel,
  }

  return (
    <SocketContext.Provider value={contextValue} >
      {children}
    </SocketContext.Provider>
  )
}

export const useSockets = () => {
  const context = useContext(SocketContext)
  if (!context) {
    throw new Error('useSockets must be used within a SocketProvider')
  }
  return context
}

Wrap your main layout with the SocketProvider like this:

<SocketProvider>
  <Layout>
    <Outlet />
  </Layout>
</SocketProvider>

Now you can use the useSockets hook to get the socket client and join channels. Here's a demo of how to join a private channel and listen for events:

const { client } = useSockets()

const channelRef = useRef<any>(null)
const onArticleCreated = (e: any) => {
  void router.invalidate()
  toast.success('Your Article was created! ✅')
}

useEffect(() => {
  if (!client) return

  channelRef.current = client.private(`user.${userId}`)
  channelRef.current.listen('article.created', onArticleCreated)

  return () => {
    channelRef.current?.stopListening('article.created', onArticleCreated)
  }
}, [client, userId, onArticleCreated])

This approach is easily portable to other frameworks like Vue, Solid, etc. You can also create "online" and "offline" components next to user profile components to show connection status indicators. Just make sure to get the state from the context—it's reactive and should be available everywhere.

5. Conclusion 🎉

I hope you enjoyed this article and learned something new! While we could dive deeper and explore many more features, I wanted to keep this article focused on the WebSocket implementation. Please make sure to read the documentation for anything mentioned here, as there are still some edge cases to cover!

6. Resources 📚

[[Laravel Broadcasting Documentation|https://laravel.com/docs/12.x/broadcasting#main-content]]
[[Laravel Echo Documentation|https://laravel.com/docs/12.x/broadcasting#main-content]]
[[@tanstack|TanStack Start Documentation|https://tanstack.com/start/docs/getting-started/installation]]
[[Pusher Documentation|https://pusher.com/docs]]
[[Better Auth Documentation|https://better-auth.com/docs]]
[[Trigger.dev|https://trigger.dev]]
[[Better Auth|https://better-auth.com]]

Astro - Power your blog with Markdown View, Copy buttons to LLMS + Voice Resumes

Pedro Martins — Thu, 17 Jul 2025 00:00:00 GMT

import Callout from "@components/Callout.astro";

1. Introduction

I've been watching many documentation websites and blogs make it easier for LLMs/AI to read content or copy and paste to your favorite AI tools - a great signal for the future of documentation websites.

I first saw this on [[Mintlify|https://mintlify.com/]] and thought it was a great idea, but never bothered implementing it. Since I'm refactoring my blog to the latest Astro version and saw the following tweet, I took the chance to implement it here.

<blockquote class="twitter-tweet"><p lang="en" dir="ltr">having this in your docs is incredibly high signal <a href="https://t.co/Z5HtOGEhu3">pic.twitter.com/Z5HtOGEhu3</a></p>— Nathan Covey (@nathan_covey) <a href="https://twitter.com/nathan_covey/status/1945233405395775691?ref_src=twsrc%5Etfw">July 15, 2025</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

We'll also add automatic voice generation of the content, so your readers can listen to a short summary. Without further delay, let's get started.

2. Add Markdown View & Copy buttons to your blog

While it looks easy at first, this was quite a challenge because I didn't know Astro internals well enough to make it work. I'll explain the steps I took and how you can do it too.

My Astro blog uses MDX with custom components - how would I convert them to pure markdown?
Should I just crawl my own page and convert it to markdown from HTML? That would also bring headers and other elements not related to content.
How could I render the content in Astro without the runtime while preserving plugins I add for Remark, Shiki, etc., so it wouldn't be a pain to maintain?
What current tools do we have to convert HTML to Markdown?
Astro MDX renders to HTML, so I still need to convert it to markdown.

After digging around, I found a way to do it (probably not the best but it works! 🥲) and I'll explain it in the following sections.

2.1. MDX to Markdown

This is where I struggled the most. Crawling my own website felt heavy and I was looking for a "cleaner" way. I could also attempt to parse my raw MDX and "traverse" the tree to convert it to markdown, but I asked myself: This should be doable with Astro only, right? Well, yes, but it's still experimental!

First I found this article: The terrible things I did to Astro to render MDX content in my RSS feed, which was somewhat what I needed, but we still needed a lot of boilerplate to make it work. However, at the end of the article I found a link to an Astro RFC that was exactly what I needed! Lucky me, this was already pushed as an experimental feature.

Let's check the [[Astro Container Reference|https://docs.astro.build/en/reference/container-reference/]] and see how we can use it to render the content. Based on this, here's an example utility I created:

// lib/markdown/to-markdown.ts
import { getEntry, type CollectionEntry } from "astro:content";
import { experimental_AstroContainer as AstroContainer, type AstroContainerUserConfig } from "astro/container";
import { astroConfig } from "../../../astro.config.mjs";
import reactRenderer from "@astrojs/react/server.js";
import vueRenderer from "@astrojs/vue/server.js";
import mdxRenderer from "@astrojs/mdx/server.js";
import { render } from "astro:content";
import turndown from "turndown";
import turndownPluginGfm from "@joplin/turndown-plugin-gfm";
import CraftBox from "@components/CraftBox.astro";

export interface ToMarkdownProps {
  post: CollectionEntry<"blog">;
  request: Request;
}

export async function toMarkdown({ post, request }: ToMarkdownProps) {

  const container = await AstroContainer.create({
    astroConfig: astroConfig as AstroContainerUserConfig,
  });

  container.addServerRenderer({ renderer: vueRenderer, name: "@astrojs/vue" });
  container.addServerRenderer({ renderer: mdxRenderer, name: "@astrojs/mdx" });
  container.addServerRenderer({ renderer: reactRenderer, name: "@astrojs/react" });
  container.addClientRenderer({ name: "@astrojs/react", entrypoint: "@astrojs/react/client.js" })

  const entry = await getEntry("blog", post.id);

  if (!entry || entry.data.draft) {
    throw new Error("Post not found or it is a draft");
  }

  const { Content } = await render(entry);

  const html = await container.renderToString(Content, {
    request,
    props: {
      components: {
        CraftBox,
      }
    }
  });

  const turndownService = new turndown({ codeBlockStyle: "fenced" });

  // Parse Inline links
  turndownService.addRule("inlineLink", {
    filter: function (node: any, options: any) {
      return (
        options.linkStyle === "inlined" &&
        node.nodeName === "A" &&
        node.getAttribute("href")
      );
    },
    replacement: function (content: any, node: any) {
      var href = node.getAttribute("href").trim();
      var title = node.title ? ' "' + node.title + '"' : "";
      return "[" + content.trim() + "](" + href + title + ")\n";
    },
  });

  // Parse Fenced Code Blocks
  turndownService.addRule('fencedCodeBlock', {
    filter: function (node: any, options: any) {
      return (
        options.codeBlockStyle === 'fenced' &&
        node.nodeName === 'PRE' &&
        node.firstChild &&
        node.firstChild.nodeName === 'CODE'
      )
    },
    replacement: function (content: any, node: any, options: any) {
      var language = node.getAttribute("data-language") || ""
      return (
        "\n\n" + options.fence + language + "\n" +
        node.firstChild.textContent +
        "\n" + options.fence + "\n\n"
      )
    }
  })

  // Use Github flavored markdown
  turndownService.use(turndownPluginGfm.gfm);

  // Convert HTML to Markdown
  const markdown = turndownService.turndown(html);
 return markdown;
}

So what's happening here? Let's break it down in easy steps:

Astro was previously using the runtime to render content, and the APIs were too tight to the runtime, so we could not use it to render content outside of the Astro context.
Astro released the Astro Container, which is a way to render content outside of the Astro context, but it was still experimental.
We pull our Astro config, create the container with the config, and add the necessary renderers to make it work.
We get our blog entry and use the render function to get the content component.
Finally we render the content to HTML like Astro would do in a normal context, passing our custom components to the context and request if needed.
Once we have the HTML, we can use the turndown library to convert it to markdown.
We create small inline rules to convert the inline links and fenced code blocks to markdown and retain the snippet's original language.
Finally we use GitHub flavored markdown to convert the HTML to markdown and return it as a string.

Yay! We did MDX → HTML → Markdown, now things just got easier!

2.2. Serving the Markdown

If you're on Astro, this is probably a boring part. Simply add a new route next to your blog post route. Like so: src/pages/blog/[id].md.ts and add the following code:

import { getCollection, type CollectionEntry } from 'astro:content'
import type { APIRoute } from 'astro'
import { toMarkdown } from "@lib/markdown/to-markdown";

export async function getStaticPaths() {
	const posts = await getCollection('blog')
	return posts.map((post) => ({
		params: { id: post.id },
		props: post,
	}))
}

export const GET: APIRoute = async ({ props, request }) => {
	try {
		const markdown = await toMarkdown({ post: props as CollectionEntry<"blog">, request });
		return new Response(markdown, {
			headers: {
				'Content-Type': 'text/markdown; charset=utf-8',
			},
		});
	} catch (error) {
		console.error(error);
		return new Response('Error', { status: 500 });
	}
}

This should be more than enough to serve the markdown version of your blog post - simply add the .md extension to your blog post route and it should just work!

2.3. Add the buttons to your blog post

Now that we have the markdown version of our blog post, we can add the buttons to it. For this I used the [[shadcn/ui|https://ui.shadcn.com/]] dropdown menu component.

<Callout icon="☝️" type="info"> I've removed the icons to keep it simple, but you can add them back if you want. Also there's an issue with the dropdown menu with Astro Transitions - watch the issue for more details. </Callout>

import { useState, type SVGProps } from "react";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "./ui/dropdown-menu";

interface BlogActionsDropdownReactProps {
  url: string;
}

export default function BlogActionsDropdownReact({ url }: BlogActionsDropdownReactProps) {
  const [copyStatus, setCopyStatus] = useState<string>("Copy Markdown");

  const [dropdownOpen, setDropdownOpen] = useState(false);

  const fetchMarkdown = async () => {
    try {
      const response = await fetch(url);
      if (response.ok) {
        const content = await response.text();
        return content;
      }
    } catch (error) {
      console.error("Failed to fetch markdown content:", error);
    }
  };


  const handleAskGPT = () => {
    const content = encodeURIComponent('Please read the contents from the following link so i can ask question about it: ' + url);
    const chatGptUrl = `https://chatgpt.com/?q=${content}`;
    window.open(chatGptUrl, "_blank", "noopener,noreferrer");
  };

  const handleAskClaude = () => {
    const content = encodeURIComponent('Please read the contents from the following link so i can ask question about it: ' + url);
    const chatClaudeUrl = `https://claude.ai/new?q=${content}`;
    window.open(chatClaudeUrl, "_blank", "noopener,noreferrer");
  };

  const handleCopyMarkdown = async () => {
    const markdownContent = await fetchMarkdown();
    if (!markdownContent) {
      setCopyStatus("Failed");
      return;
    }
    try {
      await navigator.clipboard.writeText(markdownContent);
      setCopyStatus("Copied!");
      setTimeout(() => {
        setCopyStatus("Copy Markdown");
      }, 2000);
    } catch (error) {
      console.error("Failed to copy to clipboard:", error);
    }
  };

  const handleViewMarkdown = () => {
    window.open(url, "_blank", "noopener,noreferrer");
  };

  return (
    <DropdownMenu open={dropdownOpen} onOpenChange={setDropdownOpen}>
      <DropdownMenuTrigger
        onClick={() => setDropdownOpen((val) => !val)}
        className="not-prose group relative flex w-fit flex-nowrap rounded-sm border border-black/15 py-1.5 px-2 transition-colors duration-300 ease-in-out hover:bg-black/5 hover:text-black focus-visible:bg-black/5 focus-visible:text-black dark:border-white/20 dark:hover:bg-white/5 dark:hover:text-white dark:focus-visible:bg-white/5 dark:focus-visible:text-white text-sm items-center justify-center gap-1.5">
        <div className="flex items-center justify-center gap-1.5 divide-x divide-border">
          <div className="flex items-center justify-center gap-1.5 pr-1.5">
            <IconCopy className="size-3" />
            <span>Copy Page</span>
          </div>
          <div className="flex items-center justify-center gap-1.5">
            <IconChevronDown className="size-3 transition-transform duration-300 ease-in-out group-data-[state=open]:rotate-180" />
          </div>
        </div>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end" className="min-w-[8rem]">
        <DropdownMenuItem onClick={handleAskGPT}>
          <IconOpenai className="size-3" />
          <span>Ask GPT</span>
        </DropdownMenuItem>
        <DropdownMenuItem onClick={handleAskClaude}>
          <IconClaude className="size-3" />
          <span>Ask Claude</span>
        </DropdownMenuItem>
        <DropdownMenuItem onClick={handleCopyMarkdown}>
          <span>{copyStatus}</span>
        </DropdownMenuItem>
        <DropdownMenuItem onClick={handleViewMarkdown}>
          <span>View Markdown</span>
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

And that's it! With this in place, you can add the button to your blog post page, and it should just work!

We have:

Copy markdown to your clipboard
Serve the Markdown version of your blog post
Add a link to GPT & Claude to ask questions about the content

Here is how it looks like:

3. Voice Summary

Now that we have the markdown version of our blog post, it's time to add a voice summary. While this is probably overkill, I had some fun doing it, so I'll share it with you.

This involves 4 steps:

Summarize the raw content of the blog post using [[OpenAI|https://openai.com/]] & [[ai-sdk|https://ai-sdk.com/]]
Generate the voice summary using [[ElevenLabs|https://elevenlabs.io/]] or [[Murf|https://murf.ai/]]
Generate & save the voice summary to a file
Add the voice summary to your blog post

3.1 - Summarize the raw content of the blog post

This is probably the easiest part if you're familiar with [[Vercel|https://vercel.com/]] SDK, so I'll just jump right into the code. I've tweaked the prompt to output the summary in a more natural way - feel free to tweak it to your liking or suggest how I can make it better.

// lib/voice/summarizer.ts
import { generateObject } from 'ai';
import { createOpenAI } from '@ai-sdk/openai';
import { z } from 'zod';
import { env } from '../../env';

export interface SummaryOptions {
  tone?: 'professional' | 'casual' | 'engaging';
  focusAreas?: string[];
  includeKeyPoints?: boolean;
}

export interface Metadata {
  title: string;
  description?: string;
  tags?: string[];
}

export async function summarize(
  mdxContent: string,
  metadata: Metadata,
  options: SummaryOptions = {}
) {

  const {
    tone = 'engaging',
    focusAreas = [],
  } = options;

  const openaiProvider = createOpenAI({ apiKey: env.OPENAI_API_KEY });
  const model = openaiProvider('gpt-4o-mini');

  const systemPrompt = `You are Albert, an expert summarizer. 
Your task is to:
1. Create a concise, engaging summary that flows well when spoken aloud.
2. Maintain the key technical concepts and insights
3. Use natural speech patterns and transitions
4. Keep the ${tone} tone throughout
5. MAXIMUM 3000 characters AND 250 words.
${focusAreas.length > 0 ? `6. Focus particularly on: ${focusAreas.join(', ')}` : ''}

The summary should be suitable for text-to-speech conversion and provide value to listeners who want to quickly understand the main points of the article, but without compromising the quality of the content.

You may use the following format to add pauses: [pause 1s]

Here are some important rules to following:

- Make sure you dont miss any important comparisons or insights, like if we talk about Frameworks, make sure you mention them correctly.
- While code snippets are important, you can can skip the code and explain briefly what they do.
- Always talk in third person, like you are the narrotor for nikuscs blog post.
- Dont use fancy words, keep the language simple, natural and easy to understand by the readers.
- Users will not "listen" the article, they will read it and listen to the summary.
- Avoid adding weird or special characters to the summary like: In this insightful blog post titled \"Tresjs + Vue - Holographic Sticker,\"
- Attempt to replace characters like: Tresjs + Vue - Holographic Sticker with natural words like: Tresjs and Vue - Holographic Sticker. ( This is a good example but be smart about other types thay maybe follow)
- If twitter/x URLS or other links are in the content, attempt to mention them in the summary by their names.
- For Frameworks or weird namings or words you can ( but not always need to ) use the pronunciation dictionary as you see fit like: "React" -> "Ree Act", only if it makes sense.

Please summarize the following blog post:

**Title:** ${metadata.title}
${metadata.description ? `**Description:** ${metadata.description}` : ''}
${metadata.tags ? `**Tags:** ${metadata.tags.join(', ')}` : ''}

**Content:**
${mdxContent}
`;

  try {
    const { object } = await generateObject({
      model,
      prompt: systemPrompt,
      schema: z.object({
        summary: z.string().describe('A natural, conversational summary suitable for audio that flows well when spoken aloud. MAXIMUM 3000 characters AND 250 words.'),
      }),
    });

    const summary = object.summary;
    const originalLength = mdxContent.length;
    const compressionRatio = ((originalLength - summary.length) / originalLength) * 100;

    return {
      summary,
      originalLength,
      summaryLength: summary.length,
      compressionRatio: Math.round(compressionRatio * 100) / 100,
    };
  } catch (error) {
    console.error('❌ Error summarizing content:', error);
    throw new Error(`Failed to summarize content: ${error instanceof Error ? error.message : 'Unknown error'}`);
  }
}

3.2 - Generate the voice summary

Initially I was thinking about using ElevenLabs, but I found they're now subscription-based. While I used most of the free credits while testing, I didn't feel like subscribing to ONE more AI service just for generating casual voice summaries. So I implemented ElevenLabs, but also Murf which offers a pay-as-you-go model.

It's clear to me that ElevenLabs outputs are much better, but for this case, it serves the purpose.

<Callout icon="☝️" type="info"> Check the Murf implementation for more details, as it contains a pronunciation dictionary for the most common words in tech - this was also a fun challenge to implement. </Callout>

// lib/voice/client.elevenlabs.ts
export interface ElevenLabsVoiceOptions {
  voiceId?: string;
  modelId?: string;
  stability?: number;
  similarityBoost?: number;
  style?: number;
  useSpeakerBoost?: boolean;
}

export interface VoiceSettings {
  stability: number;
  similarity_boost: number;
  style?: number;
  use_speaker_boost?: boolean;
}

export class ElevenLabsClient {
  private readonly apiKey: string;
  private readonly baseUrl = 'https://api.elevenlabs.io/v1';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async generate(
    text: string,
    options: ElevenLabsVoiceOptions = {}
  ): Promise<ArrayBuffer> {
    const {
      voiceId = 'JBFqnCBsd6RMkjVDRZzb',
      modelId = 'eleven_turbo_v2_5',
      stability = 0.5,
      similarityBoost = 0.5,
      style = 0,
      useSpeakerBoost = true,
    } = options;

    const url = `${this.baseUrl}/text-to-speech/${voiceId}`;

    const requestBody = {
      text,
      model_id: modelId,
      voice_settings: {
        stability,
        similarity_boost: similarityBoost,
        style,
        use_speaker_boost: useSpeakerBoost,
      },
    };

    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Accept': 'audio/mpeg',
          'Content-Type': 'application/json',
          'xi-api-key': this.apiKey,
        },
        body: JSON.stringify(requestBody),
      });

      if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`ElevenLabs API error: ${response.status} ${response.statusText} - ${errorText}`);
      }

      const arrayBuffer = await response.arrayBuffer();
      return arrayBuffer;
    } catch (error) {
      console.error('❌ Error generating speech with ElevenLabs:', error);
      throw new Error(`ElevenLabs TTS failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }
}

// lib/voice/client.murf.ts
export interface MurfVoiceOptions {
  voiceId?: string;
  speed?: number;
  pitch?: number;
  volume?: number;
  emphasis?: 'strong' | 'moderate' | 'reduced';
  pauseLength?: number;
  style?: string;
}

export interface MurfSpeechRequest {
  text: string;
  voiceId: string;
  audioFormat?: 'mp3' | 'wav' | 'flac';
  sampleRate?: number;
  bitRate?: number;
  speed?: number;
  pitch?: number;
  volume?: number;
  emphasis?: 'strong' | 'moderate' | 'reduced';
  pauseLength?: number;
  style?: string;
  pronunciationDictionary?: Record<string, { type: string; pronunciation: string }>;
}

export interface MurfSpeechResponse {
  audioFile: string;
  contentType?: string;
  duration?: number;
  size?: number;
}

export class MurfClient {
  private readonly apiKey: string;
  private readonly baseUrl = 'https://api.murf.ai/v1';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async generate(
    text: string,
    options: MurfVoiceOptions = {}
  ): Promise<ArrayBuffer> {

    const {
      voiceId = 'en-US-charles',
      speed = 0.8,
      pitch = 1.0,
      volume = 1.0,
      emphasis = 'moderate',
      pauseLength = 0.5,
      style = 'calm'
    } = options;

    const requestBody: MurfSpeechRequest = {
      text,
      voiceId,
      speed,
      pitch,
      volume,
      emphasis,
      pauseLength,
      style,
      pronunciationDictionary: {
        'js': { type: "SAY_AS", pronunciation: "jay ess" },
        'ts': { type: "SAY_AS", pronunciation: "tee ess" },
        'html': { type: "SAY_AS", pronunciation: "H T M L" },
        'css': { type: "SAY_AS", pronunciation: "C S S" },
        'json': { type: "SAY_AS", pronunciation: "jay son" },
        'yaml': { type: "SAY_AS", pronunciation: "yammel" },
        'vue': { type: "SAY_AS", pronunciation: "view" },
        'nuxt': { type: "SAY_AS", pronunciation: "nuhkst" },
        'react': { type: "SAY_AS", pronunciation: "ree act" },
        'angular': { type: "SAY_AS", pronunciation: "ang you lar" },
        'svelte': { type: "SAY_AS", pronunciation: "svelt" },
        'vite': { type: "SAY_AS", pronunciation: "vite" },
        'tailwind': { type: "SAY_AS", pronunciation: "tail wind" },
        'shadcn': { type: "SAY_AS", pronunciation: "shad sea en" },
        'threejs': { type: "SAY_AS", pronunciation: "three jay ess" },
        'nestjs': { type: "SAY_AS", pronunciation: "nest jay ess" },
        'nextjs': { type: "SAY_AS", pronunciation: "next jay ess" },
        'next.js': { type: "SAY_AS", pronunciation: "next jay ess" },
        'vue.js': { type: "SAY_AS", pronunciation: "view jay ess" },
        'laravel': { type: "SAY_AS", pronunciation: "la ruh vell" },
        'express': { type: "SAY_AS", pronunciation: "ex press" },
        'tsx': { type: "SAY_AS", pronunciation: "T S X" },
        'jsx': { type: "SAY_AS", pronunciation: "J S X" },
        'dom': { type: "SAY_AS", pronunciation: "dee oh em" },
        'cpu': { type: "SAY_AS", pronunciation: "C P U" },
        'gpu': { type: "SAY_AS", pronunciation: "G P U" },
        'sdk': { type: "SAY_AS", pronunciation: "S D K" },
        'api': { type: "SAY_AS", pronunciation: "A P I" },
        'cli': { type: "SAY_AS", pronunciation: "see ell eye" },
        'gh': { type: "SAY_AS", pronunciation: "gee aitch" },
        'ci': { type: "SAY_AS", pronunciation: "C I" },
        'cd': { type: "SAY_AS", pronunciation: "C D" },
        'http': { type: "SAY_AS", pronunciation: "H T T P" },
        'https': { type: "SAY_AS", pronunciation: "H T T P S" },
        'ai': { type: "SAY_AS", pronunciation: "A I" },
        'ml': { type: "SAY_AS", pronunciation: "M L" },
        'ui': { type: "SAY_AS", pronunciation: "you eye" },
        'ux': { type: "SAY_AS", pronunciation: "you ex" },
        'sql': { type: "SAY_AS", pronunciation: "sequel" },
        'npm': { type: "SAY_AS", pronunciation: "N P M" },
        'pnpm': { type: "SAY_AS", pronunciation: "P N P M" },
        'yarn': { type: "SAY_AS", pronunciation: "yarn" },
        'tresjs': { type: "SAY_AS", pronunciation: "tres jay ess" },
      },
    };


    try {
      const response = await fetch(`${this.baseUrl}/speech/generate`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'api-key': this.apiKey,
          'Accept': 'application/json',
        },
        body: JSON.stringify(requestBody),
      });

      if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`Murf API error: ${response.status} - ${errorText}`);
      }

      const data: MurfSpeechResponse = await response.json();
      const audioResponse = await fetch(data.audioFile);

      if (!audioResponse.ok) {
        throw new Error(`Failed to download audio: ${audioResponse.status}`);
      }
      const audioBuffer = await audioResponse.arrayBuffer();
      return audioBuffer;
    } catch (error) {
      console.error('❌ Error generating speech with Murf:', error);
      throw new Error(`Murf TTS failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }
}

So, we have both clients. Now let's create the TTS entry point that would pick one or another.

// lib/voice/tts.ts
import { ElevenLabsClient } from './client.elevenlabs';
import { MurfClient } from './client.murf';
import { env } from '../../env';

export type TTSProvider = 'elevenlabs' | 'murf';

export interface TTSOptions {
  provider?: TTSProvider;
  voiceId?: string;
  speed?: number;
  pitch?: number;
  volume?: number;
}

export interface TTSResult {
  audioBuffer: ArrayBuffer;
  provider: TTSProvider;
  size: number;
}

export async function generate(
  text: string,
  options: TTSOptions = {}
): Promise<TTSResult> {
  const { provider = 'murf' } = options;

  console.log(`🎤 Generating TTS with ${provider}...`);

  let audioBuffer: ArrayBuffer;

  try {
    switch (provider) {
      case 'murf':
        const murfClient = new MurfClient(env.MURF_API_KEY);
        audioBuffer = await murfClient.generate(text, {
          voiceId: options.voiceId ?? 'en-US-charles',
          speed: options.speed ?? 1.0,
          pitch: options.pitch ?? 1.0,
          volume: options.volume ?? 1.0,
        });
        break;

      case 'elevenlabs':
        const elevenLabsClient = new ElevenLabsClient(env.ELEVENLABS_API_KEY);
        audioBuffer = await elevenLabsClient.generate(text, options);
        break;

      default:
        throw new Error(`Unsupported TTS provider: ${provider}`);
    }

    return {
      audioBuffer,
      provider,
      size: audioBuffer.byteLength,
    };
  } catch (error) {
    console.error(`❌ TTS generation failed with ${provider}:`, error);
    throw new Error(`TTS generation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
  }
}

3.3 - Generate & Save the voice summary to a file

So we have both clients implemented. Now let's generate the voice summary for each of our blog posts. For simplicity, I created a command to generate them, skipping the ones that already exist. This is done before I run the deploy for each article I write.

This file will take care of the following:

Parse the MDX files in the blog directory
Call the summarizer
Pass the summary to the TTS client
Save the voice summary to a file in the public directory

You can add it to your package.json scripts if needed like: voice:generate with bun run src/lib/voice/command.ts

// lib/voice/command.ts
#!/usr/bin/env bun
import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'fs';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';
import { generate } from './tts';
import { summarize } from './summarizer';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const BLOG_DIR = join(__dirname, '../../../src/content/blog');
const AUDIO_DIR = join(__dirname, '../../../public/audio/blog');

interface BlogPost {
  id: string;
  data: {
    title: string;
    description: string;
    date: string;
    draft?: boolean;
    tags?: string[];
    cover?: string;
  };
}

function parseMDX(content: string): BlogPost['data'] {
  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
  if (!frontmatterMatch) {
    throw new Error('No frontmatter found');
  }

  const frontmatter = frontmatterMatch[1];
  const data: any = {};

  // Parse key-value pairs
  const lines = frontmatter.split('\n');
  for (const line of lines) {
    const trimmedLine = line.trim();
    if (!trimmedLine || trimmedLine.startsWith('#')) continue;

    if (trimmedLine.endsWith(':')) {
      continue;
    }

    if (trimmedLine.startsWith('- ')) {
      const value = trimmedLine.slice(2).trim();
      if (!data.tags) data.tags = [];
      data.tags.push(value);
      continue;
    }

    const match = trimmedLine.match(/^(\w+):\s*(.*)$/);
    if (match) {
      const [, key, value] = match;
      if (key === 'draft') {
        data[key] = value === 'true';
      } else {
        data[key] = value.replace(/^["']|["']$/g, '');
      }
    }
  }

  return data;
}

function getContent(): BlogPost[] {
  const posts: BlogPost[] = [];
  const blogDirs = readdirSync(BLOG_DIR, { withFileTypes: true })
    .filter(dirent => dirent.isDirectory())
    .map(dirent => dirent.name);

  for (const dirName of blogDirs) {
    const postPath = join(BLOG_DIR, dirName, 'index.mdx');
    if (existsSync(postPath)) {
      try {
        const content = readFileSync(postPath, 'utf-8');
        const data = parseMDX(content);
        posts.push({
          id: dirName,
          data
        });
      } catch (error) {
        console.warn(`⚠️  Failed to parse ${dirName}:`, error);
      }
    }
  }

  return posts;
}

async function generateAudioForPost(post: BlogPost): Promise<void> {
  const audioFilePath = join(AUDIO_DIR, `${post.id}.mp3`);

  if (existsSync(audioFilePath) && !process.argv.includes('--force')) {
    console.log(`⏭️  Skipping ${post.id} - audio file already exists`);
    return;
  }

  try {
    console.log(`🎙️ Processing: ${post.data.title}`);

    const mdx = readFileSync(join(BLOG_DIR, post.id, 'index.mdx'), 'utf-8');
    const summary = await summarize(
      mdx,
      {
        title: post.data.title,
        description: post.data.description,
        tags: post.data.tags,
      },
      { tone: 'engaging' }
    );

    console.log(`🤖 AI Summary Result:`, {
      originalLength: mdx.length,
      summaryLength: summary.summaryLength,
      compressionRatio: Math.round(((mdx.length - summary.summaryLength) / mdx.length) * 100),
      summary: summary.summary,
    });

    const audio = await generate(summary.summary, { provider: 'murf' });

    writeFileSync(audioFilePath, new Uint8Array(audio.audioBuffer));

    console.log(`✅ Generated: ${audioFilePath} (${(audio.size / 1024 / 1024).toFixed(2)} MB)`);

  } catch (error: any) {
    console.error(`❌ Error processing ${post.id}:`, error.message);
    if (process.argv.includes('--continue-on-error')) {
      console.log('⏩ Continuing with next post...');
      return;
    }
    throw error;
  }
}

async function main() {
  console.log('🎙️ Starting AI-powered voice generation for blog posts...');
  if (!existsSync(AUDIO_DIR)) {
    mkdirSync(AUDIO_DIR, { recursive: true });
    console.log('📁 Created audio directory:', AUDIO_DIR);
  }

  try {
    const posts = getContent();
    console.log(`📚 Found ${posts.length} blog posts`);
    for (const post of posts) {
      await generateAudioForPost(post);
    }
    console.log('✅ Voice generation completed successfully!');
  } catch (error) {
    console.error('❌ Error during voice generation:', error);
    process.exit(1);
  }
}

main().catch(console.error);

3.4 - Add the voice summary to your blog post

Now that we have the voice file generated, we can add it to our blog post. A simple component to do this would be:

---
interface Props {
  postId: string;
  title?: string;
}

const { postId } = Astro.props;
const audioUrl = `/audio/blog/${postId}.mp3`;
---

<div class="ring-input/80 my-6 rounded-lg p-3 ring">
  <div class="flex flex-col items-start justify-start gap-1">
    <div class="text-muted-foreground text-xs font-thin">Want a quick summary of this post? Tune in 🎧</div>
    <audio controls preload="metadata" class="h-8 w-full self-start" src={audioUrl}>Your browser does not support the audio element.</audio>
  </div>
</div>

That's it! Now you also have a voice summary of your blog post, and you can add it to your blog post page.

Here is how it looks like:

4. Conclusion

This was a fun challenge to work on, and I hope you enjoyed it. If you have any questions, feel free to ask me on [[Twitter|https://x.com/nikuscs]]. Astro is indeed a great framework for blogging, and I'm glad to see it's getting more traction!

5. Resources

[[Astro Container Reference|https://docs.astro.build/en/reference/container-reference/]]
[[Astro RFC|https://github.com/withastro/roadmap/issues/533]]
[[Turndown|https://github.com/domchristie/turndown]]
[[Turndown Plugin GFM|https://github.com/laurent22/joplin/tree/dev/packages/turndown-plugin-gfm]]
[[ElevenLabs|https://elevenlabs.io/]]
[[Murf|https://murf.ai/]]
[[Vercel SDK|https://vercel.com/docs/sdk/overview]]
[[ai-sdk|https://ai-sdk.com/]]
[[shadcn/ui|https://ui.shadcn.com/]]
[[codetv.dev|https://codetv.dev/blog/mdx-to-rss-astro]]

Tanstack Start - A deep dive into THE React Framework

Pedro Martins — Mon, 14 Jul 2025 00:00:00 GMT

1. Introduction

React Vite starter is a great way to learn React, but it's no longer recommended for production use. When building real-world applications, you'll want a more robust framework that provides routing, state management, image optimization, SSR, and other features out of the box.

The React ecosystem currently has three main frameworks:

[[Next.js|https://nextjs.org]]
[[React Router 7|https://reactrouter.com/]]
[[TanStack Start|https://tanstack.com/start]]

Let's explore TanStack Start and why it might be perfect for your next project. Disclaimer: I'm not affiliated with TanStack - just a fan of their work!

2. What is TanStack Start? 🔧

From their documentation: "Full-stack React and Solid framework powered by TanStack Router SSR, Streaming, Server Functions, API Routes, bundling and more powered by TanStack Router and Vite."

That's right! If you're in the React ecosystem, you probably know about TanStack Query, TanStack Table, TanStack Router, and recently TanStack Form. Most of these are built by the same team and by [[@tannerlinsley]] himself.

TanStack Start aims to bring the "server" side of the equation with SSR, Streaming, Server Functions, API Routes, and many more features. You can finally build a full-stack application with a single framework. About 90% of TanStack Start is powered by TanStack Router, leaving just the server bits to the "start" implementation.

3. Why TanStack Start vs Next.js / React Router 7? ⚡

Tech choices are hard, and you need to choose the right tool for the job. Here are my reasons for picking TanStack Start over Next.js or React Router 7:

React Router 7's / Remix direction: While React Router 7 powers a big part of the ecosystem alongside Next.js, and promisses to keep it up to date are there, Remix ( previously known as React Router ) seems to be stepping back from "React" - read this post for more info. This makes me unconfortable with so many decisions / rebrands taking place in the past few years.
Documentation clarity: React Router 7 lacks proper documentation and examples. It feels complex to understand and implement.
RSC complexity: Next.js placed their bets on RSC and a new React paradigm. While RSC is great, it adds extra complexity to how we build React applications.
Performance trade-offs: Next.js server-side rendering feels slower compared to traditional SPAs and needs more powerful machines to run (we're pushing workload to the server instead of the client).
Vite ecosystem: This is personal preference, but the [[Vite|https://vite.dev]] ecosystem is huge, fast, and has better DX compared to Webpack/Turbopack.
Type safety: TanStack Router is simply the best type-safe router for React - query params, context, everything is fully typed.

4. Core Architecture & Philosophy

TanStack Start represents a paradigm shift in how we think about full-stack React applications. While frameworks like Next.js have embraced a "server-first" approach with React Server Components, TanStack Start takes a fundamentally different path: client-first architecture with powerful server capabilities.

4.1 Client-First vs Server-First Philosophy

The key differentiator lies in TanStack Start's philosophy:

"While other frameworks continue to compromise on the client-side application experience we've cultivated as a front-end community over the years, TanStack Start stays true to the client-side first developer experience, while providing a full-featured server-side capable system that won't make you compromise on user experience."

This means:

Initial navigation: Server-side rendering for fast initial page loads and SEO
Subsequent navigation: Client-side routing for instant, SPA-like experiences
Data loading: Isomorphic loaders that run on server during SSR, client during navigation
Interactivity: Rich client-side interactions without server-side compromises

4.2 Isomorphic Loaders: The Game Changer 🎯

TanStack Start's most innovative feature is its isomorphic loaders. Unlike traditional meta-frameworks where server loaders and client state exist in separate worlds, TanStack Start bridges this gap elegantly:

export const Route = createFileRoute('/posts')({
  component: Page,
  validateSearch: zodValidator(PostSearchParamsSchema),
  loaderDeps: ({ search }) => ({ search }),
  search: {
    middlewares: [stripSearchParams(PostSearchParamsDefaultValues)],
  },
  loader: async ({ deps, context }) => context.queryClient.ensureQueryData(postsQueryOptions(deps.search)),
  head: () => ({
    meta: createMetaPage({
      title: 'Posts',
      description: 'Your personal post collection',
    }),
  }),
})

/**
 * Page
 */
function Page() {
  const results = Route.useLoaderData()
  return (
    <div className="flex flex-col gap-4">
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
        {results.records.map((post) => <PostCard post={post} key={post.id} />)}
      </div>
    </div>
  )
}

This solves the "impedance mismatch" problem where:

Server loaders blindly re-fetch all data on navigation ( can pair with TanStack Query )
Client state gets ignored by server-side logic
You end up requesting data you already have cached

4.3 Server Functions: Not Your Typical RPCs

TanStack Start introduces createServerFn - a unique approach to server-side logic:

export const likePost = createServerFn({ method: 'POST' })
  .middleware([authedMiddleware])
  .validator(LikePostSchema)
  .handler(async ({ data }) => {
    if (!data.postId) {
      throw new Error('Post is not valid or doesnt exist anymore')
    }

    const headers = getHeaders()
    await auth.api.likePost({
      headers: headers as HeadersInit,
      body: {
        postId: data.postId,
      },
    })

    return { message: 'Post liked successfully' }
  })

Key benefits:

Call from anywhere: Components, hooks, loaders - full flexibility
Type-safe end-to-end: Input validation with inference
No API layer needed: Direct function calls that proxy to server
Automatic serialization: Complex data types handled seamlessly

4.4 TanStack Query Integration

Unlike other frameworks, TanStack Start seamlessly integrates with TanStack Query for sophisticated caching:

const postsQuery = useQuery({
  queryKey: ['posts'],
  queryFn: () => getPostsServerFn()
})

This enables:

Smart caching: Only fetch what's not already cached
Background updates: Stale-while-revalidate patterns
Optimistic updates: Immediate UI feedback
Shared state: Between server and client seamlessly

For more info, check out the [[TanStack Query documentation|https://tanstack.com/query/latest/docs/framework/react/overview]].

4.5 Type Safety Throughout

TanStack Start builds on TanStack Router's foundation of 100% inferred TypeScript:

Routes: Fully typed path parameters and search params
Navigation: Type-safe links with autocomplete
Server functions: Input/output type inference
Data flow: From server to client with full type preservation

4.6 The Architecture in Practice

Here's how it all comes together:

Initial Load:
- Server renders page with data from loaders
- Client receives HTML + serialized data
- Hydration with full state restoration
Client Navigation:
- Router intercepts navigation
- Loaders run on client with cache awareness
- Only missing data gets fetched
- Instant page updates
Server Interactions:
- Server functions called like regular functions
- Automatic proxy to server via fetch
- Type safety maintained throughout

This architecture enables the best of both worlds: fast initial loads like traditional SSR with rich client-side experiences like SPAs, without the typical compromises or complexity.

5. Routing: File-Based vs Virtual Routes 🛣️

Just like Next.js, you can define file-based routes - check the full documentation here.

But the real power comes with virtual routes - this is where the DX starts to shine! Even better, you can mix and match file-based routes with virtual routes.

Here's an example of a virtual route:

import { rootRoute, route, index } from '@tanstack/virtual-file-routes'

export const routes = rootRoute('root.tsx', [
  index('landing/index.tsx'),
  // Private pages
  route('/dashboard', 'dashboard/layout.tsx', [
    //  Bookmarks
    route('/posts', 'dashboard/posts/layout.tsx', [
      index('dashboard/posts/index.tsx'),
      route('/create', 'dashboard/posts/create.tsx'),
      route('/$id', 'dashboard/posts/view.tsx'),
    ]),
    // User Area
    route('/user', [
      // Teams
      route('/teams', [
        route('$slug', [route('/switch', 'dashboard/user/switch-team.tsx')]),
      ]),
      route('/logout', 'dashboard/user/logout.tsx'),
    ]),
  ]),
  // Public pages
  route('/auth', 'auth/layout.tsx', [
    route('/sign-in', 'auth/sign-in.tsx'),
  ]),
  // Api
  route('/api', [
    // BetterAuth
    route('/auth', [route('$', 'api/auth.ts')]),
  ]),
])

6. Middleware 🔧

You probably know what middlewares are. While they come "for free" in other frameworks like [[Laravel|https://laravel.com]] and [[Nuxt|https://nuxt.com]], they're not always easy to implement in React.

Thankfully, TanStack Start has a very nice way to define middleware for server functions and routes. Let's explore them.

6.1 Server Functions & Request Middleware 🔒

This ensures that the server function is only called if the middleware passes or doesn't throw an exception. Here's a demo example for better auth:

async function authMiddlewareHandler(request: Request | null | undefined): Promise<AuthMaybeSessionContext> {

  const context: AuthMaybeSessionContext = {
    isAuthenticated: false,
    session: null,
    user: null,
    organization: null,
    organizations: [],
  }

  if (!request) {
    return context
  }

  const authSession = await auth.api.getSession({
    headers: request.headers,
  })

  // Add authenticated data if session exists
  if (authSession?.session && authSession.user) {
    Object.assign(context, {
      isAuthenticated: true,
      session: authSession.session as unknown as Session,
      user: authSession.user as unknown as User,
      organization: organization as Organization,
      organizations: organizations as Organization[],
    })
  }

  return context
}

/**
 * This middleware is used to authenticate the user.
 * It sets the session in the context.
 */
export const authMiddleware = createMiddleware({ type: 'function' })
  .server(async ({ next }) => {
    const request = getWebRequest()
    const context = await authMiddlewareHandler(request)
    return next({
      context,
    })
  })

/**
 * This middleware is used to authenticate the user.
 * It sets the session in the context.
 */
export const authWebMiddleware = createMiddleware({ type: 'request' })
  .server(async ({ next }) => {
    const request = getWebRequest()
    const context = await authMiddlewareHandler(request)
    return next({
      context,
    })
  })

6.2 Router "Middleware" 🚦

While TanStack Router doesn't have the concept of middleware, users often use the beforeLoad hook to achieve the same effect.

Here are examples of how to pass context from "root.tsx" into a gated route:

// root.tsx
export const Route = createRootRouteWithContext<RouterContext>()({
  beforeLoad: async ({ context }) => {
    try {
      const authContext = await context.queryClient.ensureQueryData(authQueryOptions())
      return {
        ...authContext,
      }
    } catch (error) {
      logger.error('Unable to load the auth context', error)
      return {}
    }
  },
})

// dashboard/layout.tsx
export const Route = createFileRoute('/dashboard/_layout')({
  component: Layout,
  beforeLoad: async ({ context }) => {
    const { isAuthenticated } = context
    if (!isAuthenticated || !context.session || !context.user || !context.organization || !context.organizations) {
      throw redirect({
        to: '/auth/sign-in'
      })
    }
    return AuthSessionContextSchema.parse(context)
  }
})

// Server route middleware
export const ServerRoute = createServerFileRoute().methods((api) => ({
  GET: api
    .middleware([authMiddleware])
    .handler(async ({ request }) => {
      return new Response('Hello, World! from ' + request.url)
    }),
}))

Wait, what's happening here? Let's break it down:

We use beforeLoad on the root.tsx route to load the auth context (whether the user is logged in or not)
The QueryClient fetches the auth context from server side and persists it in the query cache
The context is then passed to child routes, in this case the dashboard/layout.tsx route
The dashboard/layout.tsx route uses the beforeLoad hook to check if the user is authenticated - if not, we redirect to the login page
The AuthSessionContextSchema is a Zod schema that validates the context and ensures it's valid & fully typed
You can repeat this process for any route you want (even nested ones)

7. Server & Client Boundaries 🔐

This is a crucial concept to understand and a major security concern for full-stack applications in the JavaScript ecosystem. Blurring the lines between server & client provides good DX, but it also opens up security concerns if you don't know what you're doing.

A missed server import into the client can lead to your server application logic or even environment variables being exposed to the client!

Next.js handles this elegantly with the use 'client' directive at the top of files - anything not tagged with client is treated as server code, ensuring no server code executes on the client.

React Router 7 & SvelteKit use file naming conventions to determine if a file is server or client: post.server.tsx or post.client.tsx

While TanStack Start doesn't YET have a built-in way to handle this, you can use the Vite Plugin [[vite-env-only|https://github.com/pcattori/vite-env-only]] to ensure that files and directories matching your patterns don't get imported into the client bundle. Here's an example:

import { defineConfig } from 'vite'
import { denyImports } from 'vite-env-only'

export default defineConfig({
  plugins: [
    // .. other plugins,
    denyImports({
        client: {
          specifiers: [
            "fs", /^node:/, "drizzle-orm", "postgres",
            "node-ray", "Buffer", "process", "path", "os",
            "url", "crypto", "stream", "net",
          ],
          files: [
            "**/.server/*",
            "**/*.server.*",
            "src/console/*",
            "src/services/*",
            "src/console/*",
            "src/jobs/*"
          ],
        },
      }),
  ]
})

8. Deployment 🚀

TanStack being based on [[Vite|https://vite.dev]], [[h3|https://h3.dev]] & [[Nitro|https://nitro.unjs.io]] (at least for now), makes it a perfect fit for deployment on almost any platform!

All you have to do is toggle your target in your vite.config.ts file, and you're good to go!

// vite.config.ts
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { defineConfig } from 'vite'

// Targets can be : cloudflare-module, vercel, netlify, bun, node, etc.
export default defineConfig({
  plugins: [tanstackStart({ target: 'vercel' })],
  // ... other vite config
})

Don't forget to check the documentation - sometimes you need to tweak the config to make it work on your platform of choice.

9. Conclusion ✨

TanStack Start is a powerful meta-framework that's changing the game in the React ecosystem. If you haven't tried it yet, you should - grab some coffee and start building!

You can join their TanStack Discord to get help, ask questions, and get updates on the framework.

Next vs Nuxt, which one is better in 2025?

Pedro Martins — Thu, 16 Jan 2025 00:00:00 GMT

With more than 15 years of experience in web development, I've seen many frameworks come and go, but [[Nuxt|https://nuxt.com]] and [[Next.js|https://nextjs.org]] are here to stay. In this article, I'll compare the two frameworks and share my thoughts on which one is better in 2025.

React vs Vue

The first choice (which I won't cover in this post) is picking between React or Vue. Both are great frameworks, but I'll assume you've already chosen one for your project.

At the time of this post, both have great communities and are very popular, so you can't go wrong with either - React being more popular and Vue being more beginner-friendly.

In this article, I won't cover basic features since both frameworks support many things. I'll focus on the high-level features instead.

1. Next.js 🚀

I recently tried Next.js for a personal project, and while I'm biased towards Vue, I have to say that Next.js is a great framework with many features and a great community.

But not everything is perfect. I tried hard to ignore all the DX that Vue gives me to embrace the Next.js + React hype train. I researched medium to large Next.js projects on [[GitHub|https://github.com]] to learn more about the framework.

I read the documentation, learned the best practices, and watched tutorials & videos to get familiar with the framework, but that wasn't enough. Coming from [[Laravel|https://laravel.com]], we're REALLY spoiled with the DX that Vue or Laravel gives us.

Let's go through the pros and cons of Next.js:

1.1 Pros ✅

Great, large & active community
Solid documentation
Out-of-the-box TypeScript support
SSR, SSG, ISR capabilities
Great concept for Server & Client Components - really loved this feature
Huge React ecosystem that Next.js inherits
Pages routing is simple and easy to understand
Minimalistic/bare bones - you can add only what you need

1.2 Cons ❌

Vendor lock-in - no matter what you say, Vercel is the way to go for Next.js
Webpack 😞 - really slow on dev & build, most of the time compared to a Nuxt project
Middleware - no concept of multiple middlewares, you have to use a single middleware for all routes or implement your own middleware stack
i18n - while there are a few "demos", none are actual real-world examples, and the documentation is lacking. External packages exist but they're HEAVILY complicated to implement in my opinion
Server & Client components - while a great concept, it's really hard to understand and implement, you end up prop drilling a lot of data
Server & Client lines blurred - you have to be really careful with what you're doing, and you need to know what's running on the server vs client. A little mistake could be a big problem
Node.js support for Middleware - this is a BIG one. While Next.js advocates that Middleware should not run Node.js but their "Edge" server, there are many cases where you need to run Node.js code in Middleware, and this isn't supported by Next.js at the time of this post. This is REALLY necessary for basic stuff like auth checks against databases
Dev Experience - while the DX isn't bad, it's not as good as Nuxt. There's no proper way to debug your code. React DevTools with Next.js is a HUGE pile of nested contexts
Unstable - it seems like there are many breaking changes on every release, and the community isn't happy about it. There are many issues on GitHub about this
Lack of documentation on how to deploy other than Vercel
Somewhat slow - while SSR is good, it seems slower than traditional SPAs at first load

2. Nuxt 💚

After my mission with Next.js, I decided to replicate the same project, but this time using Nuxt. I had most of my components already done with Shadcn, and I could easily transfer a lot of code-base from Next.js.

Nuxt instantly provides a better DX than Next.js. Can't deny - after a few weeks of React, I was really happy to be back on Vue!

With my struggles from Next.js in mind, here's a breakdown for Nuxt:

2.1 Pros ✅

Great, large & active community - Vue is growing a lot, and Nuxt is growing with it
Lots of composables out-of-the-box, like useFetch, useMeta, useHead, useState, etc.
Great documentation - really easy to understand and follow
Amazing plugin & modules system - you can add many features with a single line of code
Out-of-the-box support for stacked middlewares - attach them & use them
Nuxt i18n just works - with a few clicks you can have a multi-language website, no stress!
Top-notch DX - install modules directly from the Nuxt DevTools, check OpenGraph images, dependencies, preview builds... just amazing!
Great hooks for deduping & caching around [[ofetch|https://github.com/unjs/ofetch]]
Amazing universal support from [[UnJS|https://unjs.io]] ecosystem
No vendor lock-in - you can deploy to Vercel, Cloudflare, etc.
Middleware supports Node.js & edge runtimes
Vue reactivity system & bindings are just great!
Support for "Islands" - Server & Client components are really easy to understand and implement
Configuration in one place - no need to search for many files, everything is in nuxt.config.ts
Easier to implement auth modules
Auto-imports for components, composables, etc. - just write your business logic, no need to import stuff
Vite bundler - it's really fast, and the DX is just amazing + the ecosystem

2.2 Cons ❌

Confusing sometimes - because there are many hooks, composables, etc., sometimes you don't know what to use or what's the correct one for a specific case
Documentation is still lacking some "best practices" for some features
Unstable sometimes - while auto-imports are a good DX, they also create buggy code, and it's really hard to find the source of the bug sometimes
Server Components are not yet polished - you can't mix and match client & server components like Next.js (yet)
Lack of methods to inject configurations from user-land & modules (still better than Next.js, which has none)
Unclear what composables & features you can use on server & client, leading again to unexpected bugs & hard to debug issues

The Winner 🏆

While both frameworks are great, the winner for me is clearly Nuxt. The DX is just amazing, and the features are great compared to Next.js.

I could probably do the same project 10x faster with Nuxt than with Next.js. One of the biggest concerns for me is also the vendor lock-in for Vercel. While many people try to deny and argue against that, for me it's crystal clear that Next.js doesn't have/doesn't want to make these changes, resulting in a lot of drama on Twitter & Reddit.

On the other hand, React has a huge ecosystem, and if you're already using React, Next.js is a great choice. You may also consider [[Remix|https://remix.run]] or [[TanStack Start|https://tanstack.com/start]] as alternatives.

Conclusion 🎯

In the past years, many meta-frameworks appeared and some of them are here to stay. For me, there's no perfect one yet. Nuxt has good potential to be the best one, but there's still a lot of work to be done, not only in Nuxt but also in the [[Vue|https://vuejs.org]] ecosystem.

I'm still a big fan of starting my own projects with vanilla Vue or [[React|https://react.dev]], and calling it a day - bring your own plugins, your own features, and your own DX. But if you're in a hurry or want a quick MVP, both are great choices.

One big concern I also have with full-stack JavaScript frameworks is that while they provide a really flexible way to build applications with a single language & code-base, they can also create the inverse effect.

For instance, including or importing a server module in a client module could potentially leak important data like API keys, database connections, so ALWAYS make sure you double-check your code before deploying it to production.

For me, [[Rails|https://rubyonrails.org]]/Laravel + Vue/React is still the best way to go, but if you're looking for a quick MVP or a small project, why not give it a go?

Stay safe, and happy coding!

Links 🔗

[[Nuxt|https://nuxt.com/]]
[[Next.js|https://nextjs.org/]]
[[Remix|https://remix.run/]]
[[TanStack Start|https://tanstack.com/start]]

Unraid, the perfect NAS, Streaming Server & Netflix-like service for your home & office

Pedro Martins — Sun, 05 Jan 2025 00:00:00 GMT

import Callout from "@components/Callout.astro"; import Button from "@components/Button.astro";

If you arrived here, you probably enjoy having a home server, NAS, or homelab. You might have heard about Unraid and are curious about what it is, how it works, and how you can use it to create your own Netflix-like service, NAS, or file system for your home or office.

1 - Why Unraid?

While Unraid is a pure OS that doesn't dictate specific hardware requirements, you might have heard of Synology, QNAP, or FreeNAS. While these are great solutions, they're not as flexible as Unraid and are often more expensive with hardware restrictions and slower performance.

If you're looking for a more flexible, faster, and cost-effective solution, Unraid is the way to go! Here are some advantages of Unraid:

Flexibility: Run Unraid on almost any hardware and expand as needed
Performance: Create fast NAS or streaming servers with excellent performance
Cost: Affordable licensing starting at $60, compatible with most hardware
Community: Active community with extensive help and support resources
Non-intrusive: Runs from USB without modifying your drives, allowing portability to other systems
Plugins: Extensive plugin ecosystem for customization and expansion
Docker: Built-in Docker support for running containerized applications

2 - Hardware Requirements

Unraid is based on Linux and runs on almost any hardware. Here are the recommended hardware requirements:

CPU: 64-bit processor running 1 GHz or higher
RAM: While not RAM-intensive, 4GB minimum is recommended
Storage: Flexible storage options; minimum 1TB HDD recommended for streaming
SSD: At least one SSD for cache and scratch disk operations
Network: 1Gbps connection recommended for streaming
Graphics: Optional for basic use; 4K-capable GPU recommended for media server transcoding

3 - The Basic Setup

After installing and setting up the OS, configure your shares, users, and permissions. Here are the key configurations I've set up (detailed tutorials are available online):

Shares: Separate shares for Movies, TV Shows, Music, and Photos
Users: Individual user accounts for family members with appropriate access
Permissions: Share-specific permissions controlling user access
Essential Plugins: Compose.Manager, NerdTools, GPU Stats, Nvidia Driver, Unassigned Devices, User Scripts
System Settings: NFS for macOS compatibility, UPS configuration, energy monitoring, notifications, Docker, VMs
Unraid Connect: Remote server management and notifications

4 - Docker & Containers

One of the greatest advantages of a Docker-centric OS is running containerized applications that can be wiped without affecting the host OS. This allows complete setup recreation without data loss.

Here's my Docker configuration:

Configuration Storage: Store all app configurations in a backed-up folder (e.g., /mnt/disk3/docker_data)
Docker Image Size: Set appropriate docker.img file size (I use 100GB)
Storage Location: Store docker.img on fast SSD storage
Management Interface: Use Unraid's native UI instead of Portainer for better integration
Service Organization: Group services by responsibility (media server, dev tools, etc.) in separate docker-compose files
Port Management: Organize ports to avoid conflicts; use reverse proxy when needed
Network Organization: Maintain clean networks for container communication and internal DNS

5 - External Access

With your server configured, you'll want external access to run it headlessly at home. While Unraid Connect provides server management, it doesn't grant access to your services.

Important: Verify your internet provider allows hosting services. Some providers block ports, requiring VPN or VPS solutions.

Obtain your public IP and ensure you have either a static IP or dynamic DNS setup for domain-based access.

5.1 - Domain & Cloudflare

I recommend purchasing a memorable domain for easy access from your devices. I use [[Cloudflare]] for DNS and domain management due to these benefits:

Free Service: No cost for DNS management with unlimited domains
Security Features: DDoS protection, WAF, and other security tools
Global Performance: Worldwide data centers for faster service delivery
Powerful API: Automation capabilities for domain management
Dynamic Updates: Automatic subdomain creation and IP address updates

Setup process: Purchase domain → Configure Cloudflare DNS → Point domain to your public IP.

Note: This assumes basic domain setup knowledge. Let me know if you need a detailed tutorial.

5.2 - Reverse Proxy

With your domain pointing to your public IP, you'll want subdomain access instead of port-based access.

This is where a reverse proxy like NGINX becomes essential!

We'll use [[Nginx Proxy Manager|https://nginxproxymanager.com/]] to manage subdomains, ports, and SSL certificate generation.

Here is a sample YAML file to get you started:

version: '3'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '3245:80' 
      - '3246:81'
      - '3247:443'
    volumes:
      - /mnt/disk3/docker_data/nginx_manager/data:/data
      - /mnt/disk3/docker_data/nginx_manager/letsencrypt:/etc/letsencrypt
    networks:
      - media_server_default
networks:
  media_server_default:
    external: true
  whisper_default:
    external: true

After the container starts, access the UI at 192.168.1.2:3246 to configure services and subdomains.

Local access only: Configure router port forwarding to enable external access:

Navigate to your router's IPv4 Port Forwarding settings and add these rules (adjust for your NAS IP):

80 → 3245
443 → 3247

This enables domain-based service access instead of ports.

How the Traffic Flow Works 🌐

Here's the simplified request flow:

Domain → Cloudflare (DNS + protection)
Cloudflare → Public IP (your home router)
Browser → Router (ports 80/443)
Router → Unraid Server (ports 3245/3247)
Nginx Proxy Manager → Service (based on subdomain)

Adding Services

Access services via subdomains by mapping them in Nginx Proxy Manager. For example, mapping bazar.domain.com to your local bazar container:

Important: Docker container names are case-sensitive.

Repeat this process for all services. The combination of Cloudflare and reverse proxy allows you to secure services behind firewalls or password protection.

6 - Media Server - Plex, Jellyfin & Emby

With your server configured, you can install a media server for streaming movies, TV shows, music, and more. You can either use your own media or download content from the internet. Please ensure you have proper rights to download and stream any content.

version: "2.1"
services:
  transmission:
    image: lscr.io/linuxserver/transmission:latest
    container_name: transmission
    environment:
      - PUID=99
      - PGID=100
      - UMASK=000
      - TZ=Europe/London
    volumes:
      - /mnt/disk3/docker_data/transmission/data:/config
      - /mnt/disk1/library/shows:/shows
      - /mnt/disk2/library/movies:/movies
      - /mnt/disk1/library/documentaries:/documentaries
      - /mnt/disk3/downloads:/downloads
    ports:
      - 9091:9091
      - 51413:51413
      - 51413:51413/udp
    restart: unless-stopped

  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    container_name: sonarr
    environment:
      - PUID=99
      - PGID=100
      - UMASK=000
      - TZ=Europe/London
    volumes:
      - /mnt/disk3/docker_data/sonarr/data:/config
      - /mnt/disk1/library/shows:/shows
      - /mnt/disk2/library/movies:/movies
      - /mnt/disk1/library/documentaries:/documentaries
      - /mnt/disk3/downloads:/downloads
      - /mnt/disk3/downloads:/config/downloads
    ports:
      - 8989:8989
    restart: unless-stopped

      
  radarr:
    image: lscr.io/linuxserver/radarr:latest
    container_name: radarr
    environment:
      - PUID=99
      - PGID=100
      - UMASK=000
      - TZ=Europe/London
    volumes:
      - /mnt/disk3/docker_data/radarrr/data:/config
      - /mnt/disk1/library/shows:/shows
      - /mnt/disk2/library/movies:/movies
      - /mnt/disk1/library/documentaries:/documentaries
      - /mnt/disk3/downloads:/downloads
      - /mnt/disk3/downloads:/config/downloads
    ports:
      - 7878:7878
    restart: unless-stopped

  bazarr:
    image: lscr.io/linuxserver/bazarr:latest
    container_name: bazarr
    environment:
      - PUID=99
      - PGID=100
      - UMASK=000
      - TZ=Europe/London
    volumes:
      - /mnt/disk3/docker_data/bazarr/data:/config
      - /mnt/disk1/library/shows:/shows
      - /mnt/disk2/library/movies:/movies
      - /mnt/disk1/library/documentaries:/documentaries
    ports:
      - 6767:6767
    restart: unless-stopped

  prowlarr:
    image: lscr.io/linuxserver/prowlarr:latest
    container_name: prowlarr
    environment:
      - PUID=99
      - PGID=100
      - UMASK=000
      - TZ=Europe/London
    volumes:
      - /mnt/disk3/docker_data/prowlarr/data:/config
      - /mnt/disk1/library/shows:/shows
      - /mnt/disk2/library/movies:/movies
      - /mnt/disk1/library/documentaries:/documentaries
      - /mnt/disk3/downloads:/downloads
    ports:
      - 9696:9696
    restart: unless-stopped

  sabnzbd:
    image: lscr.io/linuxserver/sabnzbd:latest
    container_name: sabnzbd
    environment:
      - PUID=99
      - PGID=100
      - UMASK=000
      - TZ=Europe/London
    volumes:
      - /mnt/disk3/docker_data/sabnzbd/data:/config
      - /mnt/disk3/downloads:/config/downloads
      - /mnt/disk3/downloads:/downloads
    ports:
      - 8329:8080
    restart: unless-stopped

  nzbget:
    image: lscr.io/linuxserver/nzbget:latest
    container_name: nzbget
    environment:
      - PUID=99
      - PGID=100
      - UMASK=000
      - TZ=Europe/London
    volumes:
      - /mnt/disk3/docker_data/nzbget/data:/config
      - /mnt/disk1/library/shows:/shows
      - /mnt/disk2/library/movies:/movies
      - /mnt/disk1/library/documentaries:/documentaries
      - /mnt/disk3/downloads:/downloads
    ports:
      - 6789:6789
    restart: unless-stopped

  overseerr:
    image: sctx/overseerr:latest
    container_name: overseerr
    environment:
      - LOG_LEVEL=debug
      - TZ=Europe/London
      - PORT=5055
      - PUID=99
      - PGID=100
      - UMASK=000
    ports:
      - 5055:5055
    volumes:
      - /mnt/disk3/docker_data/overseerr/data:/app/config
      - /mnt/disk1/library/shows:/shows
      - /mnt/disk2/library/movies:/movies
      - /mnt/disk1/library/documentaries:/documentaries
      - /mnt/disk3/downloads:/downloads
    restart: unless-stopped

  tautulli:
    image: lscr.io/linuxserver/tautulli:latest
    container_name: tautulli
    environment:
      - PUID=99
      - PGID=100
      - MASK=000
      - TZ=Europe/London
    volumes:
      - /mnt/disk3/docker_data/tautulli/data:/config
    ports:
      - 8181:8181
    restart: unless-stopped

  organizr:
    container_name: organizr
    hostname: organizr
    image: organizr/organizr:latest

    ports:
        - 8333:80
    volumes:
        - /mnt/disk3/docker_data/organizrr/data:/config
    environment:
        - PUID=99
        - PGID=100
        - TZ=Europe/London
    restart: unless-stopped

  maintainerr:
    image: jorenn92/maintainerr:latest
    container_name: maintainerr
    volumes:
      - /mnt/disk3/docker_data/maintainerr/data:/opt/data
    environment:
      - PUID=99
      - PGID=100
      - TZ=Europe/London
    ports:
      - 8154:80
    restart: unless-stopped
  wizarr:
    image: ghcr.io/wizarrrr/wizarr:latest
    container_name: wizarr
    ports:
      - 5690:5690
    volumes:
      - /mnt/disk3/docker_data/wizarr/database:/data/database

6.1.1 - Plex 📺

[[Plex]] is one of the best media servers available, offering extensive features and broad device compatibility.

Pros:

Easy setup and intuitive interface
Regular UI updates and improvements
Pre-installed apps on most TVs for easy friend/family sharing
Integrates with Netflix, Amazon Prime, etc. for unified library management

Cons:

Limited plugin ecosystem (mostly legacy)
Account dependency - Plex controls your access
Premium features require Plex Pass subscription
Mobile app requires payment for video playback (affects sharing)

6.1.2 - Jellyfin 🆓

[[Jellyfin]] is a completely free and open-source media server with extensive features and broad device compatibility.

Pros:

Truly free and open-source
Clean UI with regular updates
Complete server ownership and control
Service integrations for unified library management

Cons:

More technical setup required
Manual app installation needed (limited pre-installed availability)

6.1.3 - Emby 💰

[[Emby]] is a popular media server that transitioned from open-source to a freemium model. Like Plex, premium features require payment.

While more "free" than Plex, the closed-source nature is a drawback.

Pros:

Rich plugin ecosystem and advanced features
More configuration options than Plex
Free mobile app
Self-hosted with data ownership

Cons:

Closed-source model
Dated UI design (lacks modern aesthetics)
Premium feature paywall

6.1.4 - Best Media Server in 2025? 🏆

For home sharing with friends and family, Plex remains the top choice. It's the most user-friendly option with extensive features. Since most viewing happens on TVs rather than mobile devices, the mobile app cost becomes less significant. A one-time Plex Pass purchase offers excellent value.

6.2 - The *Arr Stack: Automation Suite 🤖

With your server and media server ready, let's explore automating content acquisition using specialized Docker containers from the community.

Why multiple applications? Each tool serves a specific purpose and excels at its designated task. This modular approach offers several benefits:

Specialized functionality: Series downloading differs from movies and music
Independent development: Each tool evolves at its own pace
Flexibility: Mix and match tools for your specific needs
Reliability: No single point of failure

<Callout icon="☝️" type="danger"> Please keep in mind that this tutorial will not cover on how to download movies, tv shows, music, etc. Please ensure you have the rights to download and stream the content that you are downloading. Subject to any applicable laws, you are responsible for your own actions. </Callout>

6.3 - *Arr Stack Capabilities 🎯

The *Arr software suite manages your media libraries and automates content acquisition, feeding new content directly to your media server.

Core Features:

Search: Find content across multiple indexers (Usenet, torrents)
Download: Automated content acquisition
Organization: Powerful renaming with proper metadata
Quality Control: Target specific qualities (4K, 1080p, 720p)
Scheduling: Track and schedule downloads

Application Roles:

[[Radarr]]: Movie management
[[Sonarr]]: TV show management
[[Prowlarr]]: Indexer management
[[Bazarr]]: Subtitle management
[[Tdarr]]: Media transcoding

6.4 - Content Acquisition Methods 📥

Here's an overview of the two main content acquisition methods (research Reddit communities for detailed information):

Usenet:

Distributed network since the 1980s
Fast, secure, and difficult to track
Requires: Provider + Indexer

Torrents:

Peer-to-peer network
Fast but easily trackable
Requires: Tracker + VPN (recommended)

Indexers: Search engines for both Usenet and torrent content

The *Arr software automates downloads from both sources based on your configuration.

6.5 - Usenet vs Torrents in 2025 ⚖️

While torrents remain viable, I've shifted to Usenet for primary content acquisition due to several factors:

Torrent Challenges:

Quality content frequently removed
Private tracker invite requirements
Seeding obligations for ratio maintenance
Provider dependency

Usenet Advantages:

Paid service reliability
No seeding requirements
Consistent availability
Enhanced security

I prefer paying for quality Usenet providers and indexers for reliable, fast, and secure downloads.

Note: This article won't recommend specific providers. Research Reddit communities to find services matching your needs.

6.6 - Localized Content & Subtitles 🌍

While most online media is available in English, localized content for family viewing often requires subtitles. Audio localization is more challenging, though you can configure preferences in Bazarr or Radarr.

[[Bazarr]] Capabilities:

Downloads subtitles from [[OpenSubtitles.org|https://opensubtitles.org]]
AI Generation: Uses [[@ahmetoner/whisper-asr-webservice]] AI for subtitle creation
Translation: Converts English subtitles to other languages (generally effective)

Here's my automation script for subtitle translation on Unraid:

import json
import os
from urllib import request, error

# ------------------
# Credentials
# ------------------
TRANSLATION_FILE_PATH = './translation_attempts.json'
API_KEY = 'YOURKEY'
API_BASE_URL = 'https://YOURBAZARURL.com/api'
COMMON_HEADERS = {
    'Accept': 'application/json',
    'X-API-KEY': API_KEY,
    'User-Agent': 'curl/8.4.0'
}

# ------------------
# Make a request
# ------------------
def make_request(url, method='GET'):
    req = request.Request(url, method=method, headers=COMMON_HEADERS)
    try:
        with request.urlopen(req) as response:
            if response.status == 200 or response.status == 204:
                return json.loads(response.read().decode()) if method == 'GET' else True
            else:
                print(f"Failed request at {url}, Status code: {response.status}")
                return None
    except error.HTTPError as e:
        #print(f"HTTP error: {e.code} - {e.reason}")
        return None
    except error.URLError as e:
        #print(f"URL error: {e.reason}")
        return None
    
# ------------------
# Load The attempts
# ------------------
def load_translation_attempts():
    if os.path.exists(TRANSLATION_FILE_PATH):
        with open(TRANSLATION_FILE_PATH, 'r') as file:
            return json.load(file)
    return {}

# ------------------
# Save The Attempts
# ------------------
def save_translation_attempts(attempts):
    with open(TRANSLATION_FILE_PATH, 'w') as file:
        json.dump(attempts, file, indent=4)

# ------------------
# Get all series IDs
# ------------------
def get_series_ids():
    data = make_request(f"{API_BASE_URL}/series?start=0&length=-1")
    return [series['sonarrSeriesId'] for series in data['data']] if data else []

# ------------------
# Get subtitle paths for multiple series
# ------------------
def get_subtitle_paths_for_multiple_series(series_ids):
    # Constructing the query string for multiple series IDs
    series_ids_query = '&'.join([f'seriesid%5B%5D={id}' for id in series_ids])
    episode_url = f"{API_BASE_URL}/episodes?{series_ids_query}"

    data = make_request(episode_url)
    subtitle_info = []
    if data:
        for episode in data['data']:
            english_subtitles = [sub for sub in episode['subtitles'] if sub['code2'] == 'en']
            portuguese_subtitles = [sub for sub in episode['subtitles'] if sub['code2'] == 'pt']
            if english_subtitles and not portuguese_subtitles:
                subtitle_info.extend([{
                    'path': sub['path'],
                    'id': episode['sonarrEpisodeId'],
                    'type': 'episode'
                } for sub in english_subtitles if sub['path'] is not None])
    return subtitle_info

# ------------------
# Get subtitle paths for movies
# ------------------
def get_movie_subtitle_paths():
    data = make_request(f"{API_BASE_URL}/movies?start=0&length=-1")
    subtitle_info = []
    if data:
        for movie in data['data']:
            english_subtitles = [sub for sub in movie['subtitles'] if sub['code2'] == 'en']
            portuguese_subtitles = [sub for sub in movie['subtitles'] if sub['code2'] == 'pt']
            if english_subtitles and not portuguese_subtitles:
                subtitle_info.extend([{
                    'path': sub['path'],
                    'id': movie['radarrId'],
                    'type': 'movie'
                } for sub in english_subtitles if sub['path'] is not None])
    return subtitle_info

# ------------------
# Translate subtitle
# ------------------
# Update the translate_subtitle function
def translate_subtitle(subtitle_info, language='pt'):
    subtitle_path = subtitle_info['path']
    translation_attempts = load_translation_attempts()

    if translation_attempts.get(subtitle_path, 0) >= 3:
        print(f"Skipping translation for {subtitle_path} due to multiple failures.")
        return

    if make_request(f"{API_BASE_URL}/subtitles?action=translate&language={language}&path={request.quote(subtitle_path)}&type={subtitle_info['type']}&id={subtitle_info['id']}", 'PATCH'):
        print(f"Translate: Subtitle translated: {subtitle_path}")
    else:
        print(f"Translate: Failed to translate subtitle: {subtitle_path}")
        translation_attempts[subtitle_path] = translation_attempts.get(subtitle_path, 0) + 1
        save_translation_attempts(translation_attempts)

# ------------------
# Translate Series
# ------------------
def translate_series():
    # Usage
    all_series_ids = get_series_ids()

    # Check if there are any series IDs, exit if not
    if not all_series_ids:
        print("Series: No series found to process.")
        #exit(0)

    all_subtitles_info = get_subtitle_paths_for_multiple_series(all_series_ids)

    # Check if there are any subtitle paths, exit if not
    if not all_subtitles_info:
        print("Series: No subtitle paths found to translate.")
        #exit(0)

    # Translate 10 Subtitles
    subtitles_to_translate = all_subtitles_info[:20]

    # Translate the selected subtitles
    for subtitle in subtitles_to_translate:
        translate_subtitle(subtitle)

# ------------------
# Translate Movies
# ------------------
def translate_movies():
    # Usage
    all_subtitles_info = get_movie_subtitle_paths()

    # Check if there are any subtitle paths, exit if not
    if not all_subtitles_info:
        print("Movies: No subtitle paths found to translate.")
        #exit(0)

    # Translate 10 Subtitles
    subtitles_to_translate = all_subtitles_info[:20]

    # Translate the selected subtitles
    for subtitle in subtitles_to_translate:
        translate_subtitle(subtitle)

# ------------------
# Main
# ------------------
if __name__ == '__main__':
    translate_series()
    translate_movies()

6.7 - Transcoding & Optimization 🎬

For advanced streaming optimization, research transcoding and optimal streaming formats. No perfect video/audio format exists - it depends on your use case and playback hardware.

While platforms like Netflix convert content into multiple codecs for different users, home servers can't afford this luxury of storing multiple formats per movie.

Choose formats that best fit your specific needs. Transcoding serves two purposes:

Space saving: Smaller file sizes
Performance: Faster streaming

6.8 - Format Selection 📋

HEVC + H.265: Modern format for 2015+ hardware MP4 + H.264: Widely compatible with modern and legacy devices

While H.265 offers better compression for 2025 streaming, it requires newer hardware. For family sharing, ensure devices support H.265, otherwise Plex will transcode to H.264, increasing hardware usage and power consumption.

6.9 - Transcoding & Processing Pipeline 🔄

Here's what you need to know about transcoding and video processing software.

Configure Radarr and Sonarr to prefer specific formats to minimize re-processing needs.

<Callout icon="☝️" type="info"> A budget NVIDIA GPU is recommended for efficient transcoding. CPU transcoding is resource-intensive and consumes more energy. </Callout>

File Processing Benefits:

Compression: Reduce disk space usage
Audio Management: Remove unwanted language tracks
Subtitle Control: Remove unnecessary subtitle tracks
Format Conversion: Convert audio formats (5.1 to 2.1)
Subtitle Extraction: Extract subtitles for translation
Track Organization: Organize audio and subtitle track order

All processing relies on [[FFmpeg]] - consider supporting this amazing project!

Tool Comparison:

[[Tdarr|https://home.tdarr.io/]]:

Advanced features
Popular community choice
Open source with freemium model
Complex UI that can be confusing

[[Fileflows|https://fileflows.com/]]:

Superior user interface
Built-in plugins and tools
Responsive smaller community
Intuitive flow building
Easy multi-node setup
Better Docker integration

Results: Saved approximately 3TB from my current library!

For large transcoding workloads, deploy multiple nodes working in parallel for simultaneous content processing.

6.10 - Advanced Media Server Features 🚀

Enhance your media server setup with these additional tools for a better library experience:

[[Tautulli|https://tautulli.com/]]: Monitor Plex server performance, user statistics, and transcoding metrics
[[Overseerr|https://overseerr.dev/]]: Enable friends and family to request content with approval workflows for automatic downloads
[[Kometa|https://github.com/Kometa-Team/Kometa]]: Plex Meta Manager for enhanced metadata, custom categories, library organization, and popular content lists
[[Wizarr|https://wizarr.dev/]]: Streamlined user invitation system with permission management
[[Organizr|https://organizr.app/]]: Unified dashboard for all your services with clean UI access
[[Maintainerr|https://github.com/maintainerr/maintainerr]]: Automatically manage content lifecycle - remove unwatched or completed content

7 - Energy Efficiency ⚡

Energy saving is often overlooked but crucial for high-end servers running 24/7. Here are effective power management strategies:

Disk Spindown: Automatically spin down unused drives to reduce power consumption
Sleep Mode: Enable server sleep mode with wake-on-demand capabilities
CPU Power Management: Configure power scaling based on usage patterns
GPU Power Management: Optimize NVIDIA GPU power states when idle

#!/bin/bash
# check for driver
command -v nvidia-smi &> /dev/null || { echo >&2 "nvidia driver is not installed you will need to install this from community applications ... exiting."; exit 1; }
echo "Nvidia drivers are installed"
echo
echo "I can see these Nvidia gpus in your server"
echo
nvidia-smi --list-gpus 
echo
echo "-------------------------------------------------------------"
# set persistence mode for gpus ( When persistence mode is enabled the NVIDIA driver remains loaded even when no active processes, 
# stops modules being unloaded therefore stops settings changing when modules are reloaded
nvidia-smi --persistence-mode=1
#query power state
gpu_pstate=$(nvidia-smi --query-gpu="pstate" --format=csv,noheader);
#query running processes by pid using gpu
gpupid=$(nvidia-smi --query-compute-apps="pid" --format=csv,noheader);
#check if pstate is zero and no processes are running by checking if any pid is in string
if [ "$gpu_pstate" == "P0" ] && [ -z "$gpupid" ]; then
echo "No pid in string so no processes are running"
fuser -kv /dev/nvidia*
echo "Power state is"
echo "$gpu_pstate" # show what power state is
else
echo "Power state is" 
echo "$gpu_pstate" # show what power state is
fi
echo
echo "-------------------------------------------------------------"
echo
echo "Power draw is now"
# Check current power draw of GPU
nvidia-smi --query-gpu=power.draw --format=csv
exit

8 - Data Protection: Backups & Parity 🛡️

Unraid's Parity system protects your data differently from traditional RAID. Parity offers more flexibility and allows expansion as needed.

For detailed information about Parity, RAID, and backups, consult the [[Unraid FAQ|https://docs.unraid.net/legacy/FAQ/Parity/]].

My Backup Strategy: I use [[Duplicacy|http://duplicacy.com]] for cloud backups with easy restoration capabilities. Currently storing backups with [[Backblaze|https://www.backblaze.com/]] for their excellent service quality and competitive pricing.

9 - Expanding Your Unraid Capabilities 🚀

The possibilities are endless with your NAS and Unraid setup. Run virtually any application including:

Personal cloud storage (Dropbox alternative)
LLM inference servers
DNS ad-blocking servers
Development environments
Home automation systems

Unraid's Docker support enables running almost any containerized application with simple expansion capabilities.

The community app ecosystem grows daily, providing countless applications installable with just a few clicks.

10 - Conclusion 🎬

We've explored Unraid fundamentals, setup procedures, and how to create your own Netflix-like service, NAS, or office file system. The configuration and tweaking process has been enjoyable while learning about Docker, Linux, and microservices.

Disclaimer: Some information may contain inaccuracies as I'm sharing personal learning experiences. This article aims to help you start your own NAS and Unraid journey.

11 - My Hardware Specifications 💻

Here's my current hardware setup:

CPU: Intel® Core™ i7-8700 @ 3.20GHz
RAM: 16GB DDR4
GPU: RTX A2000
Motherboard: Gigabyte Z390 DESIGNARE-CF
Network: 1Gbps (1GB Download / 500MB Upload)
UPS: APC Back-UPS Pro 900
Storage: 2x 10TB WDC WD101KRYZ drives
Cache: 2x 1TB Samsung SSD 970 EVO Plus

Do you need this much? No! I repurposed existing hardware for this project. You can run the same setup with much less powerful hardware.

12 - References & Links 🔗

[[Unraid|https://unraid.net/]]
[[Usenet Indexers|https://www.reddit.com/r/Usenet/wiki/indexers/]]
[[Usenet Providers|https://www.reddit.com/r/usenet/wiki/providers]]
[[LinuxServer Images|https://docs.linuxserver.io/images/docker-adguardhome-sync/]]
[[Fileflows|https://fileflows.com/]]
[[Best Movies Lists|https://mdblist.com/]]

Roast ®

Pedro Martins — Wed, 01 Jan 2025 00:00:00 GMT

A funny AI-powered social media profile roaster to try our AI skills :p

Flavorly ®

Pedro Martins — Sun, 01 Dec 2024 00:00:00 GMT

Open-source contributions to Laravel, Javascripts, Vue, React, etc.

Vue 3 & React - Ticker, Marquee, Carousel Component

Pedro Martins — Mon, 02 Sep 2024 00:00:00 GMT

import DemoReact from "./demo.tsx";

Introduction

I fell in love with [[Framer|https://framer.com]] Marquees when they launched and wanted to integrate them into one of my projects. However, I encountered several issues:

In React and Vue, I couldn't find packages/components that met my requirements
Existing solutions weren't polished enough for my design standards

Here are my specific requirements:

Hover slowdown: Mouse hover should reduce animation speed
Pause on hover: Complete animation pause when hovering
Auto-cloning: Clone items if insufficient content to fill the container
Endless repeat: Seamless infinite loop
Edge fading: Smooth fade effects on container edges
Touch support: Mobile-friendly interactions
Multi-directional: Both vertical and horizontal orientations
Performance: Render only when visible (intersection observer)

You might wonder: why not use a carousel? Carousels and marquees serve different purposes. Carousels display a few items at once with navigation controls, while marquees show continuous flowing content—perfect for news feeds, stock tickers, or sliding content displays.

While you could theoretically achieve this with pure CSS, I encountered issues with that approach. CSS animations caused inconsistent behavior, especially during hover slowdown effects.

After deeper investigation, I decided to build custom Marquee/Ticker components for both React and Vue.

Technical Challenges 🛠️

Here are the key challenges I faced while building this component:

DOM Measurement Timing: We must measure parent and child dimensions on the next tick since the DOM isn't ready immediately. This calculation determines how many duplicates we need for seamless scrolling
Framework Differences: Slots work differently in Vue and React, requiring separate handling strategies for each framework
Pixel-Perfect Animation: Creating a requestAnimationFrame ticker that loops seamlessly without visible jumps—precision is critical for smooth user experience

Vue 3 Implementation 🟢

<script setup lang="ts">
import type { ComputedRef, CSSProperties } from 'vue'
import { useFade } from '@/utils/fade-mask'

/**
 * Some notes:
 * - We cannot apply any kind of transition to the ticker because it will break the animation ( say tailwindcss classes )
 * - Types imported from vue are not working properly so we must keep styles inline
 */

export interface SizingOptions {
	widthType: boolean
	heightType: boolean
}

export interface FadeOptions {
	content: boolean
	overflow: boolean
	width: number
	alpha: number
	inset: number
}

export interface PaddingOptions {
	padding: number
	perSide: boolean
	top: number
	right: number
	bottom: number
	left: number
}

export interface TickerProps {
	gap?: number | string
	speed?: number | string
	hoverFactor?: number | string
	direction?: string | boolean | 'left' | 'right' | 'top' | 'bottom'
	alignment?: string | 'flex-start' | 'center' | 'flex-end'
	sizingOptions?: SizingOptions
	fadeOptions?: FadeOptions
	paddingOptions?: PaddingOptions
}

defineOptions({
	inheritAttrs: false,
})

const props = withDefaults(defineProps<TickerProps>(), {
	gap: 10,
	speed: 20,
	hoverFactor: 3,
	direction: 'right',
	alignment: 'center',
	paddingOptions: () => ({
		padding: 10,
		perSide: false,
		top: 0,
		right: 0,
		bottom: 0,
		left: 0
	}),
	sizingOptions: () => ({
		widthType: true,
		heightType: true
	}),
	fadeOptions: () => ({
		content: true,
		overflow: false,
		width: 50,
		alpha: 0,
		inset: 0
	}),
})

const containerStyle = {
	display: 'flex',
	width: '100%',
	height: '100%',
	maxWidth: '100%',
	maxHeight: '100%',
	placeItems: 'center',
	margin: 0,
	padding: 0,
	listStyleType: 'none',
	textIndent: 'none'
}

// Utility: Wrap Utility
const wrap = (min: number, max: number, v: number) => {
	const rangeSize = max - min
	return ((((v - min) % rangeSize) + rangeSize) % rangeSize) + min
}

// The main container ref
const container = ref<HTMLElement>()
// The UL container that contains the children
const containerItems = ref<HTMLElement>()
// Stores the Refs for the original elements
const elementsOriginal = shallowRef()
// Stores the Refs of the cloned elements
const elementsCloned = shallowRef()
// Checks if its hovered or not
const isHovered = ref(false)

// Amount of duplicates required to fill the container and provide a smooth animation
const duplicateBy = ref(1)

// Sizes of Container
const sizes = reactive({
	parent: 0,
	children: 0,
})

// First and last child to calculate the size properly
const firstChild = computed(() => unrefElement(elementsOriginal.value[0])) as unknown as ComputedRef<HTMLElement>
const lastChild = computed(() => unrefElement(elementsOriginal.value[elementsOriginal.value.length - 1])) as unknown as ComputedRef<HTMLElement>

// Get the padding on each side if required
const containerPadding = computed(() => props.paddingOptions.perSide
	? `${props.paddingOptions.top}px ${props.paddingOptions.right}px ${props.paddingOptions.bottom}px ${props.paddingOptions.left}px`
	: `${props.paddingOptions.padding}px`
)

// Check if the container has children
const hasItems = computed(() => {
	if (!containerItems.value) {
		return false
	}

	return containerItems.value.children?.length > 0
})

// Checks if the container is horizontal or vertical
const isHorizontal = computed(() => props.direction === 'left' || props.direction === 'right')

// Checks the direction of the animation
const direction = computed(() => props.direction)

// The speed of the animation
const speed = computed(() => Number(props.speed))

// The value to animate to, this a very important value because it determines the end of the animation
// Usually this is the size of the children + the size of the parent so lets say 3x multiplier
const animateToValue = computed(() => sizes.children + sizes.children * Math.round(sizes.parent / sizes.children))

// Value that holds the main animation translate value
const xOrY = ref<number>(0)

// The initial time of the animation & time related values
const timeInitial = ref<number | null>(null)
const timePrevious = ref<number | null>(null)

// Store the frame of the animation via requestAnimationFrame
const animationFrame = ref<number | null>(null)

// Fade Options
const fadeMask = useFade(isHorizontal.value ? 'horizontal' : 'vertical', props.fadeOptions)

// Since vue resets the manual styles on update, we will use reactive styles
const reactiveStyles = computed(() => ({
	...containerStyle,
	gap: `${props.gap}px`,
	placeItems: props.alignment,
	position: 'relative',
	flexDirection: isHorizontal.value ? 'row' : 'column',
	willChange: 'transform',
	top: props.direction === 'bottom' ? `-${animateToValue.value}px` || 0 : undefined,
	left: props.direction === 'right' ? `-${animateToValue.value}px` || 0 : undefined,
	perspective: '1000px',
	backfaceVisibility: 'hidden',
})) as unknown as CSSProperties

/**
 * Measures the container and children
 */
const measure = () => {
	// Must have items, container and first child
	if (!hasItems.value || !container.value || !containerItems.value) {
		return
	}

	// Must have first and last child
	if (!firstChild.value || !lastChild.value) {
		console.warn('First and last child must be present. Ensure the ticker has only one child and that child has one root')
		return
	}

	// Get the size of the parent
	const parentLength = isHorizontal.value ? container.value.offsetWidth : container.value.offsetHeight

	// Get the size of the first child
	const start = firstChild.value
		? (isHorizontal.value ? firstChild.value.offsetLeft : firstChild.value.offsetTop)
		: 0

	// Get The size of the last child
	const end = lastChild.value
		? (isHorizontal.value ? lastChild.value.offsetLeft + lastChild.value.offsetWidth : lastChild.value.offsetTop + lastChild.value.offsetHeight)
		: 0

	// Get the size of the children with the gap in mind
	const childrenLength = end - start + Number(props.gap)

	// Finally set the sizes
	sizes.parent = parentLength
	sizes.children = childrenLength

	if (sizes.parent <= 0 || sizes.children <= 0) {
		// console.warn('Unable to get parent or child size. Ensure the ticker has only one child and that child has one root')
		return
	}

	// Also update the duplication
	const duplicateResult = Math.round(sizes.parent / sizes.children * 2) + 1

	// If value is different and more then 0 and less then 200
	if (duplicateResult !== duplicateBy.value && duplicateResult > 0 && duplicateResult <= 200) {
		duplicateBy.value = duplicateResult
	}
}

const ticker = (animationTiming: number) => {
	if (!containerItems.value) {
		return
	}

	// Set initial time if it's null
	if (timeInitial.value === null) {
		timeInitial.value = animationTiming
	}

	// Adjust time elapsed
	animationTiming -= timeInitial.value
	const timeSinceLast = timePrevious.value === null ? 0 : animationTiming - timePrevious.value
	let delta = timeSinceLast * (speed.value / 1e3)

	// If its hover we want to reduce the speed, so we divide by the hover factor
	if (isHovered.value) {
		delta = delta / Number(props.hoverFactor)
	}

	// Wrap the value so it doesn't go over the max
	xOrY.value = wrap(0, animateToValue.value, xOrY.value + delta)

	// Apply transform based on direction
	if (direction.value === 'left') {
		containerItems.value.style.transform = `translate3d(-${xOrY.value}px, 0, 0)`
	}

	if (direction.value === 'right') {
		containerItems.value.style.transform = `translate3d(${xOrY.value}px, 0, 0)`
	}

	if (direction.value === 'top') {
		containerItems.value.style.transform = `translate3d(0, -${xOrY.value}px, 0)`
	}

	if (direction.value === 'bottom') {
		containerItems.value.style.transform = `translate3d(0, ${xOrY.value}px, 0)`
	}

	// Point the previous time to the current time
	timePrevious.value = animationTiming
	// Request the next frame
	animationFrame.value = requestAnimationFrame(ticker)
}

/**
 * Starts the animation
 */
const animationStart = () => {
	if (!containerItems.value) {
		return
	}
	// Initial Frame Request
	animationFrame.value = requestAnimationFrame(ticker)
}

/**
 * Stops the animation
 */
const animationStop = () => animationFrame.value && cancelAnimationFrame(animationFrame.value)

// Intersection Observer
const { stop: stopIntersectionObserver } = useIntersectionObserver(
	container,
	([{ isIntersecting }]) => {
		if (isIntersecting) {
			animationStart()
		} else {
			animationStop()
		}
	}
)

// Await next tick to ensure the DOM is ready
tryOnMounted(() => {
	nextTick(() => {
		measure()
		animationStart()
	})
})

// Clear the animation frame on unmount
onUnmounted(() => {
	animationStop()
	stopIntersectionObserver()
})

defineExpose({
	measure,
	translate: xOrY
})

</script>
<template>
	<div
		ref="container"
		data-ticker="true"
		:class="{
			'overflow-hidden': !props.fadeOptions.overflow,
			'overflow-visible': props.fadeOptions.overflow,
		}"
		:style="{
			...containerStyle,
			padding: containerPadding,
			maskImage: props.fadeOptions.content ? fadeMask : undefined,
		}"
	>
		<ul
			ref="containerItems"
			:style="reactiveStyles"
			@mouseenter="isHovered = true"
			@mouseleave="isHovered = false"
		>
			<template
				v-for="(children, i) in $slots.default?.()[0]?.children ?? []"
				:key="i"
			>
				<x-ticker-item>
					<component
						:is="children"
						ref="elementsOriginal"
					/>
				</x-ticker-item>
			</template>
			<template
				v-for="z in duplicateBy"
				:key="z"
			>
				<template
					v-for="(children, i) in $slots.default?.()[0]?.children ?? []"
					:key="i"
				>
					<x-ticker-item>
						<component
							:is="children"
							ref="elementsCloned"
						/>
					</x-ticker-item>
				</template>
			</template>
		</ul>
	</div>
</template>

React Implementation ⚛️

'use client'

import type { CSSProperties, ReactNode, RefObject, JSX, ReactElement, HTMLAttributes } from 'react'
import { Children, useLayoutEffect, useEffect, useRef, useMemo, createRef, useState, useCallback, cloneElement } from 'react'
import { RenderTarget } from 'framer'
import { useAnimationFrame, useReducedMotion, LayoutGroup } from 'framer-motion'
import { debounce } from 'lodash-es'
import { wrap } from 'popmotion'

interface SizingOptions {
  widthType: boolean;
  heightType: boolean;
}

interface FadeOptions {
  fadeContent: boolean;
  overflow: boolean;
  fadeWidth: number;
  fadeAlpha: number;
  fadeInset: number;
}

interface TransitionControl {
  type: string;
  ease: string;
  duration: number;
}

interface TickerProps extends HTMLAttributes<'div'>{
  slots: ReactElement[];
  gap: number;
  padding: number;
  paddingPerSide?: boolean;
  paddingTop?: number;
  paddingRight?: number;
  paddingBottom?: number;
  paddingLeft?: number;
  speed?: number;
  hoverFactor?: number;
  direction?: string | boolean | 'left' | 'right' | 'top' | 'bottom';
  alignment?: string | 'flex-start' | 'center' | 'flex-end';
  sizingOptions?: SizingOptions;
  fadeOptions?: FadeOptions;
  transitionControl?: TransitionControl;
  style?: CSSProperties;
}

/* Placeholder Styles */
const containerStyle = {
  display: 'flex',
  width: '100%',
  height: '100%',
  maxWidth: '100%',
  maxHeight: '100%',
  placeItems: 'center',
  margin: 0,
  padding: 0,
  listStyleType: 'none',
  textIndent: 'none'
}

/* Clamp function, used for fadeInset */
const clamp = (num: number, min: number, max: number) => Math.min(Math.max(num, min), max)

export default function Ticker({
  gap = 10,
  padding = 10,
  paddingPerSide,
  paddingTop,
  paddingRight,
  paddingBottom,
  paddingLeft,
  speed = 10,
  hoverFactor = 5,
  direction = true,
  alignment = 'center',
  sizingOptions = {
    widthType: true,
    heightType: true
  },
  fadeOptions = {
    fadeContent: true,
    overflow: false,
    fadeWidth: 100,
    fadeAlpha: 0,
    fadeInset: 0
  },
  style,
  slots,
  className,
}: TickerProps) {

  const {
    fadeContent,
    overflow,
    fadeWidth,
    fadeInset,
    fadeAlpha
  } = fadeOptions

  const {
    widthType,
    heightType
  } = sizingOptions

  const paddingValue = paddingPerSide ? `${paddingTop}px ${paddingRight}px ${paddingBottom}px ${paddingLeft}px` : `${padding}px`

  /* Checks */
  const isCanvas = RenderTarget.current() === RenderTarget.canvas
  const hasChildren = Children.count(slots) > 0
  const isHorizontal = direction === 'left' || direction === 'right'

  /* Empty state */
  if (!hasChildren || !slots) {
    throw new Error('You must add at least one child to the Ticker component.')
  }

  /* Refs and State */
  const parentRef = useRef<HTMLDivElement>(null)
  const childrenRef = useMemo<[RefObject<HTMLDivElement>, RefObject<HTMLDivElement>]>(() => [createRef(), createRef()], [])
  const [size, setSize] = useState<{ parent: number; children: number }>({
    parent: 0,
    children: 0
  })

  /* Arrays */
  let clonedChildren: ReactNode[] | JSX.Element[]
  let dupedChildren: ReactNode[] | JSX.Element[] = []

  /* Duplicate value */
  let duplicateBy = 0
  let opacity = 0

  if (isCanvas) {
    duplicateBy = 20
    opacity = 1
  }

  if (!isCanvas && hasChildren && size.parent) {
    duplicateBy = Math.round(size.parent / size.children * 2) + 1
    opacity = 1
  }

  /* Measure parent and child */
  const measure = useCallback(() => {
    if (hasChildren && parentRef.current) {
      const parentLength = isHorizontal ? parentRef.current.offsetWidth : parentRef.current.offsetHeight
      const start = childrenRef[0].current ? isHorizontal ? childrenRef[0].current.offsetLeft : childrenRef[0].current.offsetTop : 0
      const end = childrenRef[1].current ? isHorizontal ? childrenRef[1].current.offsetLeft + childrenRef[1].current.offsetWidth : childrenRef[1].current.offsetTop + childrenRef[1].current.offsetHeight : 0
      const childrenLength = end - start + gap
      setSize({
        parent: parentLength,
        children: childrenLength
      })
    }
  }, [childrenRef, gap, hasChildren, isHorizontal])

  /* Add refs to first and last child */
  useLayoutEffect(() => {
    !isCanvas && measure()
  }, [isCanvas, measure])

  /**
  * Track whether this is the initial resize event. By default this will fire on mount,
  * which we do in the useEffect. We should only fire it on subsequent resizes.
  */
  let initialResize = useRef(true)

  useEffect(() => {
    if (isCanvas || !parentRef.current) {
      return
    }

    const handleResize = debounce(() => {
      if (!initialResize.current) {
        measure()
      }
      initialResize.current = false
    }, 1500) // 300 ms debounce time

    window.addEventListener('resize', handleResize)

    return () => {
      window.removeEventListener('resize', handleResize)
    }
  }, [isCanvas, measure])

  // @ts-ignore
  clonedChildren = Children.map(slots, (child, index) => {
    let selectedRef = null
    if (index === 0) {
      selectedRef = childrenRef[0]
    }

    if (index === slots.length - 1) {
      selectedRef = childrenRef[1]
    }

    return (
      <LayoutGroup inherit="id">
        <li
          style={{ display: 'contents' }}
        >
          {cloneElement(child, {
            key: `cloned-child-${index}`,
            ref: selectedRef,
            style: {
              ...(child.props?.style),
              width: widthType ? child.props?.width : '100%',
              height: heightType ? child.props?.height : '100%',
              flexShrink: 0,
            },
          }, child.props?.children)}
        </li>
      </LayoutGroup>
    )
  })

  for (let i = 0; i < duplicateBy; i++) {
    dupedChildren = [
      ...dupedChildren,
      ...Children.map(slots, (child, childIndex) => {
        return (
          <LayoutGroup inherit="id" key={`duped-child-${i}-${childIndex}`}>
            <li style={{ display: 'contents' }}>
              {cloneElement(child, {
                style: {
                  ...child.props.style,
                  width: widthType ? child.props.width : '100%',
                  height: heightType ? child.props.height : '100%',
                  flexShrink: 0
                }
              }, child.props.children)}
            </li>
          </LayoutGroup>
        )
      })
    ]
  }

  const animateToValue = size.children + size.children * Math.round(size.parent / size.children)
  const transformRef = useRef<HTMLUListElement>(null)
  const initialTime = useRef<number| null>(null)
  const prevTime = useRef<number | null>(null)
  const xOrY = useRef(0)
  const isHover = useRef(false)
  const isReducedMotion = useReducedMotion()

  useAnimationFrame(t => {
    if (!transformRef.current || !animateToValue || isReducedMotion) {
      return
    }

    /**
     * In case this animation is delayed from starting because we're running a bunch
     * of other work, we want to set an initial time rather than counting from 0.
     * That ensures that if the animation is delayed, it starts from the first frame
     * rather than jumping.
     */
    if (initialTime.current === null) {
      initialTime.current = t
    }

    t = t - initialTime.current
    const timeSince = prevTime.current === null ? 0 : t - prevTime.current
    let delta = timeSince * (speed / 1e3)

    if (isHover.current) {
      delta *= hoverFactor
    }

    xOrY.current += delta
    xOrY.current = wrap(0, animateToValue, xOrY.current)
    /* Direction */

    if (direction === 'left') {
      transformRef.current.style.transform = `translateX(-${xOrY.current}px)`
    }

    if (direction === 'right') {
      transformRef.current.style.transform = `translateX(${xOrY.current}px)`
    }

    if (direction === 'top') {
      transformRef.current.style.transform = `translateY(-${xOrY.current}px)`
    }

    if (direction === 'bottom') {
      transformRef.current.style.transform = `translateY(${xOrY.current}px)`
    }

    prevTime.current = t
  })

  /* Fades */
  const fadeDirection = isHorizontal ? 'to right' : 'to bottom'
  const fadeWidthStart = fadeWidth / 2
  const fadeWidthEnd = 100 - fadeWidth / 2
  const fadeInsetStart = clamp(fadeInset, 0, fadeWidthStart)
  const fadeInsetEnd = 100 - fadeInset
  const fadeMask = `linear-gradient(${fadeDirection}, rgba(0, 0, 0, ${fadeAlpha}) ${fadeInsetStart}%, rgba(0, 0, 0, 1) ${fadeWidthStart}%, rgba(0, 0, 0, 1) ${fadeWidthEnd}%, rgba(0, 0, 0, ${fadeAlpha}) ${fadeInsetEnd}%)`

  return (
    <section
      className={className}
      data-ticker={true}
      ref={parentRef}
      style={{
        ...containerStyle,
        opacity,
        padding: paddingValue,
        WebkitMaskImage: fadeContent ? fadeMask : undefined,
        MozMaskImage: fadeContent ? fadeMask : undefined,
        maskImage: fadeContent ? fadeMask : undefined,
        overflow: overflow ? 'visible' : 'hidden',
      } as CSSProperties}
    >
      <ul
        className={'transform-gpu'}
        ref={transformRef}
        style={{
          ...containerStyle,
          gap,
          top: direction === 'bottom' ? -animateToValue || 0 : undefined,
          left: direction === 'right' ? -animateToValue || 0 : undefined,
          placeItems: alignment,
          position: 'relative',
          flexDirection: isHorizontal ? 'row' : 'column',
          willChange: 'transform',
          ...style,
        }}
        onMouseEnter={() => (isHover.current = true)}
        onMouseLeave={() => (isHover.current = false)}
      >
        <>
          {clonedChildren}
          {dupedChildren}
        </>
      </ul>
    </section>
  )
}

Fade Utility 🎨

import type { MaybeRef } from 'vue'
import { computed } from 'vue'

export interface FadeOptions {
	content: boolean
	overflow: boolean
	width: number
	alpha: number
	inset: number
}

function clamp(value: number, min: number, max: number): number {
	return Math.min(Math.max(value, min), max)
}

// The useFade composable function
export function useFade(orientation: MaybeRef<'horizontal' | 'vertical' | undefined>, fadeOptions: FadeOptions) {
	const orientationValue = toValue(orientation)
	const isHorizontal = computed(() => orientationValue === 'horizontal')
	const fadeDirection = computed(() => isHorizontal.value ? 'to right' : 'to bottom')
	const fadeWidthStart = computed(() => fadeOptions.width / 2)
	const fadeWidthEnd = computed(() => 100 - fadeOptions.width / 2)
	const fadeInsetStart = computed(() => clamp(fadeOptions.inset, 0, fadeWidthStart.value))
	const fadeInsetEnd = computed(() => 100 - fadeOptions.inset)
	return computed(() => `linear-gradient(${fadeDirection.value}, rgba(0, 0, 0, ${fadeOptions.alpha}) ${fadeInsetStart.value}%, rgba(0, 0, 0, 1) ${fadeWidthStart.value}%, rgba(0, 0, 0, 1) ${fadeWidthEnd.value}%, rgba(0, 0, 0, ${fadeOptions.alpha}) ${fadeInsetEnd.value}%)`)
}

Usage Tips 💡

Both implementations support the same core features:

Direction: 'left', 'right', 'top', 'bottom'
Speed Control: Adjustable animation speed
Hover Effects: Slowdown and pause on hover
Fade Options: Customizable edge fading
Performance: Built-in intersection observer

Key Differences

Vue Implementation:

Uses Vue 3 Composition API
Leverages Vue's reactivity system
Template-based rendering with slots

React Implementation:

Uses React hooks and [[Framer Motion|https://framer.com/motion]]
Imperative ref-based DOM manipulation
JSX with children cloning

Both versions provide smooth, performant marquee animations perfect for modern web applications! 🚀

Credits

[[Motion|https://motion.dev]]
[[Framer|https://framer.com]]

Tresjs + Vue - Holographic Sticker

Pedro Martins — Sun, 01 Sep 2024 00:00:00 GMT

import DemoVue from "./demo.vue"; import DemoReact from "./demo.tsx";

Recently I saw a cool holographic sticker effect on Twitter made by Baptiste Adrien, and I decided to take a stab at replicating it using Vue and TresJS. It turned out to be actually harder than I thought, but I'm happy with the results so far.

One of the things that still bugs me is that the React community has way more active contributors and libraries for ThreeJS, while Vue is still catching up. I tried reaching out to the [[TresJS|https://tresjs.org]] Discord for help to see if I could find my way around it, but didn't have any luck.

One of the challenges of this effect is the MeshTransmissionMaterial, which is not available in TresJS. So I had to use the MeshPhysicalMaterial from [[pmndrs/drei-vanilla|https://github.com/pmndrs/drei-vanilla]] and try to achieve the same effect using the available materials. But not everything is lost - TresJS provides a good abstraction around ThreeJS, and I could get a result closer to the React version.

The MeshTransmissionMaterial makes the base mesh transparent so it can reflect the background and items inside it, creating the desired effect. With little knowledge about shaders and 3D, this was indeed a fun journey to learn more about it.

Vue + TresJS

The following demo uses TresJS + Vue. Notice that the badge absorbs way more light than the React version - I'm still unsure why.

Vue implementation

But let's see the actual code! Here is the main scene for the Vue version.

<script setup lang="ts">
import { OrbitControls, Environment, useGLTF } from "@tresjs/cientos";
import { TresCanvas } from "@tresjs/core";
import Stickers from "./sticker.vue";
import MeshTransmissionMaterial from "./material.vue";
const { nodes } = await useGLTF("/assets/three-model.glb");
</script>
<template>
  <div class="relative size-[300px] lg:size-[600px]">
    <TresCanvas style="width: 100%; height: 100%" :alpha="true" :antialias="true" power-preference="high-performance"
      :shadows="true">
      <suspense>
        <TresMesh :geometry="nodes.Object_4.geometry" :rotation="[Math.PI / 2, 0, 0]" :cast-shadow="true"
          :receive-shadow="true">
          <MeshTransmissionMaterial />
        </TresMesh>
      </suspense>

      <suspense>
        <stickers />
      </suspense>

      <TresAmbientLight :intensity="1.5" />
      <TresPerspectiveCamera visible :position="[0, 0, 6]" :fov="45" />
      <OrbitControls :target="[0, 0, 0]" />
      <suspense>
        <Environment :files="'/assets/three-env.hdr'" :blur="0" :background="false" />
      </suspense>
    </TresCanvas>
  </div>
</template>

Here you can find the stickers inside the main scene:

<script setup lang="ts">
  import { useTexture } from "@tresjs/core";
  import { DoubleSide } from "three";
  const texture = await useTexture(["/assets/three-sticker.png"]);
</script>
<template>
  <suspense>
    <TresMesh>
      <TresPlaneGeometry />
      <TresMeshPhysicalMaterial :map="texture" :transparent="true" :clearcoat="1" :roughness="1" :metalness="0.8" :side="DoubleSide" />
    </TresMesh>
  </suspense>
</template>

And here's the Transmission Material - a bit messy and buggy. If you're reading this and have a better solution, please let's get in touch! :p

<script setup lang="ts">
import { shallowRef, onMounted, nextTick } from "vue";
import { MeshTransmissionMaterial, MeshDiscardMaterial } from "@pmndrs/vanilla";
import { useFBO } from "@tresjs/cientos";
import { useRenderLoop, useTresContext } from "@tresjs/core";
import { BackSide, DoubleSide } from "three";
import type { TresObject } from "@tresjs/core";
import type { Camera, Texture, WebGLRenderTarget } from "three";
import type { Ref } from "vue";

const MeshTransmissionMaterialClass = shallowRef();
const { extend, scene, renderer, camera } = useTresContext();
const parent = shallowRef<TresObject>();
const backside = true;
const backsideThickness = 0;
const thickness = 0;
const backsideEnvMapIntensity = 0;
const fboResolution = 1500;

extend({ MeshTransmissionMaterial });

/**
 * Finds the parent mesh using the specified material UUID.
 *
 * @param {THREE.Scene} scene - The Three.js scene to search.
 * @param {string} materialUuid - The UUID of the material.
 * @returns {THREE.Mesh | undefined} - The mesh using the material, or undefined if not found.
 */
function findMeshByMaterialUuid(scene: TresObject, materialUuid: string): TresObject {
  let foundMesh;

  scene.traverse((object: TresObject) => {
    if (object.isMesh && object.material && object.material.uuid === materialUuid) {
      foundMesh = object;
    }
  });

  return foundMesh as unknown as TresObject;
}

const discardMaterial = new MeshDiscardMaterial();

const { onLoop } = useRenderLoop();

onMounted(async () => {
  await nextTick();
  parent.value = findMeshByMaterialUuid(scene.value as unknown as TresObject, MeshTransmissionMaterialClass.value.uuid);
});

const fboBack = useFBO({
  width: fboResolution,
  height: fboResolution,
}) as unknown as Ref<WebGLRenderTarget<Texture>>;
const fboMain = useFBO({
  width: fboResolution,
  height: fboResolution,
}) as unknown as Ref<WebGLRenderTarget<Texture>>;

let oldBg;
let oldEnvMapIntensity;
let oldTone;

onLoop(({ elapsed }) => {
  MeshTransmissionMaterialClass.value.time = elapsed;

  if (MeshTransmissionMaterialClass.value.buffer === fboMain.value.texture) {
    if (parent.value) {
      // Save defaults
      oldTone = renderer.value.toneMapping;
      oldBg = scene.value.background;
      oldEnvMapIntensity = MeshTransmissionMaterialClass.value.envMapIntensity;

      parent.value.material = discardMaterial;

      if (backside) {
        // Render into the backside buffer
        renderer.value.setRenderTarget(fboBack.value);
        renderer.value.render(scene.value, camera.value as Camera);
        // And now prepare the material for the main render using the backside buffer
        parent.value.material = MeshTransmissionMaterialClass.value;
        parent.value.material.thickness = backsideThickness;
        parent.value.material.side = BackSide;
        parent.value.material.envMapIntensity = backsideEnvMapIntensity;
      }

      // Render into the main buffer
      renderer.value.setRenderTarget(fboMain.value);
      renderer.value.render(scene.value, camera.value as Camera);

      parent.value.material = MeshTransmissionMaterialClass.value;
      parent.value.material.thickness = thickness;
      parent.value.material.side = DoubleSide;
      // TODO: For some reason this makes the material really shinny, and i dont know why.
      // parent.value.material.buffer = fboMain.value.texture
      parent.value.material.envMapIntensity = oldEnvMapIntensity;

      // Set old state back
      scene.value.background = oldBg;
      renderer.value.setRenderTarget(null);
      renderer.value.toneMapping = oldTone;
    }
  }
});

defineExpose({
  root: MeshTransmissionMaterialClass,
  constructor: MeshTransmissionMaterial,
});
</script>

<template>
  <TresMeshTransmissionMaterial ref="MeshTransmissionMaterialClass" :buffer="fboMain.texture" :transmission="0"
    :_transmission="1" :anisotropic-blur="0.1" :thickness="0" :side="DoubleSide" />
</template>

React Three Fiber Implementation

And here you can find the same demo but with React Three Fiber. While the Vue implementation looks really close to this one, I cannot seem to get the same results. Maybe I'm missing some configuration, or it's just the way React Three Fiber handles the materials and defaults.

import { Environment, MeshTransmissionMaterial, OrbitControls, useGLTF, useTexture } from '@react-three/drei'
import { Canvas } from '@react-three/fiber'
import { DoubleSide } from 'three'

const Stickers = ({ texturePath }: { texturePath: string }) => {
  const texture = useTexture(texturePath)
  return (
    <>
      <mesh>
        <planeGeometry />
        <meshPhysicalMaterial
          map={texture}
          transparent
          clearcoat={1}
          roughness={0}
          side={DoubleSide}
        />
      </mesh>
    </>
  )
}

export interface SceneProps {
  modelPath: string
  texturePath: string
}

export const Scene = ({ modelPath, texturePath }: SceneProps) => {
  const { nodes } = useGLTF(modelPath)

  return (
    <div className="relative size-[300px] lg:size-[600px]">
      <Canvas
        shadows
        camera={{ position: [0, 0, 6], fov: 45 }}
      >
        <OrbitControls
          target={[0, 0, 0]}
        />
        <group dispose={null}>
          <mesh
            castShadow
            receiveShadow
            geometry={nodes.Object_4.geometry}
            rotation={[Math.PI / 2, 0, 0]}
          >
            <MeshTransmissionMaterial />
          </mesh>
        </group>

        <Stickers texturePath={texturePath} />

        <ambientLight intensity={2} />
        <Environment preset="city" blur={0} />
      </Canvas>
    </div>
  )
}

Once again, such a nice challenge and learning experience! I hope you enjoyed this post, and if you have any suggestions or tips, please let me know! All credits to Baptiste Adrien and Vercel for the amazing idea!

Links

[[Hybridly|https://hybridly.dev/]]
[[TresJS|https://docs.tresjs.org]]
[[Vue|https://vuejs.org]]
[[Three.js|https://threejs.org]]
[[React Three Fiber|https://docs.pmnd.rs/react-three-fiber]]
[[Baptiste Adrien|https://twitter.com/shinework/status/1775922778631245998]]
[[pmndrs/drei-vanilla|https://github.com/pmndrs/drei-vanilla]]

Speed up any WordPress site in 6 easy steps

Pedro Martins — Sun, 21 Jul 2024 00:00:00 GMT

[[WordPress|https://wordpress.org]] is an amazing tool that has powered millions of websites worldwide for years.

When building a WordPress website for yourself or a client, it's important to understand that WordPress was initially created for blogging! Everything else that adds extra features to the WordPress core comes in the format of "plugins" - small collections of PHP, CSS, and JavaScript files that integrate into your website. But if you're a bit of a geek, you probably already know all this, so let's move forward on how you can optimize your WordPress website using 6 essential techniques.

1 — Cloudflare 🚒

The first step everyone should be using is [[Cloudflare|https://cloudflare.com]]! Cloudflare is a DNS manager and CDN that brings many useful features that people aren't aware of. When creating websites for clients or myself, I always make sure Cloudflare is a requirement!

Here we'll introduce some basic settings you should enable and configure on the Cloudflare website to improve your WordPress website.

Cloudflare offers 3 different ways of SSL configuration. You should always make sure your hosting/VPS provider gives you at least LetsEncrypt free SSL certificates (if not, you should switch ASAP! [[Laravel Forge|https://forge.laravel.com]] might be a good choice to provision your VPS).

We'll provide screenshots of our standard configuration for WordPress setups:

1.1 — HTTPS / SSL ✅

In this step, make sure a certificate is already installed on your VPS/hosting. If you're unable to generate a certificate, temporarily turn off Cloudflare SSL and try again.

You can now move forward to the next tab:

1.2 — Firewall Rules 🔥

The second step on Cloudflare is to set up some basic firewall rules. This will keep most automated bots and brute-force attackers away from your website, ensuring these attacks don't affect your server's performance. The great advantage over using plugins like iTheme Security or Wordfence is that Cloudflare acts at the DNS level, so these attacks will never reach you because they're blocked at a higher level. Keep in mind that the rules we'll show here are basic - some websites may require more or fewer tweaks based on your needs.

At this point, you can also add more rules based on User Agent, URL, and so on. Some of the most common rules to keep attackers away:

User Agent contains: masscan/1.0, python-requests, WPScan
URL contains: backups, .bak, backup, .env, setup.php, phpmyadmin

Hit Save and you're ready to go! This will ensure that anyone (yes, even yourself) will need to solve a captcha when accessing any page that contains wp-admin or wp-login in the URL.

Why is this so effective? Because hackers often try to brute force those standard pages by default, so you'll save a lot of CPU and RAM by keeping them away!

2 — WP Rocket 🚀

I've tried many different plugins for WordPress caching, minification, and other performance optimizations - [[W3 Total Cache|https://wordpress.org/plugins/w3-total-cache/]], [[WP Super Cache|https://wordpress.org/plugins/wp-super-cache/]], and so on. But I always found trouble at some point: some required extensive configuration, breaking styles, JavaScript, and more.

I'm a big fan of "keep it simple," so here's where [[WP Rocket|https://wp-rocket.me]] shines! With a few clicks and toggles, you can get your website optimized without much technical knowledge, while being compatible with most themes without any issues. Some nice features we use in WP Rocket:

Cache / Separated mobile cache
Heartbeat Control (this really has a huge impact on CPU)
Lazy Load & Image Optimization
Merge / Minify JavaScript

Keep in mind that if you're using Cloudflare to minify your CSS/HTML/JavaScript, you don't really need to toggle the minify options - otherwise, you'll be doing the same optimization twice. At this point, I prefer to let Cloudflare handle it. You also need to be careful and add URLs you want to exclude from caching. By default, [[WooCommerce|https://woocommerce.com]] URLs are ignored, but others such as wish lists should be excluded manually.

3 — Redis, Redis & Redis! 🚤

Yes! You might think it's overkill, and yes it could be if your site doesn't have major traffic. But if your website runs WooCommerce and has a lot of products or heavy traffic, a nice add-on is [[Redis Object Cache|https://wordpress.org/plugins/redis-cache/]].

Redis Object Cache also has an enterprise version that claims to add even more performance (I haven't tried it myself). If you don't know what [[Redis|https://redis.io]] is, you can read more on Google. I won't go into detail here, but basically Redis is a fast object cache available for many languages and platforms. The port for PHP is called predis or phpredis, which should be available as a PHP extension on your hosting provider or via Composer.

When installed on WordPress through the WP Redis addon, it ensures that repeated queries and objects will be blazing fast as they're cached in memory, so you'll save some heavy queries to your MySQL database.

If all goes well, after some time you should see metrics like the following screenshot:

4 — Picking the Right Theme 🎨

There's no doubt that there are tons of themes available on the WordPress market. But this is a decision you should take very seriously - don't rush into picking the first theme that looks good to you. A bad theme (in terms of programming) can ruin not only your server but your user experience.

Often programmers take shortcuts and don't really look at their code quality. Most users don't understand how to evaluate a good theme when purchasing, so here we'll give you a few tips to find out if the theme is well-made and fast!

Look at HTML markup organization: Often bad markup and styling means the developer didn't put in much time, which likely means they don't care about what's under the hood.
Check CSS and JavaScript load: Inspect the code to see how much CSS and JavaScript are being included. The more JavaScript and CSS loaded, the more bloat and slower your site will be. Keep it clean with fewer dependencies.
Test responsive design: Try the theme in responsive mode or on your phone before you buy it. Often developers make themes look good on desktop, but the mobile experience could be really bad. It's always good to check how it looks on mobile - if you find little issues here and there, the developer might not be the best and didn't put much effort into the mobile-first concept. This means you should probably avoid it.
Check reviews: This is really important! If you visit [[ThemeForest|https://themeforest.net]], you can look at comments and reviews to see if other people who purchased the theme are having issues. If there are many comments/questions/problems, it usually means the theme is buggy - otherwise people wouldn't complain or call out the developer/agency so much.
Give preference to Elementor Page Builder: Why? Because it's the modern page editor for WordPress. [[WP Bakery|https://wpbakery.com]] is outdated (not officially, but in my opinion), while [[Elementor|https://elementor.com]] is a lightweight editor that provides flexibility when customizing your pages in the future. Visual Composer (formerly WP Bakery) gave me some really bad memories, so I don't recommend it personally.

5 — Find Good Hosting & Prefer a VPS 🏗️

With more bloat every day in WordPress Core and plugins around it, WordPress websites tend to be CPU-heavy. Often customers on shared hosting will struggle with very slow response times. The reason is that most shared hosting providers cap your CPU usage because the actual CPU is being used by thousands of other customers. For this reason, I'd avoid using WordPress (especially if paired with WooCommerce) on shared hosting if you want to keep your website blazing fast.

My recommendation goes for a small/medium VPS. You don't need to be a sysadmin to set up a VPS - you can use services like [[Laravel Forge|https://forge.laravel.com]] or [[Ploi.io|https://ploi.io]] to provision your VPS in a few minutes with very little effort. Keep in mind that VPS won't include any cPanel (unless you pay for it).

There are also some nice solutions for managed hosting dedicated to WordPress, such as:

[[WP Engine|https://wpengine.com]]
[[Kinsta|https://kinsta.com]]
[[SiteGround|https://www.siteground.com]]

6 — Battle with the Unknown & Debug 👻

Sometimes you may have done everything but you still don't know why your site is buggy or slow! This could be happening for many reasons that we'll describe below. Of course, we can't cover everything, but these tools will be really handy when it comes to debugging and tracking what could possibly be making your WordPress website slow!

Disable plugins one by one (Standard engineer fix! 😃) - keep testing if you notice any difference after disabling a certain plugin.
[[Query Monitor|https://wordpress.org/plugins/query-monitor/]]: This is one of the best plugins when it comes to debugging. It will tell you about queries running, slow queries, requests going out, and a lot of useful info. For instance, you can check what plugins are hitting your database really hard, causing your website to be slow. The Swiss Army knife for WordPress owners & maintainers.
[[Snitch|https://wordpress.org/plugins/snitch/]]: What I love personally about this plugin is you can keep track of what's going OUT from your WordPress website and block certain files/URLs. This is pretty nice because you can block constant plugins from slowing down your website by sending requests for updates every minute, blocking URLs if they're taking too long to respond, and block & track analytics being sent without your knowledge.
Verify file integrity with plugins like [[Wordfence|https://wordpress.org/plugins/wordfence/]]. This is really handy if you believe some of your WordPress core files were changed. Sometimes hackers hide deep in WordPress core files, so it's always good to run a quick check every few weeks.
Keep your plugins up-to-date. Often plugins bring performance improvements, so it's always good to keep them updated - just make sure it won't break anything and always perform a backup first!
Disable WP_CRON: The WordPress cron is triggered every time a user hits a page (when necessary). It's good practice to disable WP_CRON whenever possible and instead use Crontab available on most servers running cPanel or Linux. This ensures no extra workload is being called unnecessarily.

I hope you enjoyed this article - leave your comment and clap on! 👏

Building a Proxy Forwarder with 3Proxy, Squid & Laravel

Pedro Martins — Tue, 26 Mar 2024 00:00:00 GMT

Recently I needed to re-route, transform, and redirect proxies. The challenge was: how could I hide my real proxy behind another proxy by redirecting requests? Or could I set up a simple authentication method? In this article we'll cover:

Key Concepts & Terminology 📚

Inbound Port — Port that accepts incoming traffic, typically used on your device (ex: 192.168.111.2:8080)
Outbound Port — Port that redirects traffic to the destination server
Inbound IP/Domain — The IP or domain that receives connections from your device
Outbound IP/Domain — The destination IP or domain that receives the redirected traffic
Template Variables — Wildcards like {{outbound_port}} or {{xxxx}} that get replaced dynamically by scripts (PHP str_replace) with actual ports and IPs

Architecture Overview 🏗️

The diagram below shows how we mask the original proxy by creating a forwarding proxy that redirects traffic to the real proxy server.

Squid Proxy Setup 🦑

What is Squid?

[[Squid|https://www.squid-cache.org]] is one of the most widely used and reliable proxy solutions. It provides proxying, caching, authentication, user groups, and more. I didn't have time to explore all features, but at least it's not made by Russians! 😄 (joking of course).

Installation Guide: Learn how to install Squid here

Documentation for Squid can be sparse online. What I do know is that Squid relies on a single configuration file:

Squid Configuration Template 📝

Here's a sample Squid configuration file showing how to set up a proxy. You can find more about the configuration here.

The key difference is this template uses placeholders that [[Laravel|https://laravel.com]] (or any language) can replace dynamically:

header_replace Accept-Encoding gzip
auth_param basic program /usr/lib/squid/basic_ncsa_auth /etc/squid/passwd
auth_param basic credentialsttl 999 minutes
auth_param basic casesensitive on
auth_param basic realm easyshit
acl ncsa proxy_auth REQUIRED
follow_x_forwarded_for deny all
forwarded_for delete
via off

# Proxy Redirect Line
{{lines}}

# Squid Default Config
acl SSL_ports port 443
acl Safe_ports port 80		# http
acl Safe_ports port 21		# ftp
acl Safe_ports port 443		# https
acl Safe_ports port 70		# gopher
acl Safe_ports port 210		# wais
acl Safe_ports port 1025-65535	# unregistered ports
acl Safe_ports port 280		# http-mgmt
acl Safe_ports port 488		# gss-http
acl Safe_ports port 591		# filemaker
acl Safe_ports port 777		# multiling http
acl CONNECT method CONNECT
http_access deny !Safe_ports
http_access deny CONNECT !SSL_ports
http_access allow localhost manager
http_access deny manager
http_access allow localhost
http_access allow ncsa
coredump_dir /var/spool/squid
refresh_pattern ^ftp:		1440	20%	10080
refresh_pattern ^gopher:	1440	0%	1440
refresh_pattern -i (/cgi-bin/|\?) 0	0%	0
refresh_pattern (Release|Packages(.gz)*)$      0       20%     2880
refresh_pattern .		0	20%	4320

Single Proxy Redirect Configuration

Here's the configuration for a single proxy redirect line:

# Authentication for User with Port {{inbound_port}} with Reference #{{reference}}
# The user is being routed to {{outgoing_ip}}:{{outgoing_port}}
{{permissions}}
http_port {{inbound_port}} name=port_{{inbound_port}}
acl port_{{inbound_port}}_acl myportname port_{{inbound_port}}
always_direct deny port_{{inbound_port}}_acl
never_direct allow port_{{inbound_port}}_acl
cache_peer {{outgoing_ip}} parent {{outgoing_port}} 0 no-query {{outgoing_auth}} name=proxy{{inbound_port}}
cache_peer_access proxy{{inbound_port}} allow port_{{inbound_port}}_acl
cache_peer_access proxy{{inbound_port}} deny all
http_access allow localhost auth

More information can be found on the [[Squid Documentation|http://www.squid-cache.org/Doc/]] page, but I found it confusing, so I searched extensively to get this proper config. Thanks also to some friends in the proxy business who lent me a hand 🙂.

Note: This configuration uses wildcards that will be replaced dynamically.

3Proxy Setup ⚙️

How 3Proxy Works

Unlike Squid, [[3proxy|https://github.com/z3APA3A/3proxy]] runs as a simple bash process that serves as our connection listener. A process runs on the machine as the connection listener. When we no longer need it, we simply kill the process and the proxy/routing stops - this reduces management overhead significantly.

The examples below show:

HTTP to HTTP proxy
HTTP to SOCKS5 proxy

Remember: wildcards in {{}} format get replaced with actual values via PHP scripts.

Installation Guide: Learn how to install 3proxy here

Simply run/kill this process to start/stop proxy routing.

3Proxy Configuration Template 📄

#!/bin/bash

# Subscription: {{ $SUBSCRIPTION_REFERENCE }}
# Proxy: {{ $PROXY_REFERENCE }}
# Allocated port: {{ $ALLOCATED_PORT }}
# The user is being routed to {{ $ORIGINAL_HOST }}:{{ $ORIGINAL_PORT }}

daemon
pidfile /var/run/{{ $PID }}.pid
nserver {{ $PROXY3_DNS_1 }}
nserver {{ $PROXY3_DNS_2 }}
nscache 65536
nscache6 65536
timeouts 1 5 30 60 180 1800 15 60
deny * * 127.0.0.1,192.168.1.1
# Admin for this proxy, should be common for all users
auth strong
users {{ $PROXY3_ADMIN_USERNAME }}:CL:{{ $PROXY3_ADMIN_PASSWORD }}
allow {{ $PROXY3_ADMIN_USERNAME }} * * *
flush

# Build the user line
maxconn {{ $MAX_CONNECTIONS }}
auth strong
users {{ $ALLOCATED_USERNAME }}:CL:{{ $ALLOCATED_PASSWORD }}
allow {{ $ALLOCATED_USERNAME }} * {{ $ALLOWED_DOMAINS }} 80-88,8080-8088,443 HTTP,HTTPS
parent 1000 {{ $ORIGINAL_PROTOCOL }} {{ $ORIGINAL_HOST }} {{ $ORIGINAL_PORT }} {{ $ORIGINAL_USERNAME }} {{ $ORIGINAL_PASSWORD }}
proxy -4 -olSO_REUSEADDR,SO_REUSEPORT -ocTCP_TIMESTAMPS,TCP_NODELAY -osTCP_NODELAY -n -a -p{{ $ALLOCATED_PORT }}
flush

Auto-Start Script 🔄

A small bash script can automate the process startup. The {{proxy3_bin}} is the path to your 3proxy binary and the {{proxy_config}} is the path to your .conf file (mentioned above). We also call Laravel Artisan command to verify the proxy is still valid. Our backend handles the necessary commands to delete config files and terminate processes.

#!/bin/sh
if ps -aux | grep "3[p]roxy" | grep "{{proxy3_bin_grep}} {{proxy3_config}}" > /dev/null 2>&1;
then
echo 'Running {{reference}}';
else
{{proxy3_bin}} {{proxy3_config}} &
fi
/usr/bin/php -f {{artisan}} check:order {{reference}}

Laravel Helper Class 🔧

Squid & 3Proxy Helper

The following PHP Class is just a helper I've created to automatically update/generate config files on demand (from database in this case). This doesn't work out of the box and requires additional configuration. I'm providing just a proof of concept, not the complete code.


/**
  * Replaces the keys and generates the user rules
  *
  * @return mixed
  * @throws \Illuminate\Contracts\Filesystem\FileNotFoundException
  */
private function getProxyConfig(): string
{
    $keys = [
        # Inbound
        '{{inbound_port}}' => $this->getInbound()->getPort(),
        '{{inbound_username}}' => $this->getInbound()->getAuthUsername(),
        '{{inbound_password}}' => $this->getInbound()->getAuthPassword(),
        '{{inbound_allowed_urls}}' => '*', // Comma delimited instagram.com,*.instagram.com
        # Outbound
        '{{outgoing_ip}}' => $this->getOutbound()->getIpOrHostName(),
        '{{outgoing_port}}' => $this->getOutbound()->getPort(),
        '{{outgoing_protocol}}' => $this->getOutbound()->getProtocol(),
        # Other
        '{{pid}}' => random_number(100000, 10000000),
        '{{max_connections}}' => 10000,
        '{{name_server_1}}' => config('app.proxy3-dns-server-2'),
        '{{name_server_2}}' => config('app.proxy3-dns-server-2'),
        '{{reference}}' => $this->reference,
        '{{admin_username}}' => config('app.proxy3-admin-username'),
        '{{admin_password}}' => config('app.proxy3-admin-password'),
    ];

    # Check if there is auth
    if ($this->outbound->hasAuthentication() && $this->outbound->getAuth() !== null) {
        $keys['{{outgoing_username}}'] = $this->outbound->getAuthUsername();
        $keys['{{outgoing_password}}'] = $this->outbound->getAuthPassword();
    } else {
        $keys['{{outgoing_username}}'] = '';
        $keys['{{outgoing_password}}'] = '';
    }
    if($this->inbound->getProtocol() === Parser::PROTOCOL_SOCKS5){
        return replace($keys, self::getConfigTemplateSocks5());
    }
    return replace($keys, self::getConfigTemplate());
}

The Result 🎉

Here's a small example of an internal Laravel app we built to manage everything. Keep in mind that some code might NOT be optimized as this is a demo project for the sole purpose of testing 3proxy and squid. Feel free to enhance the database logic, helpers, and documentation. If you have any questions feel free to ask!

Conclusion 🎯

We've learned how to:

Use Squid & proxy config files (more or less), setup, and how it works
Build simple proxy redirecting using 3proxy from HTTP → HTTP and HTTP → SOCKS5
Automate all this logic using a back-end (Laravel & PHP)

Proxies can be used for numerous reasons such as: keeping your connection safe, bypassing blocked websites in your country, crawling, etc! If you liked this article please clap or comment below!

Vanilla Components ®

Pedro Martins — Fri, 01 Sep 2023 00:00:00 GMT

A lightweight, flexible & customizable UI library for Vue 3, styled with Tailwind CSS.

INIDGIT ®

Pedro Martins — Thu, 01 Dec 2022 00:00:00 GMT

A 360º agency specialized in Web applications, Websites, Marketing & Digital Strategy

Pokemon Accounts ®

Pedro Martins — Sat, 01 Jan 2022 00:00:00 GMT

A Marketplace to buy & sell Pokémon GO accounts, with more than 10,000 users.

IGERSLIKE ®

Pedro Martins — Wed, 20 Jan 2021 00:00:00 GMT

A full-featured plataform for Social Media Automation & Viral Marketing Services.

Pedro Martins

The 10x Trap: Why AI Made Me Work More, Not Less

1. Introduction

2. The Parallelism Trap 🪤

3. The Review Bottleneck 🔍

4. The Trust Gap 🤖

5. Wrap Up 🧘

Links

Inside Mobile Apps - The Reverse Engineering Rabbit Hole

1. Introduction

2. Glossary & Terminology

3. iOS vs Android: Two Very Different Worlds

3.1. Root (Android)

3.2. Jailbreak (iOS)

4. The Toolkit: JEB, Frida & Friends

4.1. JEB & IDA Pro

4.2. Frida

5. The Cat and Mouse Game

5.1. Root & Jailbreak Detection

5.2. Frida Detection

6. Reading the Requests

7. Data Samples & Privacy Concerns

8. Conclusion

Links

Bookmarkjar ®

Prompt Book

i18n with TanStack Start: A Complete Guide 2026

1. Introduction 🌍

2. Requirements 📋

3. How frameworks handle locale prefixes 🛤️

4. Prefixing or not to prefix? 🤔

4.1 Always prefix all languages (/en/about, /es/about)

4.2 Never prefix (detect via cookies/headers)

4.3 No prefix for default, prefix for others (/about, /es/about)

5. Redirecting the user to the correct language 🔀

5.1 Redirect based on Accept-Language header

5.2 Redirect based on cookie (returning visitors)

5.3 No redirect, just show the content

5.4 Hybrid approach (recommended)

5.5 What about localStorage?

5.6 TL;DR - Quick comparison

6. TanStack Start i18n Integration 🔧

6.1 Why a Separate Package?

6.2 Why use-intl?

6.3 What About Paraglide?

6.4 The Shared Foundation

6.5 TanStack Router URL Rewriting

6.6 The Layout Route

6.7 Server Middleware

6.8 Client-Side Locale Detection

6.9 The Provider Setup

6.10 Type-Safe Localized Links

6.11 Adding a New Language

7. Wrapping Up 🎉

Browser Clutch

Twenty Years Building for the Web: From PHP's Simple Server Rendering to TypeScript's Modern Complexity

1. Introduction

2. PHP + Laravel Golden Age

3. The Rise of Javascript

4. Frontend Complexity with Javascript

5. Node.js Enters the Chat

5.1 The SSR Complexity

6. Laravel Inertia JS - Bridging the Gap

7. TypeScript - JavaScript That Scales

8. Full Stack Laravel + Typescript = The perfect combo?

9. FullStack Typescript

10. PHP ( Laravel ) vs Javascript/Typescript

10.1 PHP ( Laravel ) Pros ✅

10.2 PHP ( Laravel ) Cons ❌

10.3 Javascript/Typescript Pros ✅

10.4 Javascript/Typescript Cons ❌

11. Conclusion

12. Credits & Links

The restless mind of thinkers, how obsession, curiosity, and chaos can be a gift

1. Introduction

2. The Storm

3. Learning - The Real Oxygen

4. AI - Infinite Learning

5. Stopping = Weakness?

6. Burnout or Laziness?

4.1 Always prefix all languages (`/en/about`, `/es/about`)

4.3 No prefix for default, prefix for others (`/about`, `/es/about`)

5.1 Redirect based on `Accept-Language` header

6.2 Why `use-intl`?