One file is imported by 31% of Grafana. It is not a god object
DEV Community

One file is imported by 31% of Grafana. It is not a god object

TL;DR: A god object is a class or file with lots of logic and many unrelated responsibilities. A file with many importers is not one by default.

Grafana's most-imported file, packages/grafana-data/src/index.ts, is imported by 3,178 of 10,090 production files (31%) and contains no logic, only re-exports.

In the median repo among 195 public repos with 1,000+ GitHub stars, one hub file is imported by 20% of production files, and in 68 repos (35%) a single file is imported by a quarter or more of the codebase.

Numbers come from repowise's index of 195 public repos with 1,000+ GitHub stars (November 2026), plus fresh clones of Grafana, Keycloak and Docker Compose on 10 November 2026.

In Grafana, one file is imported by 3,178 of its 10,090 production source files. That is 31% of the codebase depending on packages/grafana-data/src/index.ts.

If you sort any dependency graph by fan-in, a file like this lands on top, and the usual reaction is "that's our god object, we should split it". So I opened it. It is 986 lines long and contains no logic at all:

export { DataFrameView } from './dataframe/DataFrameView';
export { type FieldWithIndex, FieldCache } from './dataframe/FieldCache';
export { type MutableField, MISSING_VALUE, MutableDataFrame } from './dataframe/MutableDataFrame';
...

Many importers and too many responsibilities are two different problems. Telling them apart takes four checks, shown here with numbers from 195 popular repos and three hubs I checked by hand.

How common are hub files in popular repos?

I looked at file-to-file imports between production files (tests, generated and vendored code excluded) in 195 public repositories with 1,000+ GitHub stars. The "hub" is the single file imported by the most other files.

In the median repo, the hub is imported by 20% of all production files. The top 1% of files receive 17% of all import edges. In 68 repos (35%), one file is imported by a quarter or more of the codebase.

  • All 195 - 20%
  • TypeScript 52 - 17%
  • Python 51 - 18%
  • Go 22 - 27%
  • Rust 15 - 21%
  • JavaScript 13 - 15% (indicative, small group)

Part of Go's lead is structural: a Go file imports a package, never a single file, so every file in a widely used package picks up all of that package's importers.

So a hub is normal. Reading down the list of top hubs, the same few kinds keep coming back: package entry points (index.ts, lib.rs, __init__.py), shared type and interface files, loggers, settings objects, and "context" types passed through every call.

Django's is django/conf/__init__.py, the module behind from django.conf import settings. Repomix's is src/shared/logger.ts. Neither is a design problem.

How do you tell a hub file from a god object?

A god object is one class or file that knows too much and does too much: lots of logic, many unrelated responsibilities, and a reason to change every time any feature changes. High fan-in is a symptom it often has, but plenty of healthy files have it too.

Four checks separate the two:

  1. What is in it. Re-exports, declarations, or real logic?
  2. How wide is it. How many symbols does it expose?
  3. How often does it change, and why. One kind of change, or every kind?
  4. What do importers take from it. One or two names each, or big different slices?

Here are the three hubs I checked, each on a fresh clone from 2026-11-10: Grafana grafana-data/src/index.ts, Keycloak KeycloakSession.java, Docker Compose pkg/api.

  • Importers (my count): 3,152 non-test TS files, 1,744 non-test Java files, 126 non-test Go files (19 of 43 packages)
  • What is in it: 912 re-exported names, 0 lines of logic / 1 interface, ~39 methods / 921-line api.go: interfaces and options structs
  • Commits, last 90 days: 9 / 1 / 12 (api.go)
  • What importers take: median 2 names per file / mostly getContext() and getProvider() / median 3 names per file, 144 distinct names in use

None of these is a god object. They are three different kinds of hub, and each one has a different thing worth watching.

Kind 1: the package entry point (Grafana)

grafana-data/src/index.ts is the public face of the @grafana/data package. Application code writes import { ... } from '@grafana/data' and the file forwards each name to the module that defines it:

$ grep -oE "from '[^']+'" packages/grafana-data/src/index.ts | sort -u | wc -l
180

180 source modules, 178 export { ... } from statements carrying 912 names, plus 4 export * lines.

