DEV Community: Ryan Kahn

Supercharge Your Observability: How OTEL MCP Server Unlocks AI-Powered Insights

Ryan Kahn — Tue, 27 May 2025 14:43:40 +0000

"What caused the outage last night, and how do we fix it?"

Imagine typing this question and getting an immediate, comprehensive answer – not from a human on call, but from an AI that has already analyzed your telemetry data, identified the root cause, and prepared a detailed explanation and recommendations with supporting evidence.

OTEL MCP Server makes this possible today by connecting AI systems directly to your OpenTelemetry data. While we've solved the collection problem with OpenTelemetry, we're still facing a critical gap – mountains of telemetry data that remain largely untapped because our tools can't keep pace with the volume and complexity. OTEL MCP Server bridges this gap, transforming raw telemetry into actionable intelligence through the power of AI.

What is OpenTelemetry?

OpenTelemetry (OTEL) is an open-source observability framework that provides a standardized way to collect telemetry data from your applications and infrastructure. It's a CNCF (Cloud Native Computing Foundation) project that has quickly become the industry standard for instrumentation.

The key components of OpenTelemetry include:

Traces: Distributed tracing that tracks requests as they flow through your services
Metrics: Numerical measurements collected at regular intervals
Logs: Time-stamped records of discrete events
Baggage: Contextual metadata that enriches your telemetry data

OpenTelemetry solves the instrumentation problem by providing a vendor-neutral API and SDK that works across languages and frameworks. This means you can instrument your code once and send the data to any compatible backend – whether that's Elasticsearch, Prometheus, Jaeger, or commercial observability platforms.

What is OTEL MCP Server?

OTEL MCP Server is an open-source tool that implements the Model Context Protocol (MCP) to provide AI systems with direct access to your OpenTelemetry data in Elasticsearch. It acts as a specialized connector that allows AI assistants to query and analyze your traces, metrics, and logs in real-time, regardless of your application architecture - from monoliths to microservices, cloud-native to on-premises deployments.

Key Capabilities

Direct Elasticsearch Queries: Execute powerful, custom queries against your telemetry data
Service-Aware Tools: Filter all operations by service or query across multiple services
Field Discovery: Automatically identify available fields to construct effective queries
Dual Mapping Support: Works with both native OTEL and Elastic Common Schema (ECS) mapping modes
Cross-Platform: Runs on Windows, macOS, and Linux

Why It Matters

OpenTelemetry has solved the data collection problem by providing a vendor-neutral way to instrument applications and gather telemetry data. However, traditional observability tools still require humans to manually navigate dashboards and query interfaces.

While paid observability platforms offer features like anomaly detection and alerting, they often come with significant costs and lock you into proprietary ecosystems. These services are valuable but can be expensive as your data volume grows, and they still require manual investigation when issues arise.

OTEL MCP Server offers a complementary approach by enabling AI systems to:

Investigate Incidents Autonomously: AI can query traces during outages, find error patterns, and correlate issues across your entire application landscape
Provide Context-Aware Assistance: When reviewing code, AI can simultaneously analyze related production telemetry data
Answer Complex Questions: "Show me all errors from the authentication flow in the last 24 hours" becomes a simple natural language request
Detect Anomalies On-Demand: Instead of configuring static thresholds, ask the AI to identify unusual patterns in your data

As developers, we know that a well-designed system reveals its own inner workings. A truly complete software system teaches developers how it functions, how to troubleshoot it, and how to extend it. By connecting OpenTelemetry data to AI, OTEL MCP Server amplifies this natural learning process, making the system's behavior more transparent and accessible.

Getting Started

Prerequisites

Before you begin, you'll need:

Elasticsearch (version 8.x or higher) with OpenTelemetry data
- OTEL MCP Server works with both OTEL and ECS mapping modes
- For development, you can use Elasticsearch with security disabled
OpenTelemetry Data
- Either from your own instrumented applications
- Or from the OpenTelemetry Demo for testing

Windsurf Integration

To use OTEL MCP Server with Windsurf, add this to your Windsurf MCP configuration:

{
   "servers": {
      "otel-mcp-server": {
         "command": "npx",
         "args": ["-y", "otel-mcp-server"],
         "env": {
            // Replace with your Elasticsearch URL and credentials
            "ELASTICSEARCH_URL": "http://localhost:9200",
            "ELASTICSEARCH_USERNAME": "elastic",
            "ELASTICSEARCH_PASSWORD": "changeme",
            "SERVER_NAME": "otel-mcp-server",
            "LOGLEVEL": "OFF"
         }
      }
   }
}

Once running, the server automatically detects available telemetry types in your Elasticsearch instance and registers the appropriate tools for your environment.

Real-World Applications

The true power of OTEL MCP Server emerges when integrated with AI-powered tools like Windsurf, creating a seamless bridge between code and telemetry data.

End-to-End Incident Management

In a recent demonstration, OTEL MCP Server was used with Windsurf and the OpenTelemetry Demo application to generate an entire incident report based on the demo application's test features, along with issues injected by Chaos Mesh. With just a few natural language prompts, the AI was able to:

Discover and analyze error patterns across multiple services
Correlate logs, traces, and metrics to identify the root cause
Generate a comprehensive incident report with supporting evidence
Provide actionable recommendations for fixing the issues

You can see the process in action and view the end result.

Unified Code and Telemetry Experience

With OTEL MCP Server, developers can interact with both their code and production telemetry through a single interface. This creates a powerful feedback loop where you can:

Analyze Performance Bottlenecks: "Find slow database queries in our payment service and suggest code improvements"
Debug with Production Context: "Show me recent error traces related to this authentication function I'm debugging"
Validate Fixes: "After my recent fix to the checkout service, did the error rate decrease?"
Understand System Behavior: "How does this microservice interact with others in production?"
Identify Patterns: "Show me the memory usage metrics for our application over the past day"
Compare Deployments: "Compare response times before and after our recent deployment"

The AI can directly access this data, analyze it, combine it with code context, and provide insights - all without you having to switch contexts or manually query your observability platform.

This unified view creates a development environment where the system itself becomes self-documenting and self-healing through its telemetry data, teaching developers how it works, how to fix issues, and how to extend it effectively.

The Future of AI-Powered Observability

OpenTelemetry has democratized telemetry data collection across the industry. Now, OTEL MCP Server takes the next step by democratizing access to this data for AI systems. This represents a fundamental shift in how we interact with observability data, moving toward a future where:

Incident response becomes more automated and efficient
Developers get real-time feedback based on production telemetry
The gap between code and runtime behavior narrows significantly
Observability becomes a natural part of every developer's workflow

Ready to try it yourself? Check out the GitHub repository and start connecting your AI tools to your OpenTelemetry!

My Type of Coding: Who reads what AI writes?

Ryan Kahn — Fri, 11 Apr 2025 03:43:46 +0000

One of the detractors of AI in the software development field is the idea that it does and will inhibit critical thinking and creativity among the next generation of developers. While I agree that this is possible, I don't see it as inevitable. In fact, AI in coding has the potential to usher in a new era of competency and understanding of the underlying principles of programming.

Much of the focus around AI has been on it being a tool to write code, to fill in blanks that a human developer would otherwise have to fill in. This begs an interesting question though, who is reading that code? Who is the critical thinker who reviews the changes and handles integration?

One story is that its nobody, that we all just vibe code and git commit -m yolo. Another story is that there's an overworked senior developer who is driven mad chasing the inconsistencies in the patchwork quilt that is vibe code. Neither of these stories is particularly positive or appealing from the standpoint of professional growth.

When I was starting out in software development, there was StackOverflow, there was Google and blog posts, and there were API Docs. There was a fourth, and lesser known resource that I found invaluable, and that is code. Yes that stuff we write, and more importantly the stuff other people write. I often say the point where my growth accelerated was when I started critically reading other peoples code.

This isn't something I have seen many developers, junior or otherwise, doing. Yes they participate in code reviews, yes they read the code around what they need to modify and extend, but no they don't read with the express purpose of learning new patterns, and new ways of doing things. This is where AI offers us an incredible opportunity.

