Structuring Large-Scale React & TypeScript Applications for Enterprise

How we keep our codebases scalable, maintainable, and developer-friendly at Arisecraft Tech.

React is notoriously unopinionated. Unlike frameworks like Angular or NestJS, React doesn't tell you how to structure your files, manage your state, or route your users. While this flexibility is great for prototyping, it can quickly lead to spaghetti code when building large-scale, enterprise-grade applications—like the complex B2B systems and billing engines we build at Arisecraft Tech.

Over time, we've developed a battle-tested approach to structuring our React and TypeScript applications. Here is a look at the principles we follow to ensure our codebases remain scalable and maintainable, even as the team and the product grow.

---

1. Feature-Driven Folder Structure

One of the most common mistakes in early React apps is grouping files by type (e.g., all components in a components folder, all hooks in a hooks folder). In a massive enterprise app, this means you are constantly jumping between five different directories just to understand how the "Invoice" feature works.

Instead, we prefer a feature-driven architecture (colocation). We group files by the domain or feature they belong to.

1src/
2├── components/       # Global, highly reusable UI components (Buttons, Modals)
3├── features/         # Feature-specific modules
4│   ├── invoices/
5│   │   ├── api/      # API calls related to invoices
6│   │   ├── components/ # Invoice-specific components
7│   │   ├── hooks/    # Custom hooks for invoice logic
8│   │   ├── types/    # TypeScript interfaces for invoices
9│   │   └── index.ts  # Public API for this feature
10│   └── customers/
11├── pages/            # Page-level components that tie features together
12├── lib/              # Third-party library configurations (Axios, third-party wrappers)
13└── utils/            # General helper functions (date formatting, math)

By enforcing an index.ts export for each feature, we treat them as independent modules. This creates strict boundaries and prevents tight coupling across the app.

2. Leveraging TypeScript as a Safety Net

TypeScript is non-negotiable for large applications. However, simply renaming .js files to .ts and using any everywhere defeats the purpose.

We enforce strict typing across our B2B applications. When dealing with complex financial transactions and billing data, a single type error can lead to a broken UI or, worse, a corrupted data state.

Best Practices We Follow:

• Strict Mode: strict: true in tsconfig.json is always on. No exceptions.
• Generate Types from the Backend: Whenever possible, we share types between our Node.js backend and React frontend. If the server’s Invoice model changes, the frontend build should fail immediately if it isn't updated.
• Avoid any: We use unknown if a type is truly dynamic, forcing the developer to perform type-checking before using the variable.

3. Rethinking State Management

A few years ago, Redux was the default answer to state management. Today, we divide state into three distinct categories and handle them differently:

1. Server State (Data fetching): Data that lives on the server (e.g., a list of users, quotation data). We use libraries like React Query or SWR for this. They handle caching, background refetching, and loading/error states automatically. This eliminates 80% of what we used to put in Redux.
2. Global UI State: Data that needs to be accessed anywhere but isn't tied to the database (e.g., dark mode toggle, an open navigation drawer, auth state). For this, React Context or lightweight libraries like Zustand are perfect.
3. Local Component State: Ephemeral state like a controlled form input or a dropdown toggle. This belongs in useState or useReducer right inside the component.

By isolating Server State from Global UI State, our application remains incredibly fast and much easier to debug.

4. Separation of Logic and Presentation

Large React components can easily bloat to 500+ lines if you mix API calls, complex business logic, and JSX markup. We mitigate this by heavily utilizing Custom Hooks.

If a component needs to fetch data, calculate totals, and manage multiple sub-states, we abstract that logic into a hook.

Instead of this:

1const InvoicePage = () => {
2  const [data, setData] = useState();
3  // ... 50 lines of fetching logic, formatting, and calculations
4  return <div>{/* UI */}</div>;
5};

We do this:

1const InvoicePage = () => {
2  const { invoiceData, calculateTaxes, isLoading } = useInvoiceDetails(invoiceId);
3  
4  if (isLoading) return <Spinner />;
5  
6  return <InvoiceView data={invoiceData} onTaxCalculate={calculateTaxes} />;
7};

This keeps the component purely focused on presentation (the "Dumb Component") while the hook handles the heavy lifting (the "Smart Logic").

5. Standardizing the UI with a Design System

When building B2B software, consistency is key. We never write inline styles or scatter custom CSS classes across feature files. Instead, we invest time upfront in building a robust set of base components in our global components/ directory (e.g., <Button>, <Modal>, <DataTable>).

Everything else in the app is built by composing these base components. Whether we are using TailwindCSS, styled-components, or Vanilla CSS modules, having a single source of truth for design tokens (colors, spacing, typography) ensures the app feels premium and cohesive.

Conclusion

Structuring a large-scale React and TypeScript application requires discipline. By organizing by feature, enforcing strict types, properly categorizing state, and separating logic from presentation, you can build a codebase that is not only scalable but genuinely enjoyable to work in.

At Arisecraft Tech, these principles allow us to build complex, high-performance systems with confidence. If you're starting a new enterprise project, try adopting these patterns—your future self will thank you.