Learn Remix - Architecture & Maintainability

#Introduction

Small applications are easy to maintain because everyone remembers all the code. The problem is, applications rarely stay small. Without deliberate architecture, folders become messy, files become huge, and every new change feels scary. Episode 18 is an architecture lesson for Remix.

The good news: Remix's route structure gives you a solid foundation — every URL has its own file. Your job is simply to extend that pattern to the code that supports routes — data functions, components, and shared utilities — with rules that are consistent and easy to understand.

Episode 18 covers folder structure, feature module organization, shared utilities with typed contracts, and practices for keeping loaders and actions lean.

#Folder Structure for a Remix Application

#The Feature-Based Pattern

Instead of piling all files into one folder, separate them by responsibility. A common pattern in healthy Remix projects:

app/
  routes/            <- file route, kurus dan fokus
  components/        <- komponen yang dipakai lintas route
  lib/
    db.server.ts     <- akses database, hanya server
    session.server.ts
    validators.ts    <- schema validasi
  modules/
    posts/
      post.model.ts
      post.service.ts

Files ending in .server.ts are guaranteed to never be sent to the client. The file name is both a contract and a safety net — separate server code from client code explicitly.

#Thin Routes

An ideal route file is thin: it calls functions from modules instead of containing all the logic. A thin route means the logic lives somewhere it can be tested and reused, not inside the route file.

#Feature Modules and Route Organization

#One Feature, One Module

Group code by feature. For the "posts" feature, put the model, service, and feature-specific components in the modules/posts folder, while the route stays just the URL entry point. Changes to one feature don't bleed into another because the folder boundaries are clear.

#Leveraging Nested Routes

Nested routes aren't only about layout — they're also architectural boundaries. A parent route loads shared data; child routes load specific data. A good route hierarchy makes the data flow follow the UI hierarchy, so it's easy to trace. The route structure is an architecture map you can read from file names.

#Shared Utilities and Typed Contracts

#Clear Shared Utilities

Utilities used in many places — date formatting, slugs, pagination — go in lib with descriptive names. Avoid secret utilities used by only one file; put those next to their users.

#Typed Contracts with TypeScript

TypeScript provides contracts between modules: the data types a loader returns must match what components receive. With correct types, refactoring is safe because the compiler catches mismatches early.

Shared types for loader and component

export type Post = {
  id: string;
  judul: string;
  konten: string;
};
 
export async function loader() {
  const posts: Post[] = await ambilSemuaPost();
  return { posts };
}

The Post type is defined once and used by the loader, components, and tests. This contract prevents inconsistent data from running through the application.

#Zod for Runtime Contracts

TypeScript types disappear at runtime. For data that comes from outside — forms, APIs, databases — Zod provides validation and type inference in one. The Zod schema and TypeScript type are defined in one place and used across many layers. It's a runtime and compile-time contract at once.

#Keeping Loaders and Actions Maintainable

#One Responsibility per Function

A long loader usually mixes several things: authentication, validation, querying, transformation. Split it into small, testable functions. Small functions with a single responsibility are easier to test and change without side effects.

#Consistent Shared Helpers

Repeating patterns — reading a session, checking access, parsing a form — become helpers in lib. The authentication guard from episode 11 can be turned into a requireUser(request) used by every route. One well-tested helper beats logic copied over and over.

#Living Documentation

Good code explains itself, but important decisions deserve to be written down. A per-module README that explains why, not what, helps new team members. Communicating architecture through structure and names outlives separate documents.

#Review as the Architecture Gate

Architecture doesn't maintain itself — it's guarded by team habits. Code review that watches folder boundaries, route file size, and type usage keeps the architecture on plan. Make a simple architecture checklist part of the review process: does this change add logic where it should belong, and are types used correctly.

#Conclusion

Episode 18 gives you an architecture that can grow: a feature-based folder structure with thin routes, feature modules that limit the blast radius of change, shared utilities with typed contracts, and habits that keep loaders and actions lean. Your code is now maintainable by anyone — including yourself six months from now.

The key takeaways:

• Separate code by responsibility: routes, components, lib, modules.
• Files ending in .server.ts are guaranteed to never enter the client bundle.
• Routes should be thin; logic moves into testable modules.
• TypeScript types become contracts between modules.
• Zod provides runtime validation and type inference at once.
• Shared helpers like requireUser reduce logic duplication.

In the next episode, episode 19, we'll discuss modern tooling and build automation — the Remix CLI, bundling and deploy targets, TypeScript and schema typing support, a CI/CD pipeline for Remix applications, and linting, formatting, and build validation. The architecture is tidy; now automate everything.