Rather than using AI to simply write code for you, read the code it creates, engage your critical thinking skills, and learn from the patterns and practices it represents. In many ways it is the spirit of everyone else's code the model has gobbled up that you're conjuring when you hit enter on your well crafted prompt. AI offers us a learning experience tailored to the particular problems we're trying to solve.

AI certainly has the potential to drain our brains, to deprive us of opportunities to learn and think in the name of efficiency. Now that you're more efficient though, take the time to read through the code, understand the patterns, the API's involved. Find the mistakes and inconsistencies hidden like Easter Eggs throughout AI generated code. Become that senior developer who is not just reading code, but learning from it.

My Type of Coding: Who reads what AI writes?

Ryan Kahn — Fri, 11 Apr 2025 03:43:46 +0000

My Type of Coding: Express Route Param Types

Ryan Kahn — Mon, 07 Apr 2025 02:34:07 +0000

How does express extract the route parameters in TypeScript, such that we can read them off the request.params object in a typesafe way? It's quite ingenious, and uses template literal types, conditional types, and the infer keyword to recursively process the parameter names out of the path string and apply required and optional parameters to the params object in route handlers. Here are those types extracted into a CodeSandbox. If you open it on CodeSandbox you can see the intellisense at work!

My Type of Coding: TypeScript is for Humans

Ryan Kahn — Thu, 03 Apr 2025 13:55:37 +0000

When I started writing JavaScript, I loved it. I often compared it to painting, as opposed to a language like Java where it felt like I was building with blocks. These analogies represents spaces where patterns emerge. and what shape they will take.

In the painting world of JavaScript the patterns are innumerable. Almost any design pattern you like is possible, and you can make values essentially do whatever you please. This creates a problem though, and the problem is the "you" in those statements.

You are not alone! The design patterns you like may be obscure to someone else, and the tricks you do with values may not be amusing to someone else who has to figure them out. And so the beauty of the painting is in the mind of the coder who created it, and the mess is for everyone else.

What Patterns are in the Painting

"The Sacrament of the Last Supper" by Salvador Dali contains a myriad of patterns. Geometry, Perspective, Symbolism, Realism, Symmetry...but underneath it all what does it mean? In order to understand the genesis of these patterns, we would need the thousand words the picture is worth to tell us what the artist was thinking during the creation of a masterpiece.

Coding, however, is not painting. There is no "last" supper, it's an everlasting supper. We continue to add fruit to the table then use the painting as a recipe for dinner. So where do I add the fruit? Should it be an apple or a pear? Should I add the fruit at all? If I add a fruit should I remove a disciple? These are the questions we have to answer when we code.

Now we come to TypeScript

TypeScript is the language we use to describe patterns in our JavaScript. We're still painting, but while we're painting we're forced to explain the patterns in our mind to those who must carry the patterns in the code into the future. The patterns it elucidates are not obscure, ideally they should be what you were thinking anyway if you were just writing JavaScript.

type Frame = {
    src: URL
}

type Element = {
    children?: Element[]
}

type FrameElement = Frame & Element

We can describe the patterns in the same way as we're thinking about them as well. In the example above we have the concept of a Frame, which contains a src: URL property, and an Element, which can recursively have children?: Element[]. This explains something particular about how we were thinking about the code. That there are separate ways to look at the same object, and maybe separate objects that answer similar requirements. Like a pear in the painting having both a real and symbolic meaning, or an apple and a pear both being fruit.

type NotFound = 404
type OK = 200
type Err = 500

type StatusCode = NotFound | OK | Err

// Or

enum StatusCode {
  NotFound = 400,
  OK = 200,
  Err = 500,
}

Sometimes we're presented with a choice, two ways to explain the same thing. Here we have a representation of HTTP status codes in an application. The first way of representing the code exists only in TypeLand®️. The second creates an enum, which is both a type and an object at runtime. Which you choose depends on the requirements but also how you view the pattern you're trying to create, and how you see that pattern being used in the future as well. As in all coding, there's a preference for simpler answers.

const observeSymbol = Symbol('observe')

type Unsubscribe = () => void
type Observer<T> = (value: T) => void
type Subscribe<T> = (observer: Observer<T>) => Unsubscribe

type Observable<T> = T & {
  [observeSymbol]: Subscribe<T>
}

type ObservableMap<T> = {
    [K in keyof T]: T[K] extends () => void ? never : Observable<T[K]>
}

That said, sometimes things get complicated. Remember that TypeScript is essentially two programming languages in one. The one that rules TypeLand®️ and the one that runs the runtime. The type side has its own variables (aliases), functions (generics), logic (conditional types), comprehensions (mapped types), ect. We can make the complexity simpler just like we do in JavaScript or any programming language however.

In the example above, I could have just written out the ObservableMap type without the intermediate types. But, by factoring them out, as we would factor out references and functions, makes the code more readable. It also makes the patterns reusable. For example I might find myself wanting to subscribe to each key on an ObservableMap, in which case I might later add this:

type ObserverMap<T> {
    [K in keyof T]: T[K] extends () => void ? never : Observer<U>
}

const ObserveObject = <T>(map: ObservableMap<T>, obs: ObserverMap<T>): Unsubscribe => {
  return Object.keys(map).reduce((acc: Unsubscribe, k: keyof ObservableMap<T>) => {
      if (typeof map[k] !== 'function') {
          const unsubscribe = map[k][observableSymbol](obs[k])
          return () => {
              acc()
              unsubscribe()
          }
      }
  }, () => {})
}

Just like smaller more general functions in JavaScript, these smaller more general types or patterns in TypeScript allow us to reuse ideas to create new ones. Like Dali borrows patterns from da Vinci. While the above may seem complex (it is), in the end it's merely describing what we are actually doing in JavaScript. The real complexity is not documenting the patterns, and forcing everyone who looks at the code to re-invent them to figure out how to extend them.

What we didn't cover

We covered the human reason for TypeScript, as a form of documentation for how we as developers think of the JavaScript we write. What we didn't cover are the automation implications of this translation. Now not only can humans read the painting, but we've structured it in a way that machines can understand it as well. The ideas that we expressed in the original work can be checked for consistency, and this leads to a more reliable codebase. There are certain refactors as well that can be performed automatically, which is an added bonus.

Conclusion

Painting is an art, and so is coding — whether in JavaScript, TypeScript, or __________. However you choose to write your JavaScript, consider the person in the future how has to figure out what exists only in your mind as you write it. Unlike a painting, the mystery is not the point of the art, the function is. Leave the mystery to Dali, and write code that is understandable, verifiable, and extensible.

My Type of Library: Axios TypeScript Conversion

Ryan Kahn — Tue, 01 Apr 2025 13:39:38 +0000

This is the first post in an ad-hoc series where I convert libraries to TypeScript, and analyze the results. In the same vein as my re-conversion of the Turbo Framework to TypeScript, I decided to take a popular JavaScript library, this time one that had always been in JavaScript, and see what converting the codebase to TypeScript revealed. I chose Axios, because it’s:

Popular, well used, extensively developed
Written in JavaScript, with a manually generated TypeScript definitions file
Small enough to be easily convertible, and large enough to be interesting

The functional issues revealed during the conversion show the flexibility of JavaScript and the clever “tricks” we often perform with it. In highlighting the issues, I utilized AI agents through the Windsurf editor, and when it offered suggestions for fixes, I realized that even with the extensive context provided by the codebase, its solutions were still sub-par and illustrative of the limits of how AI can help with TypeScript problems.

To that end, I’ll highlight some of the issues found in the conversion that necessitate functional changes, referencing both my converted code and the Axios main branch as of this writing. I’ll also compare the solutions to these issues that were provided by Claude 3.7, and contrast them with my preferred solutions to show how Claude conceives of the code and solutions, and how this differs from the way a skilled developer (if I do say so myself) views them.

To be clear, there are many errors in my conversion. Where I left things there are 300 odd errors, and the majority of these are probably not hinting at actual issues in the library. My goal in all this is to gain insight into how people write JavaScript utilizing TypeScript as a lens, not port the entire library and tests.

