Taming the Monolith: Refactoring a 7,558-Line Constants File

The Problem with the Global Constants File

Every project starts small, clean, and full of promise. Then, somewhere along the line, a decision is made: "Let's put all our constants in one place." It seems reasonable at first. You need a few API endpoints, some magic numbers, maybe a list of status codes. Before you know it, that constants.js or enums.ts file becomes a black hole, sucking in every string, number, and array that isn't directly tied to component state or a database schema. Eventually, you're staring at a 7,558-line behemoth, and even searching for a specific value feels like a archaeological dig.

This isn't just an aesthetic issue; it's a genuine productivity killer. IDEs struggle, merge conflicts become a nightmare, and the cognitive load of understanding what's even in that file is immense. More importantly, it signals a deeper problem: a lack of clear ownership and domain separation. When everything lives together, nothing truly belongs anywhere.

Why Monolithic Constant Files Happen

It's easy to point fingers, but monolithic constant files often arise from good intentions. The desire for consistency and single source of truth is strong. Developers want to avoid duplicating values and ensure that if a specific string changes, it changes everywhere. The constants.ts file becomes the designated dumping ground for anything that feels static.

Another factor is the lack of a clear alternative or guidance. When you're moving fast, it's easier to append to an existing file than to design a new module or namespace. This is especially true in larger teams where different features are developed in parallel, each contributing their own set of "constants" without much thought to overall structure. Over time, the file becomes a legacy artifact that no one dares to touch, fearing the unknown repercussions of moving or deleting something that might be used by everything.

Strategy for Deconstruction

My approach to tackling a monster like this is multi-faceted, focusing on domain-driven separation, type safety, and enforced modularity. Simply splitting the file into constants1.ts, constants2.ts isn't enough; you need a meaningful organization that reflects your application's architecture. The goal is to make future developers think twice before adding a new value to a generic constants file.

1. Identify Natural Domains

Start by categorizing the constants. Are there values related to user authentication? E-commerce products? UI states? API endpoints for a specific service? You'll find natural groupings emerge quickly. For instance, all product-related constants (max quantity, discount thresholds, product categories) should live together.

// Before: A small slice of the giant constants.ts
export const AUTH_TOKEN_KEY = 'authToken';
export const USER_ROLES = { ADMIN: 'admin', EDITOR: 'editor', VIEWER: 'viewer' };
export const API_BASE_URL = 'https://api.example.com/v1';
export const PRODUCT_MAX_QUANTITY = 100;
export const PRODUCT_STATUS_AVAILABLE = 'available';
export const ORDER_STATUS_PENDING = 'pending';
export const ORDER_STATUS_SHIPPED = 'shipped';
export const UI_MODAL_Z_INDEX = 1000;
export const UI_SIDEBAR_WIDTH_PX = 250;

2. Create Domain-Specific Modules

Once you have your categories, create dedicated files or directories for them. For example, src/constants/auth.ts, src/constants/products.ts, src/constants/api.ts, src/constants/ui.ts. This immediately makes the codebase more navigable. When you need an authentication-related constant, you know exactly where to look.

// After: src/constants/auth.ts
export const AUTH_TOKEN_KEY = 'authToken';
export const USER_ROLES = { ADMIN: 'admin', EDITOR: 'editor', VIEWER: 'viewer' } as const;

// After: src/constants/products.ts
export const PRODUCT_MAX_QUANTITY = 100;
export const PRODUCT_STATUS = {
  AVAILABLE: 'available',
  OUT_OF_STOCK: 'out_of_stock',
  DISCONTINUED: 'discontinued'
} as const;

// After: src/constants/api.ts
export const API_BASE_URL = 'https://api.example.com/v1';
export const API_ENDPOINTS = {
  USERS: `${API_BASE_URL}/users`,
  PRODUCTS: `${API_BASE_URL}/products`,
  ORDERS: `${API_BASE_URL}/orders`
};

// After: src/constants/ui.ts
export const Z_INDEX_LEVELS = {
  MODAL: 1000,
  OVERLAY: 900,
  HEADER: 800
} as const;
export const SIDEBAR_WIDTH_PX = 250;

Notice the as const assertion. This is crucial in TypeScript for freezing object literals and inferring literal types, which gives you much stronger type checking when using these constants. It prevents accidental mutation and ensures that, for example, USER_ROLES.ADMIN is typed as 'admin' instead of just string.

