I've been thinking about this a lot recently, partly because we went through the exercise of hardening our own repos at Velopack, and partly because some of the attacks that surfaced recently are genuinely terrifying. I wanted to talk about what's been happening, why it matters, and what you can actually do about it.

Some attacks that should keep you up at night​

The one that set the tone was XZ Utils in early 2024. A threat actor spent two and a half years building trust as a contributor to a widely used Linux compression library. They submitted helpful patches, did code reviews, gradually became a co-maintainer. Then they slipped a backdoor into the build process, hidden inside obfuscated test fixture files. It scored a perfect 10.0 CVSS and would have given them remote code execution on basically any Linux server running OpenSSH. The only reason it got caught was because a Microsoft engineer noticed his SSH connections were using slightly more CPU than usual. Two years of social engineering, and the detection mechanism was one person noticing a performance blip. No automated tool, no CI check, no scanner caught it. Just luck.

The Axios compromise in early 2026 was a different kind of wake-up call. Axios gets around 70 million downloads a week on npm. A North Korean state actor compromised the lead maintainer's PC through social engineering, stole their npm credentials, and published trojanized versions that installed a RAT on anyone who updated. The malicious versions were live for about three hours, and because of how npm version ranges work (^1.14.0), CI pipelines across the ecosystem automatically pulled in the compromised version.

Shai-Hulud in late 2025 was the first self-replicating npm worm. It started with phishing emails that looked like they came from npm, asking developers to "update" their MFA settings. Once they had a developer's token, the worm would automatically find every other package that developer maintained, inject malicious postinstall scripts, and publish new versions. No human in the loop. It infected around 200 packages before it was contained, and CISA had to put out an advisory.

The tj-actions GitHub Actions compromise in March 2025 hit 23,000+ repositories by poisoning a widely-used action's version tags so they pointed to malicious code. The Ultralytics (YOLO) PyPI compromise happened through a GitHub Actions script injection vulnerability, and the malicious code only existed in the PyPI-distributed package, not in the source repo. The Polyfill.io takeover was someone buying the domain and CDN, then injecting malicious redirects into 100,000+ websites.

Every major package ecosystem has been hit. npm, PyPI, crates.io, NuGet, Go modules, none of them are immune.

How these attacks actually work​

If you look at the patterns, a few attack vectors come up repeatedly.

Maintainer account compromise is the most dangerous. Phishing for credentials, social engineering, malware on a developer's machine. The attacker publishes from a trusted account to a trusted package. No typo in the name, no unfamiliar publisher, it looks completely legitimate. The Axios attack is the textbook example.

Typosquatting and dependency confusion are the most common by volume. Publishing requets instead of requests, or registering a public package with the same name as a company's internal package. Sonatype has logged over a million malicious packages across registries, and the vast majority are this type. Each individual one has limited impact, but at scale it adds up.

CI/CD pipeline attacks are the force multiplier. If you can compromise a build pipeline, every artifact it produces is tainted, and CI systems are implicitly trusted. The Ultralytics attack stole PyPI upload tokens through a GitHub Actions vulnerability. The LiteLLM compromise in 2026 happened because their CI pipeline used a compromised security scanner, which exfiltrated their PyPI publishing tokens.

Build script abuse is easy to overlook. npm's postinstall, Cargo's build.rs, Python's setup.py all execute arbitrary code with full system privileges at install time, before any runtime sandboxing kicks in. Only about 2% of npm packages actually need postinstall scripts, but the mechanism is there for all of them.

Developer tooling and IDE extensions are a growing attack surface, and one that scales with team size. Every developer on your team who installs a VS Code extension is a potential entry point. In May 2026, the popular Nx Console extension (2.2 million installs, Verified Publisher badge) was compromised after a contributor's GitHub token was stolen through a separate supply chain attack on TanStack. The attacker pushed a malicious version that was live for just 18 minutes, but auto-updates pushed it to around 6,000 installs. One of those installs was on a GitHub employee's machine, and the stolen credentials were used to exfiltrate 3,800 internal GitHub repositories. Separately, two AI coding assistant extensions marketed as ChatGPT tools were found exfiltrating every source file developers opened back to servers in China, with a combined 1.5 million installs. The more developers you have, the more IDE extensions, browser tools, and local utilities are in play, and each one is a trust boundary you're probably not auditing.

The through-line here is that most of these attacks don't require finding a vulnerability in code. They exploit trust in maintainers, registries, CI systems, and the build process itself.

What we did about it​

We recently went through our repos at Velopack and tightened things up. Here's what that looked like in practice, and what I'd suggest if you haven't done this yet.

Lock your dependencies​

Commit your lockfiles (Cargo.lock, package-lock.json, etc.) and use them in CI. For Rust, that means adding --locked to every cargo build, cargo test, and cargo clippy command in your workflows. This ensures CI uses the exact versions you tested locally and fails if the lockfile is out of date. Without this, a compromised dependency could publish a new semver-compatible version and your CI would silently pick it up.

For GitHub Actions, pin actions to full commit SHAs instead of version tags. The tj-actions attack worked because tags are mutable. The attacker moved the tag to point at malicious code. A commit SHA can't be changed after the fact.

Run dependency audits in CI​

We added cargo-deny to our CI pipeline, which checks four things on every build:

• Advisories: does any dependency have a known vulnerability in the RustSec database?
• Licenses: is every dependency using an approved license? (we maintain an explicit allowlist)
• Bans: are there any wildcard version requirements that could pull in anything?
• Sources: is every dependency coming from an expected registry?

The npm equivalent would be something like npm audit or Socket. The point is to automate this so it runs on every PR, not just when someone remembers to check.

Delay non-security updates​

We configured Renovate to wait 14 days before proposing updates for non-security patches. Most malicious package versions get caught and pulled within 24-72 hours. A two-week buffer means you're almost never the first to discover a compromised version.