Instead of doing that conversion writing a book, I'll write these posts about files where the Axios rubber meets the road. The first is the "fetch adapter", which integrates the modern fetch browser API into Axios. Although it's not Axios's default adapter, it still provides some elucidating errors it when converted. It was also created mostly in one PR by a core maintainer, so it highlights what TypeScript can do on the single developer, small scale. In the next post I'll take a look at another file, one that can tell us more about TypeScript in an active historical codebase, and when looked at in concert with the git blame and the associated pull requests, can give us an idea of how issues organically come about.

TS2322: Type is not assignable

Error: Type 'string' is not assignable to type 'ResponseType | undefined'.

JS File lib/adapters/fetch.js:114
TS File: lib/adapters/fetch.ts:131

responseType = responseType ? (responseType + '').toLowerCase() : 'text';

To begin with this error, let's start with the type in question: ResponseType, which represents the different kinds of response formats that might be received from a fetch request. This comes from the index.d.ts file manually generated by the project itself:

export type ResponseType =
    | 'arraybuffer'
    | 'blob'
    | 'document'
    | 'json'
    | 'text'
    | 'stream'
    | 'formdata';

This error comes from the fact that we take a response type, and convert it from the more specific union type to a general string by concatenating it with an empty string converting it to lowercase. The "obvious" solution, and the one recommended by Claude, is to simply say "This was a possibly incorrectly cased ResponseType, it's now a ResponseType" using as:

responseType = (responseType ? (responseType + '').toLowerCase() : 'text') as ResponseType;

Let's think about this for a second though, why was it incorrectly cased in the first place? And if it was incorrectly cased, is it definitely a ResponseType like value in the first place? The answer is no, it might not be. This value comes directly from the user, and tracing the path from input to this point I was unable to find any validation that ensures this value is a valid response type.

Later on in the file we see that the responseType is used to access a resolver, which in turn accesses a Response method to deserialize the responseData:

let responseData = await resolvers[utils.findKey(resolvers, responseType) || 'text'](response, config);

If the type of response provided was incorrect, it wouldn't be found in the map of possible resolvers, and default to 'text'. What if I just typed bloob instead of blob though, does this lead to a logical error and a good user experience, as the library tries to parse my binary file as text? Probably not, and there is a better way (besides using types).

A friendlier solution that is hinted at by this error is to create some validation, and implement it much earlier on when we're processing the configuration from the user. There is already some generic code for merging configuration values with defaults, it seems that a similar validateConfig.js file could be created that follows a similar pattern, and provides functions for validating each value in the passed configuration. This could throw errors at the point where the configuration is passed, improving the developer experience in my example case and others involving similarly incorrect configuration values.

TS2345: Argument is not assignable to parameter

Error: Argument of type '{ body: ReadableStream; method: string; readonly duplex: string; }' is not assignable to parameter of type 'RequestInit'.

JS File: lib/adapters/fetch.js:31
TS File: lib/adapters/fetch.ts:39

const supportsRequestStream = isReadableStreamSupported && test(() => {
  let duplexAccessed = false;

  const hasContentType = new Request(platform.origin, {
    body: new ReadableStream(),
    method: 'POST',
    get duplex() {
      duplexAccessed = true;
      return 'half';
    },
  }).headers.has('Content-Type');

  return duplexAccessed && !hasContentType;
});

What's wrong with this picture? Trick question, there's nothing fundamentally wrong in my mind with this JavaScript. It's an example of feature detection, where stream request capability (as of this writing supported by Chrome, Edge, and Opera, and Node LTS and on) is supported by the current runtime. The method is actually quite creative, and twofold. First, pass an instance of ReadableStream as the request body, and check that the generated request does not have a content-type, which tells us we're not in FireFox for example which will return a content-type of "text/plain".

There is a problem with this in node environments however, in that older versions of Node will also return an object without a content type header, even though they don't implement streaming requests. So the final bit is to add a getter for the duplex property, and see if its actually read by the runtime's Request implementation. Brilliant! JavaScript allows us to pass objects with unused properties, so it won't tell us if anyone cares about them or not. This does, very cool!

While JavaScript allows us to pass these unused properties, TypeScript does not. Since the duplex property is not completely supported across major browsers, its not included in the RequestInit type that's expected as the second argument to the Request constructor. So now that we've established its all good, how do we tell TypeScript not to worry. Claude AI comes up with what I think is a wrong answer given the context. Basically, let's create our own type that isn't in the standard library, and tell TypeScript its that instead. Something like this:

interface ExtendedRequestInit extends RequestInit {
  duplex?: string;
}

// Then use it:
new Request(platform.origin, {
  // ...
} as ExtendedRequestInit);

Why is this a bad idea? Well someday that type will no longer be needed, as the duplex property and functionality becomes more widely supported. If that happens, and the standard library is updated, this band-aid will still be there, and become unneeded. A better solution to this problem is to use the @ts-expect-error directive, which tells TypeScript "I know this is wrong, trust me". And if one day it becomes correct, TypeScript will return the favor and say "Actually, you're wrong, it's right." When it becomes right we remove the directive, and all is well!

const supportsRequestStream = isReadableStreamSupported && test(() => {
  let duplexAccessed = false;

  const hasContentType = new Request(platform.origin, {
    body: new ReadableStream(),
    method: 'POST',
    // @ts-expect-error duplex is an experimental property
    get duplex() {
      duplexAccessed = true;
      return 'half';
    },
  }).headers.has('Content-Type');

  return duplexAccessed && !hasContentType;
});

Directives are a feature and they're useful, @ts-ignore over any as the former is documenting, @ts-expect-error is even better as it will tell you if its fixed. My personal opinion is that any is not a type its a type-hole, its not a feature of TypeScript its a compiler error, don't use it.

TS2367: This comparison appears to be unintentional

Error: This comparison appears to be unintentional because the types have no overlap.

JS File: lib/adapters/fetch.js:172
TS File: lib/adapters/fetch.ts:189

const isStreamResponse = supportsResponseStream && (responseType === 'stream' || responseType === 'response');

Take a look at this one, and thinking back to what we know about ResponseType, what might be the issue? If you said 'response' isn't a valid ResponseType, you'd be right! We know this because it's in the type definitions that exist already in Axios. I also know this because a search of the codebase reveals that the string doesn't appear in any other context in relation to a ResponseType.

This line existed in the original PR, and was actually modified in a second pr to fix a bug, but in both cases this comparison appears. Maybe it was an addition for an idea that was never completed or wasn't needed by the end of the PR, but either way TypeScript tells us its probably a mistake. Tell us Claude, how should we fix this? What's that, create a new CustomResponseType to include 'response'?

type CustomResponseType = ResponseType | 'response';

This is a solution, but it completely misses the reality of this kind of error. Its pointing to code that should be removed, not simply a compiler error to be silenced. We sometimes get into this habit ourselves as developers, especially when we're the second developer to touch a piece of code. It can be scary to delete from the codebase. Isn't it "safer" to put a bandaid on the error in TypeLand®️, rather than risk it all in the real world?

This is where TypeScript gives us an edge, because a) it would have prevented the problem in the first place. That's it actually, there is no b. And, when things do come up, TypeScript and properly typed code gives us the confidence to refactor without fear of breaking the contracts that the types define.

Up Next!

Stay tuned for my next post in this series, where I'll break down a second file in the Axios codebase!

Type-Casting Doubt: How A TypeScript Re-Migration Revealed The Truth About Turbo

Ryan Kahn — Sun, 30 Mar 2025 01:15:32 +0000

In September 2023, David Heinemeier Hansson announced that "Turbo 8 is dropping TypeScript." This decision generated significant discussion in the development community regarding the merits of static versus dynamic typing systems.

The Turbo framework represents an ideal case study because it previously underwent a full JavaScript-to-TypeScript migration before reverting back to JavaScript. This prior conversion was not merely superficial; it involved substantial refactoring throughout the codebase.

This analysis presents empirical evidence regarding TypeScript's effectiveness in the context of the Turbo framework, based on a reimplementation of Turbo using TypeScript (github.com/shiftyp/ts-turbo).

Historical Context of TypeScript in Turbo
What TypeScript Actually Fixed
- Null References
- Interface Implementation Inconsistencies
- Coercion Issues
What TypeScript Couldn't Fix
- Logical Errors
- Browser Compatibility Issues
- Memory Management Issues
TypeScript Done Wrong
- Configuration Problems
- Any Type Misuse
- Error Suppression
Best Practices for TypeScript Migration

