March 21, 2024

Introducing Kotekan

Modern application development is amazing. Developers can build backends and frontends using the same language, and frameworks like React make it relatively easy to create powerful applications that offer a great user experience on the web and mobile.

However, due to the history of the web and JavaScript as a language, modern application development can also feel overwhelmingly complicated. Yes, you can use the same language for backend and frontend. Except, your JavaScript on the server differs from your JavaScript in the browser. Also, you probably want to code in TypeScript, which, of course, the browser doesn't understand. Then, you might want to optimize what gets sent to the browser to reduce the number of requests and the amount of bytes sent over the wire. And before you know it, you're knee-deep into having to learn and manage transpilers and bundlers that do things to your code that you only halfheartedly understand (if at all).

Don't get me wrong. All those tools exist for a reason and have enabled developers to do things that otherwise wouldn't be possible. We should be grateful for their existence and thank the people building and maintaining them. But I still feel that with all the progress the web development industry is making, it's worth exploring how to scale back complexity and move towards simpler setups.

When Jarred Sumner introduced Bun as an "all-in-one JavaScript runtime & toolkit," I was excited about this premise. But although Bun's reception has been great, and many developers have embraced it as a package manager and script runner due to its phenomenal performance, I haven't seen it adapted in the React world more broadly. I was curious: What would a React framework look like if Bun were the only tool in the toolchain?

Besides Bun, there is a second emerging technology that has me really excited: React Server Components. Although they were initially announced in December 2020 already, they've not been broadly adopted so far. More than that, their potential and the extent of the second-order effects on areas like data loading and routing are still being massively underestimated, in my opinion. I think that there are a lot of things that current React frameworks like Next.js and Remix do that won't be necessary (or will at least be vastly simplified) with Server Components. So the second I asked myself was: What would a modern, minimalistic React framework based on Server Components look like?

There was a third question I asked myself, which I'll talk about at a later point in time. Those questions led me on a path to build something that would both teach me a lot about the underlying themes of bundling, transpilation, and React Server Components and serve as an artifact to explore further what's possible today and share this exploration with the broader community.

Today, I'm excited to release the first version of Kotekan, a modern React framework built on Bun. Please note that this is highly experimental at this stage. I'm grateful to everyone who dares to try it, and I am looking forward to constructive feedback. I'd not recommend using this for any production workloads at this stage.

My goal was to create a React framework that supports React Server Components and adds as little abstraction between the code you write and the end result running in the browser as possible. Here are a few things that make Kotekan pretty unique, in my opinion:

  • There's no build step for server code. You write TypeScript, and it's executed by Bun directly. Client code is bundled (and minimized in production) with Bun's built-in bundler.
  • There are two separate Bun processes for the JSX server (which produces the "JSX over the wire") and the SSR server (which serves the HTML and other assets sent to the client). Those processes talk to each other via Unix domain sockets in dev mode and can be deployed on two different servers, talking to each other via HTTP in production.
  • MDX is compiled into JSX using a custom Bun plugin.
  • Kotekan doesn't use react-server-dom-webpack (because it doesn't use Webpack); it rather builds on react-server-dom-esm. Client components are delivered to the browser as ESM.
  • All HTML and JSX payloads are streamed to the browser.
  • The rendering strategy can be chosen via the url. Simply append ?csr to the URL for client-side rendering, ?ssr gives you server-side rendering (the default). ?jsx gives you the raw RSC/JSX payload. Adding ?hydrate=false disables hydration, basically giving you static HTML with SSR and an empty website with CSR.

There are lots of things to add and improve. The biggest missing feature for me right now is Fast Refresh/Hot Module Reloading, and I'm working on adding this. There is also stuff that's maybe implemented a bit awkwardly today and could be improved with future enhancements of Bun. I'm releasing this today to put the idea out there, to ask for feedback, and to be able to ask for help or suggest improvements in Bun or other dependencies.

If you want to try it out, you can create a new project by running:

bun create kotekan

Then start up the dev server by running:

bun dev

This documentation website is built with Kotekan, and I'm also working to add some more documentation to help people try it out. You can find the project at

Was this page helpful?