Security vulnerabilities bypass this delay entirely. We set those to create PRs immediately with a security label so they don't get lost.

Restrict CI permissions​

By default, GitHub Actions tokens have write access to your repository. That's more than most workflows need. Set permissions: contents: read at the workflow level and only escalate where necessary. If a compromised action runs in your workflow, the blast radius is much smaller when the token can only read.

Other things worth doing​

Use OIDC-based "trusted publishers" for package registries if they support it (PyPI and npm both do now). Your CI publishes packages using short-lived tokens tied to your specific workflow, instead of long-lived API keys that can be stolen and used from anywhere.

Disable postinstall scripts where possible. npm config set ignore-scripts true or use pnpm, then explicitly whitelist the packages that actually need them. This eliminates one of the most common payload delivery mechanisms.

Enforce MFA on all registry accounts, preferably hardware keys. The Shai-Hulud phishing attack used a transparent proxy that forwarded credentials to the real npm site, TOTP codes included. Hardware security keys (FIDO2/WebAuthn) would have blocked it because they're bound to the actual domain.

Evaluate new dependencies before adding them. Check the OpenSSF Scorecard, look at the maintainer's activity, consider whether you actually need the package or if you're pulling in a library for something you could write in 20 lines. Every dependency is a trust relationship. Fewer dependencies means fewer things that can go wrong.

Audit your team's IDE extensions. After the Nx Console and MaliciousCorgi incidents, this should be on every organization's radar. Consider maintaining an approved list of extensions, or at minimum disabling auto-updates for extensions so compromised versions don't silently roll out across your team.

The uncomfortable truth​

There's no silver bullet. The XZ Utils attack bypassed everything. It was a trusted maintainer with legitimate access making changes that passed review. No lockfile, no scanner, no audit tool would have caught it.

What we can do is raise the bar. The vast majority of supply chain attacks are far less sophisticated than XZ. They're someone publishing ax1os and hoping a developer fat-fingers their install command, or spraying phishing emails at maintainers. The defenses I've listed here handle most of those.

Most of this stuff takes an afternoon to set up. Adding --locked to your CI commands is a one-line change. Setting up cargo-deny or npm audit is maybe an hour of work. Configuring a release age delay on Renovate is a config file change. The cost is low and the protection is real.

If you maintain open source, or really any project with dependencies, take an afternoon and go through this list. Your future self will thank you when the next big supply chain incident drops and your build pipeline isn't blindly trusting everything the internet hands it.

What's the big deal anyway?​

There is a flaw underpinning many React applications, called "render/fetch chains" or sometimes "waterfall loading". What this refers to is the phenomenon where you end up with a series of ajax requests to load required data, one after another with useEffect instead of loading data in parallel The reason this happens is data fetching is tightly coupled to component rendering.

Image a scenario where a parent component needs to fetch before rendering (perhaps showing a loading spinner in the meantime). Once it's loaded it's data it renders itself and any children. Now imagine a child also needs to fetch some data. It can only get started after the parent has fully loaded since the data fetch happens once the child renders. Here's an example:

import React, { useEffect, useState } from 'react';

// Simulating a data fetching function which takes 3s to complete
const fetchData = () => new Promise(resolve => setTimeout(() => resolve("Data loaded"), 3000));

function ParentComponent() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchData().then(data => {
      setData(data);
      setLoading(false);
    });
  }, []);

  if (loading) return (<p>Loading...</p>);

  return (
    <div>
        <h1>Parent Component</h1>
        <p>{data}</p>
        <ChildComponent />
    </div>
  );
}

function ChildComponent() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchData().then(data => {
      setData(data);
      setLoading(false);
    });
  }, []);

  if (loading) return (<p>Loading...</p>);

  return (
    <div>
        <h2>Child Component</h2>
        <p>{data}</p>
    </div>
  );
}

export default ParentComponent;

This is a super common pattern. It's also a very bad pattern. The larger your app becomes, the slower things get as more component hierarchy gets added.

Enter the Router Loader​

Libraries such as react-router (version 6.4 and above) and @tanstack/router have introduced significant improvements by adding "Data Loading" as a core feature. These router libraries manage streamline data fetching directly within the routing layer. This approach leverages the router's awareness of the component hierarchy and lifecycle to optimally schedule and parallelize data fetching tasks before the components even begin rendering.

Benefits of Using a Data Router/Loader​

Parallel Data Fetching​

By initiating all required data fetching at the router level, these libraries can load data in parallel rather than sequentially. This significantly reduces the total time waiting for data across nested routes, avoiding the "waterfall" effect seen in traditional React data fetching patterns.

Decoupling Data Fetching from UI Rendering​

This architecture separates the concerns of data fetching and UI rendering. Components are responsible solely for presenting data and handling user interactions, not for fetching the data they display. This separation makes the components more reusable and easier to manage.

Improved User Experience​

Loading data before rendering the component tree means that users see a complete UI without awkward loading states popping in sequentially. This can significantly improve the perceived performance of your application.

Simplified Component Logic​

Components no longer need to manage their own data fetching logic with useEffect and state. The router loader handles all the asynchronous logic, simplifying your React components and making them cleaner and more focused on their primary function—rendering UI.

Potential Drawbacks​

While the benefits are considerable, there are a few trade-offs to consider:

Increased Complexity in the Router​

The logic for data fetching moves into the routing configuration, which can become complex if not managed carefully. This might increase the learning curve or the amount of boilerplate code, especially in large applications with many routes and data dependencies.

Less Flexibility for Dynamic Fetching Conditions​

Since data fetching is configured per-route, dynamically changing fetching logic based on component state or props can be more cumbersome. You might need additional patterns or libraries to handle more complex, dynamic scenarios.

