Code visualization developer tool / Jul 2026 - Present
CodeTown
A VS Code extension that transforms JavaScript and TypeScript codebases into explorable 2D towns, making file dependencies and codebase structure easier to understand before making changes.
VS Code Extension API / JavaScript / TypeScript / Dependency Graphs / Code Visualization
Highlights
- Parses project imports and exports into a dependency graph and transforms that graph into a spatial representation of the codebase.
- Represents files as buildings, groups of files as neighborhoods, and dependencies as roads, making relationships visible without tracing imports manually.
- Encodes dependency density into the visualization using single-, double-, and triple-lane roads based on the number of connections between areas of the codebase.
- Provides a navigable project map with a minimap, project/dependency overview, legend, and direct navigation from buildings to their corresponding source files in VS Code.
Problem
Understanding an unfamiliar codebase usually starts with a folder tree, search, and repeatedly following imports from one file to another.
That works for individual files, but it becomes difficult to understand the larger structure of a project: which areas are tightly connected, which files belong to the same subsystem, and how far a change might propagate.
For example, before modifying authentication logic, a developer may need to determine which files participate in that subsystem and what other parts of the project depend on them.
CodeTown turns those relationships into a spatial map so the structure can be understood visually before touching the code.
What I built
CodeTown analyzes a JavaScript or TypeScript project and builds a dependency graph from its import and export relationships.
That graph is transformed into a top-down town:
- Files become buildings.
- Groups of related files become neighborhoods.
- Import and export relationships become roads between areas.
- Larger groups of code occupy more space in the town.
- Stronger dependency relationships produce wider roads.
- Single-lane roads represent fewer than 10 connections.
- Double-lane roads represent 10-20 connections.
- Triple-lane roads represent more than 20 connections.
How it works
When CodeTown is opened for a repository:
- The extension scans the project's JavaScript and TypeScript files.
- It parses import and export relationships between those files.
- Those relationships are converted into a dependency graph.
- A layout algorithm determines how the resulting buildings, neighborhoods, and connections should be positioned in the 2D environment.
- Files are rendered as buildings and related groups of files form larger areas of the town.
- Dependency counts determine the visual strength of roads connecting those areas.
- The generated map can then be explored using the main town view, minimap, dependency information, and legend.
- Selecting a file in the visualization opens the corresponding source file inside VS Code.
Technical challenge
The hardest part of CodeTown is not parsing imports. It is producing a layout that remains understandable as the dependency graph becomes more complicated.
A codebase can contain many groups of files with relationships crossing between them. Simply drawing every connection produces a map that is technically accurate but difficult to read.
The layout therefore has to balance several competing goals: keeping related areas close together, leaving enough room for navigation, representing dependency relationships clearly, and preventing the generated town from becoming visually tangled as the project grows.
Different repositories produce very different graph structures, so the layout system requires different parameters and positioning strategies rather than relying on one fixed arrangement.
Why a town?
The town metaphor gives otherwise abstract dependency information a spatial representation.
Instead of remembering that several files scattered across a repository are strongly connected, a developer can see them occupying the same neighborhood. Instead of counting import relationships, the road connecting two areas communicates how strongly those parts of the project depend on one another.
The goal is not to replace the source tree or code editor. CodeTown provides another level of abstraction for answering a different question:
How is this codebase connected?
That becomes especially useful before modifying an unfamiliar subsystem, where understanding the surrounding dependencies can help identify which parts of the repository are likely to be affected.