From Frameworks to Explicit Code: An Engineer's Shift

In the source article, the author describes a journey from using popular frameworks like Vue and Angular to employing a custom library called @relax.js/core. This change stems from a desire to better support coding agents—automated assistants that help in writing code.

Why Move Away from Vue and Angular?

The author notes that while coding agents are familiar with Vue and Angular, they often struggle with the custom components provided by @relax.js/core. This is primarily because agents rely heavily on patterns and practices they have seen extensively during training. When these agents encounter a new pattern, like those in @relax.js/core, they tend to carry over assumptions from previous frameworks, leading to incorrect implementations.

One of the primary challenges in using popular frameworks is the hidden complexity and runtime-only bugs that can occur. Issues like delayed watch executions in Vue or change detection problems in Angular are not easily observable by agents, as they cannot interact with browsers or debug in real-time. This results in agents making speculative changes rather than addressing the root cause of a problem. For example, in Vue, a watch function might trigger one tick later than expected, displaying outdated information. Similarly, Angular might fail to run change detection if updates occur outside its zone, leading to discrepancies between the model and the view. These are not trivial issues and often require deep debugging skills and understanding of the framework's internal mechanics to resolve.

The Benefits of Explicit Code

The author argues that explicit code, where updates occur directly in response to changes, minimizes the class of bugs caused by framework abstractions. For instance, directly updating a text content with this.nameSpan.textContent = user.name ensures that the change is visible and verifiable in the same file, making it easier for both humans and agents to understand and maintain the code.

Explicit code offers three major advantages:

• Failure locality: Bugs manifest in the same file as the symptoms, avoiding complexities introduced by schedulers or dependency graphs. This means the developer can quickly locate and resolve issues without delving into the framework's internals.
• Greppability: The ability to search for specific events or functions in the codebase makes it easier for agents to navigate and understand the connections within the code. For instance, searching for an event handler in a template can immediately show all its invocations and definitions, streamlining debugging and code comprehension.
• Reviewability: Changes are more transparent, allowing for straightforward code reviews where the effects of a change are immediately apparent. The diff between code versions clearly indicates what the code intends to do, reducing ambiguity and potential errors during code reviews.

What Was Built to Support This Approach

To make @relax.js/core effective for coding agents, the author highlights the need for additional tools and practices:

• Skills, not docs: The library includes skills files that agents use to avoid common mistakes, rather than relying solely on documentation. These skills are concise, focusing on the pitfalls an agent might encounter, thus improving the agent's performance by preemptively addressing potential errors.
• Errors over silence: Quiet failures, such as unresolved template paths, are transformed into errors that agents can detect and handle. This proactive error reporting ensures that agents can flag issues that might otherwise go unnoticed until runtime.
• A custom checker: A tool called npx @relax.js/core check verifies template expressions against TypeScript types, bridging the gap with Angular's template type-checking. This checker provides immediate feedback on potential type mismatches, reducing runtime errors and improving code reliability.

By providing these tools, the author ensures that coding agents can work effectively with @relax.js/core, reducing the need for human intervention and improving the accuracy of agent-generated code. The comprehensive test suite features functions like mount(), flush(), and fakeServer(), allowing agents to validate their work through automated testing frameworks like vitest, rather than relying on manual verification.

When Frameworks Still Make Sense

Despite the benefits of explicit code, the author acknowledges scenarios where established frameworks like Vue or Angular still hold an advantage. If the agent's first-draft correctness is crucial, or if the application requires server-side rendering (SSR) or manages deeply interdependent state, the complexity of a framework's reactive engine might be justified. In these cases, the frameworks' capabilities outweigh the potential pitfalls of their abstractions. For example, handling deeply nested state changes across multiple components can be more manageable with a reactive framework like Vue or Angular, which automatically propagates changes through the component tree.

Implementing Explicit Code in Your Projects

If you're maintaining a production codebase and are considering moving away from established frameworks, here are some practical steps to implement explicit code effectively:

• Assess your project's needs: Determine if your application would benefit from more explicit coding practices, especially if it's a small-to-medium single-page application (SPA) where human review of agent-generated code is feasible. Evaluate the complexity of your current framework and if it adds unnecessary overhead to your project.
• Experiment with custom libraries: Consider using or creating small libraries like @relax.js/core that offer more control over the code's behavior and reduce hidden complexities. Start with non-critical parts of your application to gauge the effectiveness of this approach.
• Leverage TypeScript: Use TypeScript to enhance type-checking capabilities, catching errors early in the development process. This can substantially reduce runtime errors and improve the overall robustness of your code.
• Invest in tooling: Develop or integrate tools that help agents better understand and work with your codebase, such as custom checkers or skills files. These tools can automate mundane tasks and allow developers to focus on more complex issues requiring human insight.

Limitations of Explicit Code

While explicit code reduces certain types of bugs and improves agent collaboration, it is not without trade-offs. Here are some limitations to consider:

• Scalability: Explicit code might become cumbersome in large applications with complex state management needs. As the application grows, maintaining explicit updates for numerous components can become labor-intensive and error-prone.
• Learning curve: Developers familiar with frameworks may need time to adjust to new coding practices. Transitioning from a framework-centric approach to explicit coding requires a shift in mindset and understanding of different coding paradigms.
• SSR limitations: If server-side rendering is a requirement, explicit code may not provide the necessary support out-of-the-box. Frameworks like Next.js or Nuxt.js provide built-in SSR capabilities that are challenging to replicate with a custom solution.

As with any technology decision, it's crucial to weigh the benefits and drawbacks in the context of your specific project requirements. Consider conducting a pilot project to understand the implications of moving to explicit coding before fully committing to the transition.