Code Sample​

I'll take our code sample from earlier and update it for loaders:

import React from 'react';
import {
  BrowserRouter as Router,
  Route,
  Routes,
  Outlet,
  useLoaderData
} from 'react-router-dom';

// Simulating a data fetching function which takes 3s to complete
const fetchData = () => new Promise(resolve => setTimeout(() => resolve("Data loaded"), 3000));

// Data loader function for the parent component
async function parentLoader() {
  const data = await fetchData();
  return { parentData: data };
}

// Data loader function for the child component
async function childLoader() {
  const data = await fetchData();
  return { childData: data };
}

function ParentComponent() {
  const { parentData } = useLoaderData();
  return (
    <div>
      <h1>Parent Component</h1>
      <p>{parentData}</p>
      <Outlet />  {/* Child components will be rendered here */}
    </div>
  );
}

function ChildComponent() {
  const { childData } = useLoaderData();
  return (
    <div>
      <h2>Child Component</h2>
      <p>{childData}</p>
    </div>
  );
}

const router = createBrowserRouter([
  {
    path: "/",
    element: <ParentComponent />,
    loader: parentLoader,
    children: [
      {
        path: "child",
        element: <ChildComponent />,
        loader: childLoader,
      },
    ],
  },
]);

function App() {
  return (
    <RouterProvider router={router} />
  );
}

export default App;

In the above sample we can see that the data loading is defined in our router from the beginning - so when the user navigates to /child, react-router can get going fetching both the parent and child data simultaneously. The UX here can be further enhanced (and easily) by using deferred data and React Suspense enabling you to show placeholder UI instead of generic spinners, but I'll save that for another topic.

react-router vs. @tanstack/router - Which to use?​

It's no question that react-router used to be the king of React SPA navigation before it was acquired by Remix in 2024. Since the acquisition though, it's clear that drastic changes are being made to fit it in better to their commercial offering and community feedback is being largely ignored. Also, it's missing out on several key features.

react-router​

• Pro: Has a huge legacy and is more widely used
• Con: Limited TypeScript support (more runtime errors)
• Con: Core logic is not exported, making it very hard to integrate with non-standard use-cases
• Con: New versions often have rewrite-inducing major changes
• Con: No ability to customize pre/loader behaviors (eg. timeouts)
• Con: In order to make use of loaders properly, you need to switch from traditional Route components to a data router which many people will not be familiar with.
• Con: Documentation is atrocious and unsearchable.

@tanstack/router​

• Pro: First class TypeScript support in all aspects
• Pro: Smaller / simpler code base
• Pro: Supports code-based routing (like react-router) but also supports auto-generated routing based on file names.
• Pro: API is very clean and mostly exported, resulting in a very extensible and customisable solution
• Pro: Very customizable data loading behaviors, with fully deferred, partially with timeouts, etc
• Pro: Intent based Preloading (eg. user hovering on a link) allows you to speed up data loading even further
• Pro: Documented integrations with @tanstack/query (formerly react-query) which is already widely used.
• Con: @tanstack/router is the new kid on the block.

I might be biased, but I think it's clear from the list above that @tanstack/router is the winner for me.

Conclusion​

Adopting a Data Router/Loader can significantly enhance the structure and performance of large-scale React applications by optimizing data fetching strategies. While this approach introduces some complexities, the overall benefits in terms of performance gains and cleaner code generally outweigh these concerns. As with any architectural decision, it’s crucial to evaluate whether the specific benefits align with the needs and scale of your project.

Incorporating a Data Router/Loader could be a game changer for your React app, ensuring that data management is as efficient and unobtrusive as possible. As you refactor or start new projects, consider how leveraging these advanced routing capabilities might enhance both developer experience and your UX.

If you're only targeting .NET 6 and higher, you can stop reading here - because there's already great support in the framework via FileSystemInfo.LinkTarget, Directory.CreateSymbolicLink and other built-in methods.

If you need to target the Full .Net Framework, then read on...

If you just want the final code without the prologue, then click here.

Starting Point​

As I eluded to above, the addition of cross platform varients will simplify things for us on other operating systems, so I started by writing an API which delegates to those functions.

internal static class SymbolicLink
{
    public static void Create(string linkPath, string targetPath, bool overwrite = true)
    {
        linkPath = Path.GetFullPath(linkPath);
        targetPath = Path.GetFullPath(targetPath);

        if (!Directory.Exists(targetPath) && !File.Exists(targetPath)) {
            throw new IOException("Target path does not exist.");
        }

        if (Directory.Exists(linkPath) || File.Exists(linkPath)) {
            if (overwrite) {
                Utility.DeleteFileOrDirectoryHard(linkPath);
            } else {
                throw new IOException("Junction / symlink path already exists and overwrite parameter is false.");
            }
        }

        var finalTarget = relative
            ? GetRelativePath(Path.GetDirectoryName(linkPath)!, targetPath)
            : targetPath;

        if (Directory.Exists(targetPath)) {
            Directory.CreateSymbolicLink(linkPath, finalTarget);
        } else if (File.Exists(targetPath)) {
            File.CreateSymbolicLink(linkPath, finalTarget);
        } else {
            throw new IOException("Target path does not exist.");
        }
    }

    public static bool Exists(string linkPath)
    {
        return TryGetLinkFsi(linkPath, out var _);
    }

    public static void Delete(string linkPath)
    {
        var isLink = TryGetLinkFsi(linkPath, out var fsi);
        if (fsi != null && !isLink) {
            throw new IOException("Path is not a junction point.");
        } else {
            fsi?.Delete();
        }
    }

    public static string GetTarget(string linkPath)
    {
        if (TryGetLinkFsi(linkPath, out var fsi)) {
            return fsi.LinkTarget!;
        }
        throw new IOException("Path does not exist or is not a junction point / symlink.");
    }