Historical Context of TypeScript in Turbo

DHH stated that "TypeScript just gets in the way for me," and "things that should be easy become hard, and things that are hard become any." This perspective merits examination in the specific context of Turbo's implementation.

The commit history indicates that Turbo's previous TypeScript implementation was partial and inconsistent. The codebase exhibited signs of Type-Script-as-retrofit rather than TypeScript-by-design. Specifically, it showed patterns of:

Extensive use of any types to bypass type checking
Disabled strict null checks to avoid addressing potential null references
Inconsistent application of type safety across related components

What TypeScript Actually Fixed

When properly implemented with strict settings, TypeScript revealed a number of genuine issues in the Turbo codebase:

Null References

Null reference errors can cause applications to crash with messages like "Cannot read property 'getAttribute' of null". These issues are particularly dangerous because they can work during testing but fail in production under specific conditions. They result in blank pages, non-functioning controls, or broken navigation for users.

In frame controllers, element references were frequently accessed without checking for existence. Consider this innocent-looking JavaScript code from the original Turbo implementation:

// From commit 9f3aad7: src/core/frames/frame_controller.js
getRootLocation() {
  const meta = this.element.ownerDocument.querySelector(`meta[name="turbo-root"]`)
  const root = meta?.content ?? "/"
  return expandURL(root)
}

What happens when this.element is null? JavaScript crashes at runtime with a null reference error. The TypeScript version in ts-turbo makes this safer:

// Current implementation in ts-turbo: src/core/frames/frame_controller.ts
get rootLocation(): Location {
  if (!this.element) return expandURL("/")
  const meta = this.element.ownerDocument.querySelector<HTMLMetaElement>(`meta[name="turbo-root"]`)
  const root = meta?.content ?? "/"
  return expandURL(root)
}

When this pattern appears throughout your codebase, users might experience seemingly random errors that would be difficult to reproduce and debug.

Interface Implementation Inconsistencies

Inconsistent interface implementations create "ghost bugs" where components work in normal conditions but fail in edge cases. These failures manifest as seemingly random crashes or functionality that works inconsistently. Interface mismatches create problems with missing parameters, unexpected return types, and dependencies on non-existent properties.

JavaScript's loose nature allowed Turbo components to implement interfaces inconsistently. A particularly dangerous interface implementation issue found during the migration involves the delegate pattern and missing method implementations. Turbo uses a system where FrameElement has a delegate, but there's no explicit interface defining what methods this delegate must implement.

In frame_controller.js (lines 238), we see a call to a method that may not exist:

// In frame_controller.js - The method is called on the frame's delegate
frame.delegate.proposeVisitIfNavigatedWithAction(frame, element, submitter)

Turbo has a delegate pattern where FrameElement creates its delegate from a constructor class:

// In frame_element.js - The delegate is created but with no explicit interface
export class FrameElement extends HTMLElement {
  static delegateConstructor = undefined  // Set elsewhere in the codebase

  constructor() {
    super()
    this.delegate = new FrameElement.delegateConstructor(this)
  }

  // The only delegate methods actually called are:
  connectedCallback() {
    this.delegate.connect()
  }

  disconnectedCallback() {
    this.delegate.disconnect()
  }

  attributeChangedCallback(name) {
    if (name == "loading") {
      this.delegate.loadingStyleChanged()
    } else if (name == "src") {
      this.delegate.sourceURLChanged()
    } else {
      this.delegate.disabledChanged()
    }
  }
}

The problem is that in JavaScript, there's no explicit interface requiring proposeVisitIfNavigatedWithAction to be implemented by whatever class gets assigned to FrameElement.delegateConstructor. This creates an implicit, undocumented contract between components.

This is a particularly severe issue that would cause the application to crash with a "method not found" error when a frame navigation occurs. Since the error only happens during specific navigation sequences, it would be difficult to detect during testing. In TypeScript, this problem is solved by requiring explicit interfaces that define exactly what methods must be implemented.

Confusing Type Coercion

JavaScript's implicit type coercion creates bugs that appear to work correctly but produce incorrect results under specific conditions. These issues are difficult to debug because they often appear to be environmental or timing-related problems.

JavaScript's implicit type coercion created subtle bugs that often went unnoticed until they caused production failures. In src/core/drive/history.js we find code that raises questions about intent:

// Original JavaScript implementation - implicit type coercion
restore(position) {
  if (this.restorationIdentifier) {
    history.replaceState(history.state, "", location.toString())
    this.location = location.href
    history.pushState(history.state, "", position)
    // Number comparison with string using == (not ===)
    if (this.currentIndex == 0) {
      window.scrollTo(0, 0)
    }
  }
}

The TypeScript implementation in ts-turbo makes the comparison explicit and prevents potential coercion issues:

// TypeScript implementation in ts-turbo
restore(position: URL): void {
  if (this.restorationIdentifier) {
    history.replaceState(history.state, "", location.toString())
    this.location = location.href
    history.pushState(history.state, "", position)
    // Explicit comparison with proper typing
    if (this.currentIndex === 0) {
      window.scrollTo(0, 0)
    }
  }
}

Is this checking for equality or accidentally converting types?
return this.pageLoaded || document.readyState == "complete". This might execute when you don't expect it to due to coercion. This pattern was found throughout the history management module. The deeper issue is more complex than it appears:

Mismatched comparison patterns: Throughout the codebase, comparisons mixed strict equality (===) and loose equality (==), creating inconsistent behavior. document.readyState == "complete" uses loose equality while this.restorationIdentifier === identifier uses strict equality elsewhere.
State tracking issues: The history system tracks various types of data: URL paths (strings), restoration identifiers (mixed types), and state objects. When compared with loose equality, URL paths like "/404" could accidentally match numeric identifiers.
Browser implementation differences: Browsers handle history state objects inconsistently - some preserve types exactly, others serialize and deserialize (changing types), and Safari might convert numeric strings to numbers in some contexts.

Another example comes from the form submission handling:

In the form submission handling, we see problematic implicit conversions:

// Actual code from form_submission.js after TypeScript removal (commit 9f3aad7772ba8ef4080538e4e5fb175a8ad550f1)
get method() {
  const method = this.submitter?.getAttribute("formmethod") || this.formElement.getAttribute("method") || ""
  return fetchMethodFromString(method.toLowerCase()) || FetchMethod.get
}

This pattern creates potential issues where an empty string method attribute (which is falsy in JavaScript) would be treated differently than a non-existent method, when both should result in the default method

This form submission example illustrates multiple coercion challenges that affected real user interactions:

Attribute handling inconsistencies: getAttribute() returns null for non-existent attributes while empty attributes return "". The logical OR (||) treats both as falsy, but these cases should be handled differently.
Form method determination: Web forms behave differently based on GET vs POST methods, affecting navigation, caching, and data handling. The wrong method can cause data loss or security issues.
Cascading defaults problem: The chain of OR operations creates complex logic paths where getAttribute() might return null, undefined, or empty string, each requiring different handling.

TypeScript's strict checking would have enforced explicit handling of these different cases.

TypeScript flagged dozens of instances where loose equality checks (==) were used instead of strict equality (===), where string values were implicitly converted to numbers, and where empty strings were treated as falsy values.

What TypeScript Couldn't Fix

Static typing isn't a silver bullet, and certain categories of bugs remained immune to TypeScript's protection:

Logical Errors Persisted

While TypeScript catches type-related errors effectively, it offers little protection against logical errors in algorithm design and control flow. Users might experience inconsistent application state, operations executing in the wrong order, and race conditions. These bugs often work during testing but fail in production, particularly with asynchronous operations where timing becomes critical.

The migration revealed that TypeScript couldn't prevent flawed algorithms or incorrect control flow. For example, in the stream message renderer implementation, even with TypeScript, logical errors in the processing sequence remained:

// From src/core/drive/navigator.ts in the TypeScript codebase
visit(location: URL, options: Partial<VisitOptions> = {}) {
  this.navigator.visit(location, options)
}

navigate(event: Event) {
  if (this.isHashChangeEvent(event)) {
    this.navigator.update(this.location, "replace")
  } else {
    // Event and navigation handling run in separate async paths
    // TypeScript can't detect logical flow problems between these methods
    const linkClicked = this.getVisitOptions(event)
    this.visit(linkClicked.url, linkClicked.options)
  }
}