3. Embrace enums and types where appropriate

Not everything is a simple string constant. Sometimes, a set of related values is better represented by a TypeScript enum or a literal union type. This provides compile-time checks and better readability. For example, instead of separate ORDER_STATUS_PENDING, ORDER_STATUS_SHIPPED, you can define an OrderStatus enum.

// Before: More constants in the monolith
export const ORDER_STATUS_PENDING = 'pending';
export const ORDER_STATUS_SHIPPED = 'shipped';
export const ORDER_STATUS_DELIVERED = 'delivered';
export const ORDER_STATUS_CANCELLED = 'cancelled';

// After: src/types/order.ts (or src/enums/order.ts)
export enum OrderStatus {
  PENDING = 'pending',
  SHIPPED = 'shipped',
  DELIVERED = 'delivered',
  CANCELLED = 'cancelled'
}

// Usage elsewhere:
function updateOrderStatus(orderId: string, status: OrderStatus) {
  // ...
  if (status === OrderStatus.DELIVERED) {
    // ...
  }
}

Enums make intent clearer and prevent typos. If you prefer not to use TypeScript enums (they have some runtime quirks), a union of string literals with as const works just as well and is often preferred in modern TypeScript codebases for better tree-shaking and type inference.

// Alternative using a union type and const assertion
export const OrderStatuses = ['pending', 'shipped', 'delivered', 'cancelled'] as const;
export type OrderStatus = typeof OrderStatuses[number]; // 'pending' | 'shipped' | 'delivered' | 'cancelled'

// Usage elsewhere:
function updateOrderStatus(orderId: string, status: OrderStatus) {
  // ...
  if (status === 'delivered') { // Type-safe comparison
    // ...
  }
}

4. Co-locate with Related Code

Sometimes, a "constant" is so tightly coupled to a specific component or utility function that it makes more sense to live alongside that code. If UI_MODAL_Z_INDEX is only ever used by your Modal component, why should it be in a global constants/ui.ts file? Move it into src/components/Modal/constants.ts or even directly into Modal.tsx if it's truly a private detail.

This is a subtle but powerful shift in thinking. Instead of centralizing all constants, you're asking: "Where does this constant logically belong in the context of the code that uses it?" This improves locality of reference and reduces the mental overhead of jumping between files.

5. Leverage Configuration Files for Environment-Dependent Values

API keys, base URLs that change between development and production, feature flags – these aren't truly "constants" in the immutable sense. They are configuration values. They belong in environment variables (.env files), config directories, or a dedicated configuration management system. Separating these concerns ensures that your application behaves correctly across different environments without recompilation or manual code changes.

This is a critical distinction. A PRODUCT_MAX_QUANTITY is a business rule constant; an API_KEY is a deployment configuration. Mixing them in the same constants.ts file conflates these very different concepts.

The Trade-offs and Gotchas

This refactoring isn't a silver bullet. The immediate downside is the sheer amount of work involved. A 7,558-line file means thousands of usages spread across the codebase. You'll need to use a robust IDE search-and-replace, potentially with regex, and be prepared for a lot of manual verification and fixing imports. This is a task for a dedicated sprint, not a side project.

Another point of friction can be team buy-in. If your team is used to the monolithic constants.ts file, there might be resistance to a more distributed approach. It requires a shift in mental model and a commitment to maintaining the new structure. You'll need to clearly articulate the benefits: improved maintainability, reduced merge conflicts, better discoverability, and enhanced type safety.

Finally, be mindful of over-segmentation. While splitting is good, don't go overboard. Creating a new file for every single constant negates the benefits of grouping. Find the right balance between granularity and logical cohesion. The goal is to make things easier to find and understand, not to create a sprawling directory of single-line files.

Wrapping up

Refactoring a monster constants file is more than just code cleanup; it's an exercise in applying domain-driven design principles to the most basic building blocks of your application. It forces you to think about what data truly belongs together and why. By separating concerns, leveraging TypeScript's advanced type features, and co-locating values with their consumers, you'll end up with a codebase that's significantly easier to navigate, maintain, and extend.

Your next step: Pick the largest, most unwieldy constants or utils file in your current project. Spend 15 minutes mapping out its logical domains on a piece of paper or in a README.md. Don't even write code yet – just the act of categorizing will reveal the underlying structure you can leverage for a cleaner future.