    private static bool TryGetLinkFsi(string path, out FileSystemInfo fsi)
    {
        fsi = null!;
        if (Directory.Exists(path)) {
            fsi = new DirectoryInfo(path);
        } else if (File.Exists(path)) {
            fsi = new FileInfo(path);
        }

        return fsi != null && (fsi.Attributes & FileAttributes.ReparsePoint) != 0;
    }
}

Support for .Net Framework​

I cheated slightly with the implementation of the above API, because I copied the public API of the JunctionPoint.cs library by Jeff Brown on CodeProject, hoping to just copy it in to my project and conditionally compile in one or the other.

JunctionPoint.cs, was great, but unfortunately it only supports directory junctions and not file links. I set out to enhance this library as is, but things have moved on and there are higher level abstractions in Win32 these days, so I scrapped and moved on to something simpler:

    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
    private static extern bool CreateSymbolicLink(string lpSymlinkFileName, string lpTargetFileName, int dwFlags);

    [DllImport("Kernel32.dll", SetLastError = true, CharSet = CharSet.Auto)]
    private static extern uint GetFinalPathNameByHandle(IntPtr hFile, [MarshalAs(UnmanagedType.LPTStr)] StringBuilder lpszFilePath, uint cchFilePath, uint dwFlags);

The CreateSymbolicLink and GetFinalPathNameByHandle provide simple solutions which I could conditionally compile in on the full framework, for example:

if (Directory.Exists(targetPath)) {
#if NETFRAMEWORK
    if (!CreateSymbolicLink(linkPath, finalTarget, SYMBOLIC_LINK_FLAG_DIRECTORY | SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE))
        ThrowLastWin32Error("Unable to create junction point / symlink.");
#else
    Directory.CreateSymbolicLink(linkPath, finalTarget);
#endif
}

This is enough if all you need to do is support absolute paths.

Adding Relative Paths​

I was relatively happy with the simplicitly of the solution above, but since I was preserving symlinks within a self-contained application bundle, I needed support for relative paths, when creating and reading symlinks.

Unfortunately Path.GetRelativePath only exists on .NET, so we'll need a new implementation for that, which I stole from RT.Util - a project written my a friend of mine.

Also GetFinalPathNameByHandle resolves relative paths to absolute paths before it gets back to us, so we're going to have to switch back to using DeviceIoControl which I was hoping to avoid.

This function didn't turn out too complicated, but writing it involved a lot of searching on the topic, debugging, and so forth.

One of the things I got stuck on (without realising it) is that CreateFile is very picky when it comes to the flags passed in. You need FILE_FLAG_BACKUP_SEMANTICS and FILE_FLAG_OPEN_REPARSE_POINT.

private static string GetTargetWin32(string linkPath)
{
    // https://github.com/microsoft/BuildXL/blob/main/Public/Src/Utilities/Native/IO/Windows/FileSystem.Win.cs#L2711
    // http://blog.kalmbach-software.de/2008/02/28/howto-correctly-read-reparse-data-in-vista/
    // https://github.com/dotnet/runtime/blob/e5f0c361f5baea5e2b56e1776143d841b0cc6e6c/src/libraries/System.Private.CoreLib/src/System/IO/FileSystem.Windows.cs#L544
    SafeFileHandle handle = CreateFile(
        linkPath,
        dwDesiredAccess: 0,
        FileShare.ReadWrite | FileShare.Delete,
        lpSecurityAttributes: IntPtr.Zero,
        FileMode.Open,
        dwFlagsAndAttributes: EFileAttributes.BackupSemantics | EFileAttributes.OpenReparsePoint,
        hTemplateFile: IntPtr.Zero);

    if (Marshal.GetLastWin32Error() != 0)
        ThrowLastWin32Error("Unable to open reparse point.");

    int bufferSize = INITIAL_REPARSE_DATA_BUFFER_SIZE;
    int errorCode = ERROR_INSUFFICIENT_BUFFER;

    byte[] buffer = null!;
    while (errorCode == ERROR_MORE_DATA || errorCode == ERROR_INSUFFICIENT_BUFFER) {
        buffer = new byte[bufferSize];
        bool success = false;

        int bufferReturnedSize;
        success = DeviceIoControl(
            handle,
            FSCTL_GET_REPARSE_POINT,
            IntPtr.Zero,
            0,
            buffer,
            bufferSize,
            out bufferReturnedSize,
            IntPtr.Zero);

        bufferSize *= 2;
        errorCode = success ? 0 : Marshal.GetLastWin32Error();
    }

    if (errorCode != 0) {
        throw new Win32Exception(errorCode);
    }

    const uint PrintNameOffsetIndex = 12;
    const uint PrintNameLengthIndex = 14;
    const uint SubsNameOffsetIndex = 8;
    const uint SubsNameLengthIndex = 10;

    uint reparsePointTag = BitConverter.ToUInt32(buffer, 0);
    if (reparsePointTag != IO_REPARSE_TAG_SYMLINK && reparsePointTag != IO_REPARSE_TAG_MOUNT_POINT) {
        throw new NotSupportedException($"Reparse point tag {reparsePointTag:X} not supported");
    }

    uint pathBufferOffsetIndex = (uint) ((reparsePointTag == IO_REPARSE_TAG_SYMLINK) ? 20 : 16);

    int nameOffset = BitConverter.ToInt16(buffer, (int) PrintNameOffsetIndex);
    int nameLength = BitConverter.ToInt16(buffer, (int) PrintNameLengthIndex);
    string targetPath = Encoding.Unicode.GetString(buffer, (int) pathBufferOffsetIndex + nameOffset, nameLength);

    if (string.IsNullOrWhiteSpace(targetPath)) {
        nameOffset = BitConverter.ToInt16(buffer, (int) SubsNameOffsetIndex);
        nameLength = BitConverter.ToInt16(buffer, (int) SubsNameLengthIndex);
        targetPath = Encoding.Unicode.GetString(buffer, (int) pathBufferOffsetIndex + nameOffset, nameLength);
    }

    return targetPath;
}