This example illustrates a logical flow error that TypeScript cannot detect:

In Turbo's navigation system, there are multiple asynchronous execution paths:

The navigate() method responds to click events
getVisitOptions() performs DOM operations (reading data attributes) that are implicitly async
visit() initiates async operations (network requests, history API calls)
Multiple event listeners at different levels (window, document, elements) can trigger competing navigation requests simultaneously

The race condition occurs because between events, the URL can be modified by other code, multiple clicks create competing navigation requests, and these events execute in different event loop cycles that TypeScript cannot analyze.

These timing issues led to bugs where users would click a link but end up at a different URL, back/forward navigation would break after rapid interactions, and the browser and Turbo would get into inconsistent states about the "current" URL.

TypeScript can only validate parameter and return types, but cannot detect timing-related problems across event loops, verify coordination between async execution paths, or ensure state consistency in a multi-event environment.

These issues required specialized testing (like rapid-click testing) and event sequence analysis during code reviews - things that static type checking cannot provide.

Memory Management Still Required Discipline

Memory management issues cause gradual performance degradation, increasing memory consumption, and browser crashes after extended use. Applications become slower over time with no obvious solution except reloading. These problems are especially severe in single-page applications where resources aren't naturally cleaned up by page navigation.

Some of the most insidious bugs in Turbo involved memory management. Analysis of stream_source_element.js revealed significant issues:

// From commit 9f3aad7: src/elements/stream_source_element.js
export class StreamSourceElement extends HTMLElement {
  streamSource = null

  connectedCallback() {
    this.streamSource = this.src.match(/^ws{1,2}:/) ? new WebSocket(this.src) : new EventSource(this.src)

    connectStreamSource(this.streamSource)
  }

  disconnectedCallback() {
    if (this.streamSource) {
      disconnectStreamSource(this.streamSource)
    }
  }

  get src() {
    return this.getAttribute("src") || ""
  }
}

TypeScript can't catch memory leaks if disconnect logic is incomplete. The pattern above requires careful tracking of all resources across multiple components.

To better understand the context, let's look at my TypeScript implementation and several key components involved:

// src/elements/stream_source_element.ts (TypeScript implementation)
export class StreamSourceElement extends HTMLElement {
  streamSource: StreamSource | null = null

  connectedCallback() {
    // Creates either WebSocket or EventSource based on URL pattern
    this.streamSource = this.src.match(/^ws{1,2}:/) ? 
      new WebSocket(this.src) : new EventSource(this.src)

    connectStreamSource(this.streamSource)
  }

  disconnectedCallback() {
    if (this.streamSource) {
      disconnectStreamSource(this.streamSource)
    }
  }
}

// Example from observer pattern in frame_controller.ts
export class FrameController implements LinkClickObserverDelegate, 
  AppearanceObserverDelegate<FrameElement>, FormSubmitObserverDelegate {
  // Multiple observers that need to be started/stopped at the right times
  readonly appearanceObserver: AppearanceObserver<FrameElement>
  readonly formLinkClickObserver: FormLinkClickObserver
  readonly formSubmitObserver: FormSubmitObserver

  constructor() {
    // Create observers that register event listeners
    this.appearanceObserver = new AppearanceObserver(this, this.element)
    this.formLinkClickObserver = new FormLinkClickObserver(this, this.element)
    this.formSubmitObserver = new FormSubmitObserver(this, this.element)
  }

  connect() {
    this.appearanceObserver.start()
    this.formLinkClickObserver.start()
    this.formSubmitObserver.start()
  }

  disconnect() {
    this.appearanceObserver.stop()
    this.formLinkClickObserver.stop()
    this.formSubmitObserver.stop()
  }
}

This example represents a much larger memory management challenge in Turbo. The deeper context reveals:

Multi-layer resource ownership: The StreamSource element creates controllers that register observers, attach event listeners, and establish network connections. In the FrameController example, three different observer types are instantiated, each requiring proper start/stop coordination.
Disconnection gaps: The disconnectedCallback only calls hostDisconnected(), but that method might not clean up all event listeners, verify closed connections, or handle interruptions during active operations. TypeScript can't enforce proper cleanup at runtime.
Cross-component coordination: TypeScript has no way to ensure resources allocated by one component are cleaned up by another, observers are properly stopped, or event listeners are removed correctly. TypeScript can verify methods exist but cannot enforce they're called at the right time or sequence.

Typescript couldn't solve these fundamental design challenges because memory management in web components requires a holistic approach rather than just type checking. The issue wasn't just about having the correct type signatures, but about enforcing a complete resource lifecycle management system.

Other memory issues included event listeners not being properly removed, circular references preventing garbage collection, and resources not being released after use.

TypeScript offered little protection against these problems. Memory management in JavaScript requires disciplined coding practices regardless of the type system, and TypeScript's compile-time checks couldn't enforce proper cleanup.

TypeScript Done Wrong

A partial, inconsistent TypeScript implementation creates a situation where a codebase incurs all the costs of TypeScript (build complexity, learning curve, type definitions) while receiving few of its benefits. This can create a false sense of security and add friction to development, with team members spending time fighting the type system rather than leveraging it.

Perhaps the most revealing finding was that Turbo never truly implemented TypeScript correctly in the first place.

Configuration Shortcomings

The TypeScript configuration used in previous attempts was fundamentally flawed. From tsconfig.json prior to removal in commit 0826b8152c0e97f19d459c1a1c364fa89cc62829

{
  "compilerOptions": {
    "esModuleInterop": true,
    "lib": [ "dom", "dom.iterable", "esnext" ],
    "module": "es2015",
    "moduleResolution": "node",
    "noUnusedLocals": true,
    "rootDir": "src",
    "strict": true,
    "target": "es2017",
    "noEmit": true,
    "removeComments": true,
    "skipLibCheck": true,
    "isolatedModules": true
  },
  "exclude": [ "dist", "src/tests/fixtures", "playwright.config.ts" ]
}

Key issues included:

The tsconfig.json lacked crucial strict settings despite claiming to be "strict"
Important type checking flags like strictNullChecks were functionally disabled through type assertions
The compiler was configured to be permissive rather than strict in practice

The "Any" Escape Hatch

When TypeScript flagged potential issues, the common solution was to use the any type to silence the compiler rather than fix the underlying problem:

// From stream_message.ts prior to removal
// Instead of properly typing this:
function processMessage(message: any) {
  // Access properties without type checking
  if (message.content) {
    // Type safety completely bypassed
  }
}

// From error_renderer.ts prior to removal
function renderError(error: any) {
  // Using any to avoid properly modeling the error hierarchy
  return error.message || "Unknown error"
}

// Using any to bypass element type checking
function processNode(node: any) {
  // Directly accessing element properties without verification
  if (node.id && node.hasAttribute) {
    // This crashes if node is a Text node, not an Element
  }
}

// Promise error handling with any type
async function handleRequest(request: any): Promise<any> {
  try {
    // Generic error handling that loses error type information
    return await fetch(request)
  } catch (error: any) {
    console.error(error.message) // May fail if error isn't an Error object
  }
}

This pattern appeared throughout the codebase, effectively neutralizing TypeScript's benefits.

What This Means for the TypeScript vs. JavaScript Debate

DHH's frustration with TypeScript makes more sense when viewed through this lens. If your experience with TypeScript involves fighting a poorly configured system, inconsistent type enforcement, and partial implementations, then you're getting all of the friction with few of the benefits.

A lint check on the code right before TypeScript removal revealed 36 instances of the any type across the codebase. These were found in critical files like history management, rendering, HTTP request handling, and DOM manipulation.

TypeScript was implemented with significant escape hatches that undermined its safety benefits. Interestingly, while there were 36 instances of any types, there were no instances of directive comments like @ts-ignore, @ts-expect-error, or @ts-nocheck in the codebase. This suggests that developers were primarily using the any type as their main escape hatch rather than suppressing specific errors with directives.

This pattern reveals a TypeScript implementation that was likely using loose configuration settings rather than strict mode, with developers defaulting to any when encountering typing challenges instead of properly solving type issues. The result was a codebase with all of TypeScript's friction but few of its safety benefits.

