Modularize Vanilla JS with AI

Web development can quickly spiral into a maze of complexity. While frameworks like React, Vue, and Next.js certainly have their merits, I firmly believe that a straightforward Flask app paired with HTML and Vanilla JS can deliver exactly what you need—with minimal fuss. One of the biggest advantages? A single deployment. Managing that on Railway is a breeze, as everything is neatly packaged together without the overhead of complex build processes.

Today, I’m sharing my two-step approach to keep your code both agile and maintainable.

I start by building out features in one simple file (usually index.js).

Once those features stabilize, I let my favourite AI coding assistant (Claude) help refactor the code into modular, purpose-driven components. 

This method ensures that you can prototype quickly while still setting yourself up for long-term success.

Step 1: Start Simple with One File

When you’re prototyping, it makes sense to keep everything together. Here’s an example of a simple index.js:

// index.js
const state = { count: 0 };

function render() {
  document.getElementById('counter').innerText = state.count;
}

function handleIncrement() {
  state.count += 1;
  render();
}

document.getElementById('incrementBtn').addEventListener('click', handleIncrement);
render();

This single-file approach lets you iterate quickly, focusing on features without worrying about the file structure.

Step 2: Modularize for Clarity and Scalability

Once your key features stabilize, it’s time to split your code into modules.

Simply ask Claude to modularize your main JS file into more manageable components.

Hey Claude, I’ve been developing a Vanilla JS project and have built out my features in a single file (index.js). 

Now, I want to refactor this file into a more modular structure for clarity and scalability. Please help me split the code into the following components:

index_state.js: Handles the application state (e.g., a simple counter) and functions to update it.
index_ui.js: Manages UI rendering based on the current state.
index_api.js: Contains functions for handling API calls.
index_utils.js: Includes any reusable utility functions, like formatting or cloning objects.

index_main.js: Serves as the entry point that imports the other modules, sets up event listeners, and initializes the app.
For each module, include clear comments and sample code. The modularized code should follow best practices, use ES modules (with import/export), and be easy to understand. 

Could you provide the content for each file?

This modularization breaks your code into logical chunks, each with a dedicated purpose. Here’s what a typical structure might look like in your static/js folder:

static/
└── js/
    ├── index_main.js    // Entry point, wiring all modules together
    ├── index_state.js   // Handles state management
    ├── index_ui.js      // Manages UI rendering
    ├── index_api.js     // Deals with API interactions
    └── index_utils.js   // Contains reusable utility functions

Purpose of Each Module

• index_main.js:
  This is your bootstrapping file. It imports all the other modules and sets up event listeners. Its job is to kick off the application and tie everything together.

• index_state.js:
  Here, you manage your application’s state. Whether it’s a counter, user data, or any dynamic element, this module holds your state and provides functions to update it.

• index_ui.js:
  Responsible for updating the UI, this module takes care of rendering changes based on state updates. It keeps your display logic separate from business logic.

• index_api.js:
  This module handles communication with external APIs. It encapsulates fetch calls, error handling, and data parsing, ensuring that your main application remains uncluttered by network code.

• index_utils.js (can also simply be utils.js for broader use):
  Reusable functions that don’t neatly belong in one of the above categories can be placed here. Whether it’s formatting dates, deep-cloning objects, or any helper function, utils.js keeps your code DRY (Don’t Repeat Yourself).

Example Code for Each Module

index_state.js

// index_state.js
export const state = { count: 0 };

export function updateCount(newCount) {
  state.count = newCount;
}

index_ui.js

// index_ui.js
import { state } from './index_state.js';

export function render() {
  document.getElementById('counter').innerText = state.count;
}

index_api.js

// index_api.js
export async function fetchData(url) {
  try {
    const response = await fetch(url);
    return await response.json();
  } catch (error) {
    console.error('API error:', error);
  }
}

index_utils.js

// utils.js
export function formatNumber(num) {
  return num.toLocaleString();
}

export function deepClone(obj) {
  return JSON.parse(JSON.stringify(obj));
}

index_main.js, which replaces index.js as main file

// index_main.js
import { state, updateCount } from './index_state.js';
import { render } from './index_ui.js';

function handleIncrement() {
  updateCount(state.count + 1);
  render();
}

document.getElementById('incrementBtn').addEventListener('click', handleIncrement);
render();

Referencing Your Main File in HTML

After modularizing, update your HTML to properly load your modules. Use the <script type="module"> tag to enable native module support:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Vanilla JS App</title>
</head>
<body>
  <div id="counter">0</div>
  <button id="incrementBtn">Increment</button>
  <!-- Main module file that ties everything together -->
  <script type="module" src="static/js/index_main.js"></script>
</body>
</html>

This ensures that the browser can handle your import and export statements without any hassle.

Why This Two-Step Approach Works

Starting with a single file lets you prototype rapidly without the overhead of structure. As your project grows, modularizing your code into distinct files makes your codebase easier to maintain, test, and extend. With each module having a clear, focused purpose, debugging becomes simpler and collaboration with others is smoother.

Moreover, a modular setup means fewer headaches during deployment on Railway when using your Flask app. It also plays nicely with tools like Claude or GitHub Copilot (Edit Mode) — editing targeted, shorter files is much faster and more efficient than sifting through a monolithic file.

By keeping it simple and modular, you maintain control over your development process and streamline your workflow. Embrace this approach to build efficient, scalable apps without unnecessary complexity.

Do you use Flask and Vanilla JS in your projects? Hit reply and share your thoughts on modularizing your code!

🧑‍💻 Happy coding!