Final Solution​

The final code works for .Net Framework, as well as NET 6.0 and above. It supports writing/reading both absolute or relative paths. The code is released as a part of Velopack, which is under the MIT license.

internal static class SymbolicLink
{
    /// <summary>
    /// Creates a symlink from the specified directory to the specified target directory.
    /// </summary>
    /// <param name="linkPath">The symlink path</param>
    /// <param name="targetPath">The target directory or file</param>
    /// <param name="overwrite">If true overwrites an existing reparse point or empty directory</param>
    /// <param name="relative">If true, stores a relative path from the link to the target, rather than an absolute path.</param>
    public static void Create(string linkPath, string targetPath, bool overwrite = true, bool relative = false)
    {
        linkPath = Path.GetFullPath(linkPath);
        targetPath = Path.GetFullPath(targetPath);

        if (!Directory.Exists(targetPath) && !File.Exists(targetPath)) {
            throw new IOException("Target path does not exist.");
        }

        if (Directory.Exists(linkPath) || File.Exists(linkPath)) {
            if (overwrite) {
                Utility.DeleteFileOrDirectoryHard(linkPath);
            } else {
                throw new IOException("Junction / symlink path already exists and overwrite parameter is false.");
            }
        }

        var finalTarget = relative
            ? GetRelativePath(Path.GetDirectoryName(linkPath)!, targetPath)
            : targetPath;

        if (Directory.Exists(targetPath)) {
#if NETFRAMEWORK
            if (!CreateSymbolicLink(linkPath, finalTarget, SYMBOLIC_LINK_FLAG_DIRECTORY | SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE))
                ThrowLastWin32Error("Unable to create junction point / symlink.");
#else
            Directory.CreateSymbolicLink(linkPath, finalTarget);
#endif
        } else if (File.Exists(targetPath)) {
#if NETFRAMEWORK
            if (!CreateSymbolicLink(linkPath, finalTarget, SYMBOLIC_LINK_FLAG_FILE | SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE))
                ThrowLastWin32Error("Unable to create junction point / symlink.");
#else
            File.CreateSymbolicLink(linkPath, finalTarget);
#endif
        } else {
            throw new IOException("Target path does not exist.");
        }
    }

    /// <summary>
    /// Returns true if the specified path exists and is a junction point or symlink.
    /// If the path exists but is not a junction point or symlink, returns false.
    /// </summary>
    public static bool Exists(string linkPath)
    {
        return TryGetLinkFsi(linkPath, out var _);
    }

    /// <summary>
    /// Does nothing if the path does not exist. If the path exists but is not 
    /// a junction / symlink, throws an IOException.
    /// </summary>
    public static void Delete(string linkPath)
    {
        var isLink = TryGetLinkFsi(linkPath, out var fsi);
        if (fsi != null && !isLink) {
            throw new IOException("Path is not a junction point.");
        } else {
            fsi?.Delete();
        }
    }

    /// <summary>
    /// Get the target of a junction point or symlink.
    /// </summary>
    /// <param name="linkPath">The location of the symlink or junction point</param>
    /// <param name="resolve">If true, will return the full path to the target.
    /// If false, will return the link target unadulterated - so it may be a 
    /// relative or an absolute path.</param>
    public static string GetTarget(string linkPath, bool resolve = true)
    {
        if (TryGetLinkFsi(linkPath, out var fsi)) {
            string target;
#if NETFRAMEWORK

            target = GetTargetWin32(linkPath);
#else
            target = fsi.LinkTarget!;
#endif
            if (!resolve) return target;

            if (Path.IsPathRooted(target)) {
                // if the path is absolute, we can return it as is.
                return Path.GetFullPath(target);
            } else {
                // if it is a relative path, we need to resolve it as it relates to the location of linkPath
                return Path.GetFullPath(Path.Combine(Path.GetDirectoryName(linkPath)!, target));
            }
        }
        throw new IOException("Path does not exist or is not a junction point / symlink.");
    }

    private static bool TryGetLinkFsi(string path, out FileSystemInfo fsi)
    {
        fsi = null!;
        if (Directory.Exists(path)) {
            fsi = new DirectoryInfo(path);
        } else if (File.Exists(path)) {
            fsi = new FileInfo(path);
        }

        return fsi != null && (fsi.Attributes & FileAttributes.ReparsePoint) != 0;
    }

    private static string GetRelativePath(string relativeTo, string path)
    {
#if NETFRAMEWORK
        relativeTo = Path.GetFullPath(relativeTo);
        path = Path.GetFullPath(path);
        return ToggleRelative(relativeTo, path);
#else
        return Path.GetRelativePath(relativeTo, path);
#endif
    }

#if NETFRAMEWORK
    [Flags]
    private enum EFileAttributes : uint
    {
        Readonly = 0x00000001,
        Hidden = 0x00000002,
        System = 0x00000004,
        Directory = 0x00000010,
        Archive = 0x00000020,
        Device = 0x00000040,
        Normal = 0x00000080,
        Temporary = 0x00000100,
        SparseFile = 0x00000200,
        ReparsePoint = 0x00000400,
        Compressed = 0x00000800,
        Offline = 0x00001000,
        NotContentIndexed = 0x00002000,
        Encrypted = 0x00004000,
        Write_Through = 0x80000000,
        Overlapped = 0x40000000,
        NoBuffering = 0x20000000,
        RandomAccess = 0x10000000,
        SequentialScan = 0x08000000,
        DeleteOnClose = 0x04000000,
        BackupSemantics = 0x02000000,
        PosixSemantics = 0x01000000,
        OpenReparsePoint = 0x00200000,
        OpenNoRecall = 0x00100000,
        FirstPipeInstance = 0x00080000
    }

    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
    private static extern SafeFileHandle CreateFile(
        string lpFileName,
        FileAccess dwDesiredAccess,
        FileShare dwShareMode,
        IntPtr lpSecurityAttributes,
        FileMode dwCreationDisposition,
        EFileAttributes dwFlagsAndAttributes,
        IntPtr hTemplateFile);

    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
    private static extern bool CreateSymbolicLink(string lpSymlinkFileName, string lpTargetFileName, int dwFlags);