However, this doesn't mean TypeScript itself is flawed. The evidence from the Turbo migration suggests that TypeScript can be valuable when:

It's implemented completely and consistently
Strict compiler settings are enabled from the start
Type definitions are treated as design tools, not afterthoughts
The escape hatches (any, type assertions) are used sparingly

Lessons From the Re-Migration

My experience remigrating Turbo to TypeScript (available at github.com/shiftyp/ts-turbo) has given me a unique perspective on this debate. By applying TypeScript properly—with strict null checks enabled, minimal use of any, and thorough interface definitions—I was able to uncover and fix numerous issues that had previously gone undetected.

The re-migration effort revealed several key improvements that TypeScript can bring when implemented correctly:

1. Explicit Interface Contracts

In the original codebase, interfaces were implicit. Looking at the remigrated session.ts file, proper interface definitions now explicitly state the contract between components:

// From src/core/session.ts in the remigration
interface PageViewDelegate {
  allowsImmediateRender({ element }: { element: Element }, options: RenderOptions): boolean;
}

interface LinkPrefetchDelegate {
  canPrefetchRequestToLocation(link: HTMLAnchorElement, location: URL): boolean;
}

export class Session implements PageViewDelegate, LinkPrefetchDelegate, FrameRedirectorSession {
  // Implementation now contractually bound to fulfill these interfaces
}

This pattern ensures that when one component expects another to have certain capabilities, that contract is verified at compile time rather than failing mysteriously at runtime.

2. Exhaustive State Handling

Form submissions in Turbo can exist in various states. The re-migration properly types these states using TypeScript's const assertions:

// From src/core/drive/form_submission.ts in the remigration
export const FormSubmissionState = {
  initialized: "initialized",
  requesting: "requesting",
  waiting: "waiting",
  receiving: "receiving",
  stopping: "stopping",
  stopped: "stopped"
} as const

export type FormSubmissionStateType = typeof FormSubmissionState[keyof typeof FormSubmissionState]

This pattern ensures that state transitions are checked exhaustively, preventing invalid states that could lead to runtime errors.

3. Browser Compatibility Safeguards

In the remigration, TypeScript forces explicit checks:

// From src/core/drive/history.ts in the remigration
assumeControlOfScrollRestoration() {
  if ("scrollRestoration" in history) {
    this.previousScrollRestoration = history.scrollRestoration
    history.scrollRestoration = "manual"
  }
}

By making these checks explicit in the type system, it's impossible to accidentally access APIs that might not exist in all browsers without first verifying their presence.

4. Form Data Safety

There were several issues with null references when processing form data. The remigration adds proper null checking:

// From src/core/drive/form_submission.ts in the remigration
buildFormData(formElement: HTMLFormElement, submitter?: HTMLElement): FormData | URLSearchParams {
  const formData = new FormData(formElement)
  const name = submitter?.getAttribute("name")
  const value = submitter?.getAttribute("value")

  if (name && value && formData.get(name) !== value) {
    formData.append(name, value)
  }

  return formData
}

This pattern of optional chaining (?.) combined with explicit null checks ensures that form processing is robust against missing data.

Conclusion

The Turbo TypeScript migration offers a nuanced perspective on the JavaScript vs. TypeScript debate. TypeScript isn't inherently good or bad—its value depends entirely on implementation. The remigration efforts have tangibly demonstrated both the costs and benefits of TypeScript when properly applied.

The question isn't "Should you use TypeScript or JavaScript?" but rather "Are you willing to implement TypeScript properly?" If you're going to disable strict null checks, use any types liberally, and only partially convert your codebase, you might be better off with JavaScript's simplicity.

DHH's announcement about dropping TypeScript from Turbo 8 might be less about TypeScript itself and more about recognizing that Turbo never gave TypeScript a fair chance to begin with. The history of previous attempts shows a pattern of half-measures and workarounds rather than embracing what TypeScript had to offer.

My re-migration project took a different approach. Rather than treating TypeScript as an afterthought or a simple type annotation layer, I integrated it as a fundamental design tool. By defining precise interfaces first and then implementing against those interfaces, TypeScript became a collaborator in the development process rather than an obstacle to be worked around. The result was a more robust codebase with fewer edge cases and more predictable behavior.

What's particularly revealing is how many issues were resolved not by adding complex type annotations, but by the simple act of forcing explicit handling of edge cases. For instance, many potential errors were eliminated by adding a few strategic null checks that TypeScript required but JavaScript didn't enforce.

Perhaps the right move isn't abandoning TypeScript, but implementing it correctly. Or perhaps, as DHH suggests, JavaScript itself has evolved enough that for some teams and projects, the additional safety net of TypeScript simply isn't worth the friction it introduces.

What's your experience? Has TypeScript saved your project from critical bugs, or has it primarily introduced friction? The debate continues, but hopefully with more nuance and less zealotry than before.

Code Mind, Beginners Mind

Ryan Kahn — Tue, 25 Mar 2025 01:18:17 +0000

“If your mind is empty, it is always ready for anything; it is open to everything. In the beginner’s mind there are many possibilities; in the expert’s mind there are few.”

— Shunryu Suzuki

Software development is an engineering discipline, a technical craft, and an art. It can also be a form of meditation, and in the style of zen practice, it can also be zen practice. Those who have sat with code long enough—through the long nights, through bugs, through flow states where time dissolves—know that writing software is as much about the mind as it is about the machine.

A calm, open, beginner’s mind is the most powerful tool a developer can cultivate. To write good code, it helps to let go of ego, of attachment, of the illusion of mastery. We are not building only systems—we are building awareness.

I. Syntax and Emptiness

When we first learn to program, everything is an obstacle. Syntax errors are indecipherable, types are byzantine, indentation and symbols are in a foreign tongue. Our minds are full of questions and doubt. And yet, in that state of confusion, there is a sense clarity and balance if we look for it. We are present. We are paying attention.

A more experienced developer may work in smoother fashion. They no longer think about where semicolons go, or how to declare a variable. But this fluency can be an impediment as well. They may assume understanding where there is none. They stop asking why.