On the importer side, I counted which names each file takes (a small Python script over every non-test .ts / .tsx file):

  • files importing named exports from @grafana/data: 3152
  • distinct names used: 678
  • median names per importing file: 2
  • files using 1-3 names: 2538
  • 1329 GrafanaTheme2
  • 321 DataFrame
  • 301 SelectableValue
  • 194 FieldType
  • 171 Field
  • 161 TimeRange
  • ...

The typical importer takes two names. GrafanaTheme2 alone shows up in 1,329 files, because almost every component styles itself with the theme.

9 commits touched index.ts in the last 90 days ("Panels: Support panel notices and custom status actions", "Transformations: Allow setting static refIDs per transformation", ...). Together they added 29 lines and removed 2: eight added exports for a new feature, one moved an export to a new directory.

So the file changes often, but always for the same reason: the package's public API grew. That is all you need to classify it: a package entry point, not a god object.

What a barrel like this costs is a separate question, and it gets its own post later in this series.

Kind 2: the core interface (Keycloak)

In Keycloak, server-spi/.../models/KeycloakSession.java is imported by more files than anything else. For Java, rg gets you the full ranking in one line:

$ rg -oN --no-filename -g '*.java' -g '!**/src/test/**' -g '!testsuite/**' \
'^import (org\.keycloak\.[\w.]+);' -r '$1' | sort | uniq -c | sort -rn | head -5
1744 org.keycloak.models.KeycloakSession
926 org.keycloak.models.RealmModel
528 org.keycloak.models.UserModel
498 org.keycloak.models.ClientModel
484 org.keycloak.models.KeycloakSessionFactory

That is 1,744 of 6,030 non-test Java files. The file is a 272-line interface with about 39 methods: realms(), users(), clients(), keys(), a transaction manager, and a generic getProvider(Class<T>).

A long method list on a class everyone imports is the classic god object picture, so check 4 matters most. A rough count of calls on variables named session across the main code:

$ rg -o --no-filename -g '*.java' -g '!**/src/test/**' -g '!testsuite/**' \
'\bsession\.(\w+)\(' -r '$1' | sort | uniq -c | sort -rn | head -6
1480 getContext
806 getProvider
280 users
275 getKeycloakSessionFactory
126 realms
120 identityProviders

Callers mostly ask the session for the current request context or for a provider. The interface holds no logic, and its one implementation, DefaultKeycloakSession, is 445 lines. It is the door to the providers that do the work (user storage, realm storage, keys, themes), each behind its own SPI.

The generic getProvider(Class<T>) is what keeps it stable: a new feature registers a provider instead of adding a method. The file was touched by 3 commits in the last year and 1 in the last 90 days.

What to watch here is method count. As long as new capabilities go through the generic lookup, a hub like this can have thousands of importers and stay small.

Kind 3: the shared contract package (Docker Compose)

In the dataset, Compose's hub is pkg/api/context.go, imported by 130 of 194 production files (67%), the highest hub reach of any repo above 20k stars. That file is 32 lines and declares one three-method interface.

Go code imports a package, though, so "which file" is the wrong question there. Count packages with go list:

$ go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./... \
| sed 's#github.com/docker/compose/v5#compose#g' | tr ' ' '\n' \
| awk '/:$/{next} /^compose/' | sort | uniq -c | sort -rn | head -5
19 compose/pkg/api
9 compose/internal/naming
8 compose/pkg/utils
7 compose/internal/concurrency
6 compose/internal

19 of the other 43 packages import pkg/api, and at the file level 126 of 239 non-test Go files do. The weight is in api.go: 921 lines with 57 type declarations, mostly one options struct per command (UpOptions, DownOptions, BuildOptions, ...) plus the Compose service interface. Next to it sit the progress event types, label names and error values.

It changes a lot (12 commits to api.go in 90 days), because new command flags land in its options structs. Importers also take different things from it. Across the non-test Go files, 144 different api. names are in use, and the median importing file uses 3. The most common are the progress event types (api.Resource, api.Done, api.Working), then label constants and container summaries. That spread is check 4 pointing at more than one job in one package.

This is the one with the broadest surface of the three, and the Compose maintainers already did the thing I would suggest. In October, PR #14322 split Compose into focused interfaces:

type Compose interface { Lifecycle Inspector ImageManager Runner Watcher ProjectLoader }