    private const int SYMBOLIC_LINK_FLAG_FILE = 0x0;
    private const int SYMBOLIC_LINK_FLAG_DIRECTORY = 0x1;
    private const int SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE = 0x2;
    private const int INITIAL_REPARSE_DATA_BUFFER_SIZE = 1024;
    private const int FSCTL_GET_REPARSE_POINT = 0x000900a8;
    private const int ERROR_INSUFFICIENT_BUFFER = 0x7A;
    private const int ERROR_MORE_DATA = 0xEA;
    private const uint IO_REPARSE_TAG_SYMLINK = 0xA000000C;
    private const uint IO_REPARSE_TAG_MOUNT_POINT = 0xA0000003;

    [DllImport("Kernel32.dll", SetLastError = true, CharSet = CharSet.Auto)]
    private static extern uint GetFinalPathNameByHandle(IntPtr hFile, [MarshalAs(UnmanagedType.LPTStr)] StringBuilder lpszFilePath, uint cchFilePath, uint dwFlags);

    [DllImport("kernel32.dll", SetLastError = true)]
    [return: MarshalAs(UnmanagedType.Bool)]
    private static extern bool DeviceIoControl(
        SafeFileHandle deviceHandle,
        uint ioControlCode,
        IntPtr inputBuffer,
        int inputBufferSize,
        byte[] outputBuffer,
        int outputBufferSize,
        out int bytesReturned,
        IntPtr overlapped);

    private static string GetTargetWin32(string linkPath)
    {
        // https://github.com/microsoft/BuildXL/blob/main/Public/Src/Utilities/Native/IO/Windows/FileSystem.Win.cs#L2711
        // http://blog.kalmbach-software.de/2008/02/28/howto-correctly-read-reparse-data-in-vista/
        // https://github.com/dotnet/runtime/blob/e5f0c361f5baea5e2b56e1776143d841b0cc6e6c/src/libraries/System.Private.CoreLib/src/System/IO/FileSystem.Windows.cs#L544
        SafeFileHandle handle = CreateFile(
            linkPath,
            dwDesiredAccess: 0,
            FileShare.ReadWrite | FileShare.Delete,
            lpSecurityAttributes: IntPtr.Zero,
            FileMode.Open,
            dwFlagsAndAttributes: EFileAttributes.BackupSemantics | EFileAttributes.OpenReparsePoint,
            hTemplateFile: IntPtr.Zero);

        if (Marshal.GetLastWin32Error() != 0)
            ThrowLastWin32Error("Unable to open reparse point.");

        int bufferSize = INITIAL_REPARSE_DATA_BUFFER_SIZE;
        int errorCode = ERROR_INSUFFICIENT_BUFFER;

        byte[] buffer = null!;
        while (errorCode == ERROR_MORE_DATA || errorCode == ERROR_INSUFFICIENT_BUFFER) {
            buffer = new byte[bufferSize];
            bool success = false;

            int bufferReturnedSize;
            success = DeviceIoControl(
                handle,
                FSCTL_GET_REPARSE_POINT,
                IntPtr.Zero,
                0,
                buffer,
                bufferSize,
                out bufferReturnedSize,
                IntPtr.Zero);

            bufferSize *= 2;
            errorCode = success ? 0 : Marshal.GetLastWin32Error();
        }

        if (errorCode != 0) {
            throw new Win32Exception(errorCode);
        }

        const uint PrintNameOffsetIndex = 12;
        const uint PrintNameLengthIndex = 14;
        const uint SubsNameOffsetIndex = 8;
        const uint SubsNameLengthIndex = 10;

        uint reparsePointTag = BitConverter.ToUInt32(buffer, 0);
        if (reparsePointTag != IO_REPARSE_TAG_SYMLINK && reparsePointTag != IO_REPARSE_TAG_MOUNT_POINT) {
            throw new NotSupportedException($"Reparse point tag {reparsePointTag:X} not supported");
        }

        uint pathBufferOffsetIndex = (uint) ((reparsePointTag == IO_REPARSE_TAG_SYMLINK) ? 20 : 16);

        int nameOffset = BitConverter.ToInt16(buffer, (int) PrintNameOffsetIndex);
        int nameLength = BitConverter.ToInt16(buffer, (int) PrintNameLengthIndex);
        string targetPath = Encoding.Unicode.GetString(buffer, (int) pathBufferOffsetIndex + nameOffset, nameLength);

        if (string.IsNullOrWhiteSpace(targetPath)) {
            nameOffset = BitConverter.ToInt16(buffer, (int) SubsNameOffsetIndex);
            nameLength = BitConverter.ToInt16(buffer, (int) SubsNameLengthIndex);
            targetPath = Encoding.Unicode.GetString(buffer, (int) pathBufferOffsetIndex + nameOffset, nameLength);
        }

        return targetPath;
    }

    private static void ThrowLastWin32Error(string message)
    {
        throw new IOException(message, Marshal.GetExceptionForHR(Marshal.GetHRForLastWin32Error()));
    }