Both stages have value (even if the salary doesn't reflect the value of a beginner), but it is the beginner’s curiosity that must be preserved.

When you can see syntax, look for structure. When you no longer think about loops and conditionals, think about clarity, intent, and flow. You must see through the code to the mind that wrote it and the mind that will read it. You must read code like a poem, not just a plan. A helpful note from all the developers who have come before and will come after, a lineage of knowledge.

In this way, code isn't code, its a product of countless minds, a thread in a fabric of existence, stretching from before computers to the present, into future technologies. From a Buddhist lens we might say it's empty of its own existence, and exists only in concert with the minds that envision it, the computers that run it, and the world that created it.

Seeing code this way may seem abstract, but if you really try you may find that its the most useful way to view it. It frees you of attachment to a particular commit, a particular way of doing things. Knowing that today's innovation is tomorrows legacy. It frees us to work, and create and iterate seeing each commit as a fresh start and at the same time nothing special.

II. The Simplicity of Understanding

The beginners focus is on making things work. This is everyone's focus of course (we spend 99.9% of our time in a broken state after all), but for the beginner the search lacks focus. We pile on logic, conditions, flags. Our code is often verbose. This is not wrong. It is part of the path. But over time, we develop simplicity—not the kind that comes from cleverness, but the kind that comes from understanding.

When we deeply understand a problem, our search is more focused, and we write less code. We remove more than we add. We avoid the temptation of premature abstraction. We leave helpful hooks, not voluminous frameworks. We write just enough and then stop.

This is difficult. Our culture rewards complexity. Job titles grow with the number of systems a person has touched. But in zen, as in code, the simplest solution is a sign of understanding. Simplicity is not a lack of ambition—it is a sign of maturity.

Write code as if you will come back to it in a year, tired and under pressure. Will you understand what it does? Will it still feel obvious? If not, there's an opportunity to make it simpler.

III. Version Control and Non-Attachment

Git is a wonderful tool. It can be maddening, but when used artfully and mindfully it gives us an opportunity to practice non-attachment. We write, we commit, we rewrite. We branch and merge. We make mistakes and revert. We learn to let go of what we wrote yesterday.

Code is not permanent. Systems evolve. Files disappear. Sometimes, entire architectures are thrown away in favor of something simpler, more modern, or more correct to the current problems.

To a beginner this might seem scary, difficult to swallow. When we've put our hearts into our work we may clutch code and the ideas behind it tightly, hoping it will be judged well, hoping it will stay, and we will stay. But a mature developer will take a different tact. Good code must be willing to die. It serves its purpose, and then it fades.

Don’t be precious about your solutions. Don’t resist a better one. Don’t argue for something just because you wrote it.

You are not your code.

IV. Bugs as Teachers

Bugs are not a sign of imbalance. A computer can never be out balance actually. If a cosmic ray flips a bit, that cascade of failures is the new balance. If you unplug it, its empty, and balanced. When things appear chaotic, this is an opportunity to learn. Every bug is a mirror. It shows us how we misunderstood the system, how we made assumptions, how we moved quickly.

To debug is not just to fix. It is to sit, to watch, to question. It is a meditation. You stare at the screen, not in frustration, but in patience. You trace the paths. You follow the data. You look for what you missed.

The bug does not lie. It does not hide. It is there, waiting to be seen. Most of the time, it's our perception of a solution that's clouded. We attach to the same path, checking the same solutions to see if "this time" they'll work. Sometimes magic happens, other times it takes time.

Sometimes, we debug in a frenzy. We change things randomly. We panic. But this generally pushes a solution farther away. It waits until we are calm again.

When we are still, when we go for a walk, or eat an orange, we see.

V. Architecture and the Space Between

A good system has room to breathe. It has space for change, for growth. It does not predict every requirement. It is not overbuilt. Like a mind with open doors, it invites what is needed, and lets go of what is not.

When we begin we might build with fear. Wanting to account for every possibility. Adding ideas no one has asked for. Creating abstractions in case “we need to change this later.”

But abstraction is not preparation. It is debt. Build the thing you know you need. Do it cleanly. When the need arises to generalize, you will know.

Systems emerge. They are not planned into existence. They evolve with attention and care.

VI. Collaboration and the Ego

When we code alone, we are gods in our own tiny worlds. But when we code in teams, we are students again.

In the beginning its natural to feel unsure in a team. We fear being wrong, we feel the perception of failure and the judgment of our peers. But the wise developer can adopt the stance of knowing they're wrong, knowing they don't have the full picture and that a team can correct and expand the vision of each member.

In pair programming, and code review, the best interactions feel like a conversation between equals, even if one person has a clearer vision of the problem. The joy comes not from proving knowledge, but from discovering something together.

In code reviews, we must be gentle. We must ask, not demand. Suggest, not declare. Teach, but also be taught.

The ego is the enemy of learning. The moment you think you are beyond beginner’s mind, you stop growing.

VII. Refactoring and Renewal

We don't make mistakes. We make one continuous mistake, and then we refactor to create a better mistake. Refactoring deepens our understanding. The first version of any system is like a sketch—useful, but incomplete. As we work with it, we see new shapes. We learn its rhythms.

To refactor is to clean the temple. It is not necessarily glamorous. It is necessary. It might even be fun.

We remove duplication because it hides patterns. We rename variables for clarity. We split functions to clear out confusion for that big brain that is the current and future team.

A well-factored codebase feels light. You want to work in it. You trust it.

This is not achieved once. It is a practice. Like tending a garden.

VIII. Always Returning

Every system will break. Every technique will grow old. Every library will be deprecated. In this way, software humbles us. It reminds us that we are not building forever. We are building for now. And we are part of that forever.

Beginner’s mind is not naivety. It is the courage to return. Again and again. To look at the same problem as if it were new. To let go of dogma. To let go of pride. To be curious again.

The code will always change. The tools will evolve. But the practice remains.

We come to the editor. We breathe. We write.

We begin again, awaiting input.

~# _

Backbone for React Devs: The Song Remains the Same

Ryan Kahn — Mon, 03 Apr 2023 16:15:37 +0000

Why should you care?

Maybe you shouldn't! However, if you have to work in Backbone and come from a React background, or if you're interested in some historical changes in the world of the web, read on! Even if you only care about React or modern DOM diffing frameworks, this comparison will give you a new perspective. So what is the difference between Backbone and React?

Imperative vs Declarative

The primary difference between React and Backbone is that React uses the Declarative (and "Reactive") way to define mutations or changes in a webpage, where as Backbone uses the Imperative way. Consider HTML:

<body>
  <h1>The title!</h1>
  <p>Some <span class="bold">content!</span></p>
</body>

HTML declares elements on the page, and sets an initial state and content for the page. It says what things are, and where the go, but does not (without a script block) define any interactions or changes to the page.

React is like this too, only it defines a cycle between a State, or values that change, and translates that through functions to a declarative snapshot of what the page looks like in reaction to that change (what you see in JSX). React looks at changes in the snapshots and through that diff mutates DOM elements. Sort of like a diff in git, "Add this Line", "Remove this Line", only its "Add this class", "Remove this element" ect... So in the end you declare the page, and React modifies it imperatively.

Backbone takes an older approach prior to DOM diffing frameworks appearance on the scene. Back then, JQuery was the hot library, and essentially it would do the same thing React does in the end. "Add this class" or "Remove this class". The approach is imperative directly, as in you select elements and mutate the DOM.

State and Components vs MVC

In React, you have state, and components. These fit the data flow and declarative style, where you're constantly translating state into DOM snapshots through nested function calls. Backbone has Models, Views. and Controllers. Because it's imperative, it needs to take an Object Oriented as opposed to a Functional approach. You need long lived references to DOM elements, the View objects, so that you can change them over time. The data flow isn't one way like React, so you need persistent models that handle the state of the program, and trigger changes in the Views through subscriptions (this is sort of like the reactivity in React). Then there are Controllers, that handle the business logic of the program. In React these kinds of changes would live mostly in effects with React hooks.

Code Navigation

Backbone can seem a bit like a mess compared to the clean functional programming of React. Persistent objects messaging each other willy nilly, mutating the DOM in a complex fashion...is less comprehensible than the one way data flow and declarative nature of React. And this is true! It is a bit of a mess! The key to comprehending it is to trace dependencies, just like you would look at nested components in React. Start with the DOM mutation, or model update that you care about. Then trace the function calls, the subscriptions to the model, or the other way from the view with the updates that lead to the change...follow this around and you'll be able to modify these interactions safely.

Conclusion

I am a strong believer that nothing really changes in software development. In the end we're doing the same thing programmers did on the ENIAC machine, translating input to output through commands and switches. In that same vein, web development hasn't really changed fundamentally between the Backbone years and the React years. We're still declaring the DOM in HTML, mutating it through JavaScript commands.

What has changed is how we divvy up these actions, how we generate the commands, and the resulting power and developer experience that gives us a bigger lever to move those bits around. Keep this in mind as you compare any two frameworks or programs, or languages, or any abstraction that we use in programming. There is nothing all that new fundamentally, and at the same time what does change is the power we have as developers to take in complex inputs and create ever more complex outputs.

Best of luck, and long live the web!

React Server Components Without a Framework

Ryan Kahn — Wed, 29 Mar 2023 16:15:03 +0000

Server Components are Cool! Frameworks may or may not be.

I, along with many ReactJS devs, have been following the development of the "new" React Server Components API with excitement. It solves some common problems in React around data fetching and efficiency in client side applications. If you're interested in learning more about the API I'd recommend you listen to the recent JS Party podcast with Dan Abramov and Joe Savona from the React Team on the future of React, and then check out the React Server Components Demo on GitHub.

One aspect of the planned Server Components API that I personally dislike is the reasoning from the core team that in order to make use of them, you should utilize a framework like Next or Remix. If you're already using one of these, then great! You will get this feature in time. But, if you're like me and would rather assemble right size tools on your own, or you have a large application you'd rather not completely refactor, this leaves something to be desired. I want there to be a way to use Server Components without a framework.

With this in mind, I've started building a compiler of sorts on top of TS-Morph that will allow you to write your client and server components together, and split them into two bundles automatically for deployment to your server of choice and client application. Ideally, this would work with both Typescript and JavaScript codebases. So far it does, but as I get deeper I can't make too many promises on this feature.

A tool for creating Server Components without a Framework

The emphasis of this tool would be to minimize both code and configuration, while introducing the least new dependencies into a code base. This starts with how you write your components. While the plan in Next, for example, is for developers to identify server and client components explicitly, their documentation points to a straightforward set of rules for how to divvy them up:

What do you need to do?	Server Component	Client Component
Fetch data.	✅	⚠️
Access backend resources (directly)	✅	❌
Keep sensitive information on the server (access tokens, API keys, etc)	✅	❌
Keep large dependencies on the server / Reduce client-side JavaScript	✅	❌
Add interactivity and event listeners (onClick(), onChange(), etc)	❌	✅
Use State and Lifecycle Effects (useState(), useReducer(), useEffect(), etc)	❌	✅
Use browser-only APIs	❌	✅
Use custom hooks that depend on state, effects, or browser-only APIs	❌	✅
Use React Class components	❌	✅

With these rules as a guide, it should be possible to separate server and client components into categories automatically based on their dependencies. In fact, I've already completed some of this work which you can check out on GitHub. The remainder of the work is more testing and implementation around third party dependencies, then creating and compiling the server and client bundles.

This would be exposed as a command line tool, as well as a Node API, to allow developers to integrate this optimization step into their build processes without adding additional dependencies outside of the compiler, some types if you're not using Typescript already, and some new React core packages for the client and server coordination.

What's "Next" and how you can help

At the very least, this would provide a way for all React devs to try out server components without the overhead of learning and implementing applications in a heavy framework. At the very best, it would allow application developers to integrate server components in a lightweight and seamless fashion into new and existing codebases. Overall I'm excited about the possibilities. Are you?

If so, I'd love ideas and contributions! I'd be happy to chat about:

Would you use this tool?
If so, or if not, what would make it a better fit?
What might you do to contribute to this open source project?

Let me know in the comments, I'd love to chat and work with y'all!

Space Themed Site with Mini Game!

Ryan Kahn — Sat, 19 Dec 2020 04:11:11 +0000

What I built

Hi all! For this hackathon (and for myself) I've built a space themed site for my work as an engineering mentor and trainer, with a collaborative mini-game! 🚀

Category Submission:

This falls under the personal site category!

App Link

You can find the application here at https://rkahn.dev!

Screenshots

Description

This site showcases some aspects and reviews of my work, as well as some personal information and thoughts. It also contains an astronaut themed mini-game. Launch an astronaut, and everyone can see it for a time!

Link to Source Code

The static site is built from this repo, and the golang / docker backend from this repo!

Permissive License

The code is all released under an MIT license. Feel free to remix it for your own purposes. The imagery on the site is not included in the repository, and is either copyrighted by myself or under the proprietary image license included in the static repo.

Background

I've been in need of a personal site for some time, but I haven't been inspired to come up with a design. I came across these space graphics a while back, and I've been meaning to incorporate them into a personal project. My personal site turned into a perfect opportunity!

How I built it

The static site and the backend are both built and deployed on Digital Ocean Apps. The images are separately hosted on a Digital Ocean Spaces CDN. The images are premium content from freepik.com and flaticon.com. I've purchased a license to them, so please don't use them without permission of their respective owners.

I tried to keep the code approachable, so the majority of the Frontend is built using just HTML and CSS and compiled with Parcel. The astronaut minigame is built using Preact with hooks!

The backend is built with Golang, mainly because this is what the Digital Ocean Docker example started as, and it seemed like a good idea! It stores all the data in memory and doesn't utilize a database. Go ahead and take a look! (see what I did there)

I had wanted to add an analytics server that used the Apps Postgres database component...but I ran into various issues involving SSL and decided to throw my hands in the air and use Segment. 🤷‍♂️

Additional Resources/Info

I really enjoyed using Digital Ocean Apps, it made the simpler things (for me) straightforward. I ran into some issues as stated with using the database component, but overall I had a great experience, and look forward to keeping the site on DO Apps for the foreseeable future!

Introducing Object Hooks: Mutable State for React 🤯

Ryan Kahn — Tue, 21 Apr 2020 14:21:11 +0000

The idea I started with is: What if we could write state changes in react as mutations on a persistent reference? 🤔 So I wrote the code to make it work! The basic concept is summed up in the code from the banner image:

import React from 'react';

import { useObject } from '../hooks/useObject';

export const Counter: React.FC = () => {
  const [state] = useObject({
    count: 1,
  });

  return (
    <button
      onClick={() => {
        state.count++;
      }}
    >
      {state.count}
    </button>
  );
};

In this case, state is a persistent reference that you can mutate (state.count++). The consequences of this change are fairly interesting. For one, you can create these objects with a class! So the above example could be rewritten as:

import React from 'react';

import { useInstance } from '../hooks/useInstance';

class Counter {
  count = 1;

  increment() {
    this.count++;
  }
}

export const Counter: React.FC = () => {
  const [counter] = useInstance(Counter);

  return (
    <button
      onClick={() => {
        counter.increment();
      }}
    >
      {counter.count}
    </button>
  );
};

Also, if you need to subscribe to to changes in the objects outside of a component function, they implement the AsyncIterable interface, so you can await their next state, or for await future states in an async function. Here's a logger class that subscribes to a counter!

class CounterLogger {
  constructor(
    private counter: Counter & AsyncIterable<Counter>
  ) {}

  log(count: number) {
    console.log(`Count is: ${count}`);
  }

  async watch() {
    this.log(this.counter.count);

    for await (const { count } of this.counter) {
      this.log(count);
    }
  }
}

There's more to it, and there will be more as the project progresses. I wanted to share what I have in its current "state" 😉 to give everyone a chance to contribute their thoughts and ideas! If you're interested, clone the repo and try it for yourself! Or leave a comment or question on this post! All are contributions, all are welcome. 🔰

DEV Community: Ryan Kahn

Supercharge Your Observability: How OTEL MCP Server Unlocks AI-Powered Insights

What is OpenTelemetry?

What is OTEL MCP Server?

Key Capabilities

Why It Matters

Getting Started

Prerequisites

Windsurf Integration

Real-World Applications

End-to-End Incident Management

Unified Code and Telemetry Experience

The Future of AI-Powered Observability

My Type of Coding: Who reads what AI writes?

My Type of Coding: Who reads what AI writes?

My Type of Coding: Express Route Param Types

My Type of Coding: TypeScript is for Humans

What Patterns are in the Painting

Now we come to TypeScript

What we didn't cover

Conclusion

My Type of Library: Axios TypeScript Conversion

TS2322: Type is not assignable

TS2345: Argument is not assignable to parameter

TS2367: This comparison appears to be unintentional

Up Next!

Type-Casting Doubt: How A TypeScript Re-Migration Revealed The Truth About Turbo

Contents

Historical Context of TypeScript in Turbo

What TypeScript Actually Fixed

Null References

Interface Implementation Inconsistencies

Confusing Type Coercion

What TypeScript Couldn't Fix

Logical Errors Persisted

Memory Management Still Required Discipline

TypeScript Done Wrong

Configuration Shortcomings

The "Any" Escape Hatch

What This Means for the TypeScript vs. JavaScript Debate

Lessons From the Re-Migration

1. Explicit Interface Contracts

2. Exhaustive State Handling

3. Browser Compatibility Safeguards

4. Form Data Safety

Conclusion

Code Mind, Beginners Mind

I. Syntax and Emptiness

II. The Simplicity of Understanding

III. Version Control and Non-Attachment

IV. Bugs as Teachers

V. Architecture and the Space Between

VI. Collaboration and the Ego

VII. Refactoring and Renewal

VIII. Always Returning

Backbone for React Devs: The Song Remains the Same

Why should you care?

Imperative vs Declarative

State and Components vs MVC

Code Navigation

Conclusion

React Server Components Without a Framework

Server Components are Cool! Frameworks may or may not be.

A tool for creating Server Components without a Framework

What's "Next" and how you can help

Space Themed Site with Mini Game!

What I built

Category Submission:

App Link

Screenshots

Description

Link to Source Code

Permissive License

Background

How I built it

Additional Resources/Info

Introducing Object Hooks: Mutable State for React 🤯