The commit message says the method set of Compose is unchanged, and two callers that only load a project now depend on api.ProjectLoader instead of the whole service. The interface change itself touched 3 files (+70 and -40 lines). The PR, merged 2026-10-12, also regenerated a 626-line mock, for 4 files and +696 / -40 in total. Nothing broke for existing importers, and new code can ask for the narrowest interface it needs.

How do you find the most-imported file in your codebase?

You do not need a full graph tool for a first look. One command per ecosystem:

TypeScript / JavaScript with relative imports, using madge (it only parses the source):

npx madge --json --extensions ts src > graph.json
node -e ' const g = require("./graph.json"), n = {}; for (const deps of Object.values(g)) for (const d of deps) n[d] = (n[d] || 0) + 1; const files = Object.keys(g).length; Object.entries(n).sort((a, b) => b[1] - a[1]).slice(0, 5) .forEach(([f, c]) => console.log(c, Math.round(100 * c / files) + "%", f));'

On repomix (commit 758c3d71), run over the 147 TypeScript files under src/, this prints:

59 40% shared/logger.ts
38 26% config/configSchema.ts
26 18% shared/errorHandle.ts
22 15% core/file/fileTypes.ts
20 14% shared/types.ts

Python, counting each module once per file:

$ rg -oN -g '*.py' '^\s*from (django[\w.]*) import' -r '$1' django \
| sort -u | cut -d: -f2 | sort | uniq -c | sort -rn | head -3
170 django.conf
156 django.db
155 django.core.exceptions

Java: the rg line from the Keycloak section, with your own package prefix. Go: the go list pipeline from the Compose section, with your module path.

Workspace packages imported by name (like @grafana/data) do not resolve in madge without the workspace installed, so for those, count the bare import: rg -l "from '@grafana/data'" -g '*.{ts,tsx}' | wc -l.

What to do with each kind

  • Package entry point / barrel - Only re-exports, importers take 1 to 3 names - Keep it as the public API. Inside the package, import the defining module directly
  • Core interface or session object - Few methods used heavily, rare changes - Keep new features behind a generic lookup so the method list stops growing
  • Shared contract package - Many types, changes with every feature - Split the big interface by role and let callers depend on the narrowest one
  • Real god object - Lots of logic, frequent changes for unrelated reasons, importers each use a different slice - Group importers by which symbols they use and extract each group's slice into its own module

The last row is the only one where "split the hub" is the right reflex. The useful work is check 4: once you know which importers use which parts, the split lines usually draw themselves.

Fan-in and fan-out together, plus what the file contains, is a better test than fan-in alone. This post on building a dependency graph covers how both are computed and how PageRank ranks load-bearing files. You can also open Grafana's architecture view and follow the import edges between its packages.

If you run one of these on your repo, I would like to know what kind of file comes out on top. My guess is a logger or a types file.

How I got these numbers

The cohort is 195 of the most-starred public repositories indexed on repowise (1,000+ GitHub stars each, 253,688 production source files, November 2026). "Hub reach" is the share of a repo's production files that import its most-imported production file; the hub file finding in the code health report has the cohort-wide figures.

Each repo is measured at its own latest index between May and November 2026, so the figures are a snapshot per repo. The Grafana headline (3,178 of 10,090) is from its 2026-10-28 index. A fresh repowise init on Grafana at commit 12c49a4d (2026-11-10) gave 3,148 of 10,164, still 31%.

Keycloak, Compose, Django and repomix counts in the sections above come from local clones on 2026-11-10 (Keycloak cbe2bc82, Compose fde2a0a, Grafana 12c49a4d, Django 6a8248f, repomix 758c3d71) with ripgrep 15.1.0, Go 1.26.10 and madge 8.0.0, counting non-test files only. Commit counts are from the GitHub API for each file path since 2026-08-12 (90 days) and 2025-11-10 (one year).

FAQ

What is a god object in programming? A god object is a single class or file that holds too much logic and too many unrelated responsibilities, so almost every feature change has to touch it. High fan-in is a common symptom, but files like Grafana's @grafana/data entry point have thousands of importers and no logic at all.

Why is the god object an anti-pattern? Because every change goes through it. A file that changes for many unrelated reasons, and whose importers each use a different slice of it, couples features that should be independent and turns merges and reviews into a bottleneck.

What is a god class? A god class is the same anti-pattern at class level: one class with a long list of methods co

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.