{
  "$type": "site.standard.document",
  "canonicalUrl": "https://johnnyreilly.com/posts/migrating-from-ts-node-to-bun",
  "description": "Migrating from ts-node to Bun is surprisingly easy - this post ports a console app from ts-node to Bun and compares performance.",
  "path": "/posts/migrating-from-ts-node-to-bun",
  "publishedAt": "2023-03-18T00:00:00.000Z",
  "site": "at://did:plc:yy3apqjlms24kso7ahn7lbmb/site.standard.publication/3mova7c4nho2b",
  "tags": [
    "node.js",
    "typescript"
  ],
  "textContent": "I've wanted to take a look at some of the alternative JavaScript runtimes for a while. The thing that has held me back is npm compatibility. I want to be able to run my code in a runtime that isn't Node.js and still be able to use npm packages. I've been using ts-node for a long time now; it's what I reach for when I'm building any kind of console app. In this post I want to port a console app from ts-node to Bun and see how easy it is.\n\n\n\nThe ts-node app\n\nI have a technical blog which is built on Docusaurus. When the Docusaurus build completes, a post processing script runs to do things like:\n\n- update the sitemap.xml to include the lastmod date based on git commit date, and truncate the number of entries in the file\n- patch the html files to use Cloudinary as an image CDN for open graph images\n\nThese scripts are implemented as a simple ts-node console app. For historical reasons it's called trim-xml (it originally just truncated the sitemap.xml file). It's not a particularly good name but I'm not going to change it now. As the blog is open source, you can see the code of trim-xml here.) When I ran the suggested commands it looked like bun was happy and healthy.\n\nPorting the install from yarn to bun\n\nWith bun in place I was ready to port the app. I opened up the (as I say, badly named) trim-xml directory and triggered installation of the dependencies using bun install:\n\nOutput looked like this:\n\nAs well, a new bun.lockb file had appeared in the directory alongside the package.json. Although I can't find any documentation on it, I'm guessing that this is the Bun equivalent of package-lock.json or yarn.lock. It's a binary file, so you can't read it. I did find this project which allows you read bun.lockb files which looks like a useful way to solve that problem.\n\nTo avoid confusion, I also deleted the yarn.lock file. Yay - I've installed things! And pretty fast! What next?\n\nFrom @types/node to bun/types\n\nAs I looked at the output for the install I realised that the @types/node package had been installed. The @types/node package is a package that contains TypeScript definitions for the Node.js runtime. Given we're moving to using Bun, it seemed likely that I didn't need these. But I likely did need something that represented the Bun runtime types. (Which incidentally, I would imagine to be pretty similar to the Node.js runtime types.)\n\nI had a quick look at the Bun documentation and found the bun/types package. I added it to my project, whilst removing @types/node and ts-node:\n\nOutput looked like this:\n\nThe docs also say:\n\n> Add this to your tsconfig.json or jsconfig.json:\n>\n> \n\nI aligned my existing tsconfig.json with the above. For my console app this meant the following changes:\n\nmoduleResolution with Bun\n\nI'd imagined that at this point I'd be able to run the app, but when I navigated around in VS Code I saw that I had a bunch of errors. I was getting errors like this:\n\nThe error message was suggesting I needed to explicitly state that I wanted to use the Node.js module resolution algorithm. Whilst we're using Bun, we're porting a Node app - so this made sense. So I made one more change to the tsconfig.json to satisy this:\n\nWith that in place, the module resolution errors were... resolved. (Sorry.)\n\nFile APIs with Bun\n\nHowever, I was still getting errors. This time they were about the fs.promises API. I was getting errors like this:\n\nIt looked like the version of bun I was using didn't support that API. As I dug through my code I realised that I was using the fs.promises API in a few places. I was using it in the following ways:\n\n- await fs.promises.readdir\n- await fs.promises.readFile\n- await fs.promises.writeFile\n\nFor fs.promises.readFile and fs.promises.writeFile I was able to replace them with the Bun equivalents Bun.file(path).text() and Bun.write(path, content) respectively:\n\nThere appeared to be no Bun equivalent for fs.promises.readdir, so I used the sync Node.js API:\n\nWe now had code without any errors. (At least in VS Code as far as TypeScript was concerned. I had yet to run the app to see if it worked.)\n\nClarification on fs.promises\n\nI was tweeting about my findings as I wrote this, and Jarred Sumner (who works on Bun) was kind enough to share that the fs.promises API is implemented but the types aren't as yet.\n\nRunning the app\n\nI now needed to do one more thing:\n\nThat's right; update the start script in package.json to use bun instead of ts-node. And now I was able to run the app with bun start:\n\nThe first positive thing about what I saw, was that we appeared to have running code. Yay! The program also appeared to be executing instantaneously, which seemed surprising. I was expecting Bun to be faster, but this seemed too fast.\n\nAlso, we seemed to be lacking many of the log messages I'd expect. I was expecting to see about 1000 log messages. Something wasn't right.\n\nTop level await and Bun\n\nThe issue was that my main function was asynchronous. However, because support for top level await wasn't available in Node.js when I originally wrote the code, I'd called the main function synchronously. Fortunately Node didn't complain about that, and the program behaved in the way required.\n\nHowever Bun looked like it was respecting the fact that main was asynchronous. That's why it was apparently executing so quickly; it wasn't waiting for the main method to complete before terminating.\n\nTo be honest, Bun's behaviour here is just right; the code as is didn't suggest that it was interested in waiting for the main function to complete. But it turns out that waiting is exactly the desired behaviour. To bring things right, we could use top level await. So I made the following change to my index.ts file:\n\nAnd now I was getting the expected log messages; and the program appeared to be working as expected.\n\nGitHub Actions and Bun\n\nI was now able to run the app locally. But I wanted to run it in GitHub Actions. I just needed to add the setup-bun action to my workflow, so bun was available in the GitHub Actions environment:\n\nPerformance comparison; Bun vs ts-node\n\nI was expecting Bun to be faster than ts-node. Let's take a run of our app in GitHub Actions with ts-node and compare it to a run of our app with Bun:\n\nts-node\n\nBun\n\nI haven't done any formal benchmarking, but it looks like Bun is about 50% faster than ts-node for this usecase. That's pretty good. It's also worth expanding on how this breaks down.\n\nYou'll notice in the logs above there's two log entries:\n\n1. The \"Post processing\" reflects the time taken to run the main function.\n2. The \"Done\" reflects the time taken to run the bun command end to end.\n\nWhat can we learn from this? First of all, running code in ts-node takes 17 seconds, compared to 12 seconds with Bun. So Bun is performing about 40% faster at running code.\n\nThe end to end is 19 seconds with ts-node, compared to 14 seconds with Bun. So Bun is performing about 50% faster end to end. There's two parts to this; the time taken to compile the code and the time taken to start up. We're doing type checking with ts-node; which if deactivated would make a difference.\n\nHowever, when you look at the difference between the end to end runtime and code runtime with Bun, it's a mere 0.353 seconds. ts-node clocks in at 2.43 seconds for the same. So ts-node is about 6.5 times slower at starting up. That's a pretty big difference; it's unlikely that all of this is TypeScript compilation; Node.js is fundamentally slower at getting going than Bun is.\n\nConclusion\n\nMoving from ts-node to Bun was a pretty easy process. I was able to do it in a few hours. I was able to run the app locally and in GitHub Actions. And I was able to run the app in less time.\n\nThis all makes me feel very positive about Bun. I'm looking forward to using it more in the future.\n\nThis post was originally published on LogRocket.\n\n<head>\n    <link rel=\"canonical\" href=\"https://blog.logrocket.com/migrating-typescript-app-node-js-bun/\" />\n</head>",
  "title": "Migrating from ts-node to Bun"
}