    private static string ToggleRelative(string basePath, string toggledPath)
    {
        // from https://github.com/RT-Projects/RT.Util/blob/master/RT.Util.Core/Paths/PathUtil.cs#L297
        if (basePath.Length == 0)
            throw new Exception("InvalidBasePath");
        if (toggledPath.Length == 0)
            throw new Exception("InvalidToggledPath");
        if (!Path.IsPathRooted(basePath))
            throw new Exception("BasePathNotAbsolute");

        try { basePath = Path.GetFullPath(basePath + "\\"); } catch { throw new Exception("InvalidBasePath"); }

        if (!Path.IsPathRooted(toggledPath)) {
            try {
                return StripTrailingSeparator(Path.GetFullPath(Path.Combine(basePath, toggledPath)));
            } catch {
                throw new Exception("InvalidToggledPath");
            }
        }

        // Both basePath and toggledPath are absolute. Need to relativize toggledPath.
        try { toggledPath = Path.GetFullPath(toggledPath + "\\"); } catch { throw new Exception("InvalidToggledPath"); }
        int prevPos = -1;
        int pos = toggledPath.IndexOf(Path.DirectorySeparatorChar);
        while (pos != -1 && pos < basePath.Length && basePath.Substring(0, pos + 1).Equals(toggledPath.Substring(0, pos + 1), StringComparison.OrdinalIgnoreCase)) {
            prevPos = pos;
            pos = toggledPath.IndexOf(Path.DirectorySeparatorChar, pos + 1);
        }
        if (prevPos == -1)
            throw new Exception("PathsOnDifferentDrives");
        var piece = basePath.Substring(prevPos + 1);
        var result = StripTrailingSeparator((".." + Path.DirectorySeparatorChar).Repeat(piece.Count(ch => ch == Path.DirectorySeparatorChar))
            + toggledPath.Substring(prevPos + 1));
        return result.Length == 0 ? "." : result;
    }

    private static string Repeat(this string input, int numTimes)
    {
        if (numTimes == 0) return "";
        if (numTimes == 1) return input;
        if (numTimes == 2) return input + input;
        var sb = new StringBuilder();
        for (int i = 0; i < numTimes; i++)
            sb.Append(input);
        return sb.ToString();
    }

    private static string StripTrailingSeparator(string path)
    {
        if (path.Length < 1)
            return path;
        if (path[path.Length - 1] == '/' || path[path.Length - 1] == '\\')
            return (path.Length == 3 && path[1] == ':') ? path : path.Substring(0, path.Length - 1);
        else
            return path;
    }
#endif
}

The Bane of Cross-Platform Distribution​

Imagine you've just developed this killer app. It's sleek, it's fast, and it's ready to make waves across Windows, macOS, and Linux. But wait, here comes the catch – updating this marvel. Suddenly, you're diving into the deep end of software update frameworks. For Windows, you might use Squirrel.Windows. For macOS, you're looking at Squirrel.Mac or Sparkle. And for Linux, oh boy, maybe AppImageUpdate, Snap, Flatpak, or a number of others.

And guess what? Each of these frameworks comes with its own set of quirks, documentation, setup, and debugging nightmares. You thought you signed up to be a developer, not a juggler, trying to keep all these different platforms and tools in the air. It's enough to make anyone question their life choices.

And what about if you're maintaining products written in different programming languages? You're stuck with this problem all over again because many of these frameworks are language specific.

All this ultimately takes time away from time which could be spent improving your actual product.

The Installer Conundrum​

Then there's the joy of dealing with installers. If you thought update frameworks were fun, installers are the party you never wanted to attend. Windows has WiX, NSIS, InnoSetup, or other commercial solutions, macOS prefers DMG or PKG, and Linux, well, it could be anything from a simple .deb to a more complex script. Each installer type is a world unto itself, requiring unique skills and knowledge to create and maintain.

The real kicker? Debugging. Something goes wrong, and suddenly you're deep in log files, trying to decipher where your installer decided to take a holiday. And let's not even start on the multitude of environments and versions your app needs to support. It's enough to give even the most seasoned developer a headache.

Not even going to mention CI, because now you're figuring out how to get all these tool working again in a possibly remote environment.

A Common Approach? More Like Common Frustration​

So, how do we brave souls typically tackle this Herculean task? Some of us go down the path of learning and mastering each tool and framework needed for our app's distribution. It's time-consuming, it's frustrating, and let's be honest, it's incredibly inefficient. Others might opt for a team of specialists, each versed in the arcane arts of their respective platform's distribution. Effective, perhaps, but not exactly practical or cost-efficient for smaller teams or solo devs.

And through all this, we haven't even touched on the ongoing maintenance these frameworks require. Updates, bug fixes, platform changes – it's a never-ending cycle of toil and trouble.

The Light at the End of the Tunnel​

Now, after painting quite the bleak picture, you might be wondering if there's any respite from this madness. Well, fellow developers, there is, and it goes by Velopack. Picture this: a single, streamlined framework that not only spans across Windows, macOS, and Linux but embraces a multitude of programming languages - so it goes with you no matter what app you're developing. A framework that's faster, smaller, handles updating, installing, eliminating the need to juggle a circus of tools and frameworks.

With Velopack, the promise is simple: learn once, apply everywhere. No more scrambling to keep up with the latest in installer technology or update frameworks. No more sleepless nights debugging a platform-specific distribution issue. Velopack offers a unified approach to software distribution, allowing developers to focus on what they do best – creating amazing software.

Did I mention it's free to use?

Not Just Another Tool​

Now, I know what you're thinking. "Great, another tool to learn." But hear me out. Velopack isn't just another drop in the ocean of software distribution tools. It's a lifeline thrown to developers drowning in the complexity of cross-platform distribution. By simplifying the process, Velopack frees up valuable time and resources, allowing us to channel our efforts into innovation and improvement, rather than maintenance and troubleshooting.

