How to Simplify your Codebase

Large, legacy codebases often suffer from tangled dependencies, lack of modular boundaries, and monolithic "barrel" files that bundle together many modules. This makes the codebase difficult to understand, modify, and scale. In this talk, we'll explore strategies for "untangling the barrel" and simplifying a complex codebase to prepare it for migration to a monorepo architecture.

We'll cover techniques for:

- Analyzing your code for cyclic dependencies

- Tools to help refactoring the code

- Establishing coding guidelines and automation to control codebase complexity going forward

This talk has been presented at Node Congress 2025, check out the latest edition of this JavaScript Conference.

FAQ

'Crappy texture' refers to a problematic software architecture where there are no clear module boundaries, leading to code repetition, cluttered flows, and difficulties in making changes and refactoring.

Common signs include unclear module boundaries, code repetition, cluttered flows, slow developer velocity, difficulty in refactoring, and unexpected bugs.

Reasons include time pressure, changing requirements, incomplete understanding, technological changes, and human factors where developers lack perfect knowledge.

Dead code increases cognitive load, creates confusion, adds maintenance burden, and can negatively impact performance and application size.

A barrel file is an index file from which multiple functions are exported, simplifying imports but potentially increasing import surface and cyclic dependencies.

Tools like linters can help identify unused code, but for exported functions, programmatic approaches using tools like TypeScript's AST and TSmorf can be more effective.

MADGE is a tool that can find circular dependencies in a codebase and generate call graphs to help visualize dependencies.

A good layered architecture ensures modularity, clarity, faster development, easier maintenance, and scalability.

Improving architecture can involve eliminating dead code, breaking cyclic dependencies, and reducing reliance on barrel files for clarity and efficiency.

Cyclic dependencies cause tightly coupled code, increase complexity, make refactoring difficult, and can lead to runtime errors.

Tally Barak

35 min

17 Apr, 2025

Comments

Video Summary and Transcription

This talk focuses on the challenges of working with large codebases, such as unclear module boundaries, code repetition, and cluttered flows. Dead code is identified as a major problem that adds clutter and cognitive load to developers. The abstract syntax tree (AST) is introduced as a tool for systematically accessing code. TSmorf is recommended for finding and removing dead code by traversing and manipulating the AST. Cyclic dependencies are discussed as another issue, and MADGE is suggested as a tool for identifying and resolving circular references. Barrel files are presented as a method for organizing code and resolving cyclic references. The process of replacing imports and removing empty calls is explained. The key takeaways include the importance of a good layered architecture, eliminating dead code, breaking cyclic dependencies, and reducing barrel files.

Video transcription and chapters available for users with access.