In the grand scheme of things, Velopack represents more than just a technical solution. It's a testament to the fact that sometimes, the best way to solve a complex problem is to step back and simplify. For developers tired of the distribution dance, Velopack offers a chance to change the tune, focusing on what matters most – delivering great software to our users.

So, if you're like me, fed up with the distribution dilemma and looking for a way out, give Velopack a try. It might just be the breath of fresh air your development process needs.

The journey to find one that would work for Velopack was painful and took a few tries.

Docfx​

Since we started out as a C# library, it made sense to start with docfx, which was appealing because if you just need to launch a documentation site as quickly as possible for a C# project, it seems to work well. The design is nothing to be proud of, but it's functional.

You can compile .csproj files to the corresponding docfx metadata (.yml), merge your extra markdown (.md) and output a static website in one command, and they even have handy instructions on their homepage on how to publish this to a Github Pages site.

Beyond the basics is where things started to get rough. We built the Velopack marketing site, I wanted to merge the two sites together, but I spent many hours pulling our my hair getting docfx to work with relative url's that live in parent directories ../../the-website for example. The solution I went with was in the website build script, copy all the files needed into the docfx project, build the site, and then copy the compiled assets back out. Far from elegant.

Also, good luck actually testing and seeing how anything looks - because there's no watch or hmr functionality built in, and compile times even for a small project could be as much as 10-20s. You need your own build scripts (eg. gulp) with watch built in if you want to get any real work done.

The next problem was styling. I wanted the documentation site to match the style of the marketing site, which I thought wouldn't be hard since they both used Bootstrap 5 (in fact, I picked Bootstrap 5 for the marketing site for this exact reason!). To get anything done, I needed to eject most of the underlying template files (which are handlebar based) and edit them directly. Since the template was already pre-compiled, the css it took to wrangle it into a good looking state was not "easy" per say, but bootstrap is fairly clean.

This site served us for a while. The design was okay (not great) and the built-in search was sub-par, but it worked for a month before I outgrew it and gave up. Velopack was expanding to support other programming langauges (Rust, C++, JS, etc) and became a multi-repo project.

The promise of one command -> get doc site was nowhere in sight. My build script for docfx was hundreds of lines long, copying files every which way, and in the end there were still crucial parts of the site I just could not alter or hook in to.

Nextra​

I am a fan of React and next.js, and so when I found a static site documentation engine built on both, I was over the moon. It was easy to get up and running, copy all my markdown in, even add inline React components to my markdown using mdx.

This time I wasn't going to get burned though, I was going to test everything I needed up front.

Out of the gate, TypeScript support was mixed, this wasn't a deal breaker for me. It needs to be set up manually, and some files just need to be .js or it won't work.

Dev server / HMR worked well to start with, but the build to static files is where things got hairier. Nextra is built as a JS SPA, and designed to deploy to Vercel or Netlify. There is an option to output: "export" your site to static files, this is the only way it will actually emit .html files, but with this option enabled the development server stops working. It also disables image optimisation and SPA/JS style navigation. Not an insurmountable problem but definitely an inconvenience for both me and my users.

The final problem which caused everything to fall apart was the styling. I'm by no means a designer, but I am a stickler for consistency. I wanted the background of the Nextra site to match that of the Velopack marketing site. Surely this would be an easy change.

It turns out changing the background just can't really be done. As is sometimes the case with React websites, the css class structure becomes totally incomprehensible, so writing manual css classes was out of the picture, and there was no setting or variable to override anywhere. Judging by some of the issues (eg. #2185, #788, #2122, and so on) this was not just a "me being thick" problem.

Docusaurus​

Since this was so much of an issue with Nextra, this time I started with styling and building.

Starting with Docusaurus ended up being much easier than the others. This was the only command I needed to scaffold the project with full TypeScript support.

npx create-docusaurus@latest my-docs-site-name classic --typescript

Styling came just as easy, the template had a custom css file all ready for me to add styles, there were examples on the docs and plenty of css variables to edit out of the box. In just a handful of minutes I had it styled the way I wanted, something that took hours or days on the previous attempts.

I was pleasantly suprised when it got time to compile the project. When I ran npm run build, docuaurus exported my site structure to pure html/css and also preserved JS/SPA nav. The way it worked is clever, Say you had the files intro.md and guide.md, it will generate html files for both of these so a static file server (like GitHub Actions) will also serve the files correctly. Once the page has loaded, following links will use JS/SPA style nav avoiding page re-loads. It's really slick.

At this point I was sold. I started moving all my markdown into my docusarus project.

For compiling references for language libraries, I had to use several strategies:

• C# using docfx metadata and dfmg to convert xmldoc to markdown
• JS using TypeDoc
• C++ using doxygen followed by moxygen to convert C++ headers to markdown
• For Rust, I didn't bother, since the default docs.rs page was good already.

Everything just worked perfectly. It was easy to start embedding custom React components into the docs too. Each Velopack docs page has an indicator at the top showing what operating systems are supported. In previous iterations this was just text, but in Docusarus it was easy to spruce up:

This was super simple. Just create a src/components/AppliesTo.tsx, and I also wrapped MDXComponents so I my component was pre-loaded (eg. did not need to import it at the top of the markdown page):

import MDXComponents from '@theme-original/MDXComponents';
import AppliesTo from '@site/src/components/AppliesTo';

export default {
    ...MDXComponents,
    AppliesTo,
};

And then in each markdown file I can just add the component directly, for example:

# My Page Title
<AppliesTo win mac />
This page applies to only windows and mac...

In the end, I can't recommend Docusaurus enough. It is extremely easy to use/get started, and provides plenty of extensibility in all areas.

And the fact that it comes out of the box with a Blog is the reason I'm writing this post!