Blog / Build with AI /
Splitting one big file into sensible parts
There’s a moment in every small project when the main file hits 800 lines and you start scrolling past things you wrote last week without recognising them. Everything is in one place, nothing is easy to find, and a change to one feature breaks something three screens away.
Splitting that file into sensible parts is one of the best uses of AI help, and one of the easiest to get wrong. This is how I’d go about it safely.
When to split
You don’t split because a file is long. You split because it’s hard to work with. Signs it’s time:
- You can’t remember what’s in it.
- Unrelated things live together (styling, data, logic and setup).
- Asking an AI to change one thing risks it rewriting everything else.
- The file no longer fits in a single AI conversation, so the tool starts forgetting the top while editing the bottom.
That last point is practical. Context windows explained for builders explains why a long file makes AI worse at editing it.
What “sensible” means
Parts should be split by purpose, not by size. Cutting a file into four equal chunks gives you four confusing files. Instead, ask what the file is doing.
For a typical small web tool, the natural groups are:
- Data: the lists, settings and constants.
- Logic: the functions that do the work (calculate, filter, format).
- Interface: the code that reads from and writes to the page.
- Setup: the bit that starts everything.
For an HTML page with everything in one file, the easiest first split is pulling out the CSS into styles.css and the JavaScript into app.js. Nothing about how it works changes; you’ve just put things in labelled drawers.
The safety net first
Before you move anything:
- Save a copy of the working project, or commit it in Git. Git basics for non-developers shows how.
- Write down what “working” means. Five things you can click or type to prove the tool still works: add an item, delete one, refresh and see it saved, change a setting, export.
- Change nothing else at the same time. A split is a reorganisation, not an excuse to add features. Mixing the two makes bugs impossible to trace.
Step 1: ask for a plan, not code
Give the AI the file (or the relevant parts) and ask for a proposal first:
Here is my app.js. Don’t rewrite anything yet. Propose a way to split it into several files by purpose. For each file, list the functions and variables that would go in it, and note any that are used across files. Keep behaviour identical. Tell me the order I should do it in so the app still works after each step.
Read the plan. If it suggests ten files for a 400-line tool, push back: “Simplify. Maximum four files.”
Step 2: move one piece at a time
Don’t ask for the whole split at once. Move the least tangled part first, usually the constants and data. Then test, using your five checks. Then the next piece.
Move all the constants and default settings into a file called config.js and export them. Update app.js to import them. Show me only the changed parts.
“Show me only the changed parts” keeps the reply short and reviewable.
Step 3: handle the connections
The tricky bit is that parts depend on each other. A function in logic.js might use a variable defined in app.js. When you split, those links break, typically with errors like “x is not defined” or “does not provide an export named”.
In a browser, split JavaScript files need to be loaded properly, either with several script tags in the right order or with modules (type="module" and import/export). Ask the AI which approach it’s using and why, and note one thing: modules often won’t load if you simply double-click the HTML file, because browsers block them from file:// addresses. You’ll need a tiny local server, or to use script tags instead. That’s a very common stumbling block for beginners.
Step 4: test after every move
Run your five checks. Look at the browser console for errors. If something breaks, undo the last move and ask for help with that specific step. Because you only moved one piece, you know exactly where the problem is.
Step 5: tidy up
Once it works:
- Give files names that say what they do (
format-date.jsbeatsutils2.js). - Remove dead code the AI left behind.
- Add a short README line: what each file is for.
The same idea for documents
This works beyond code. A 40-page document, a giant spreadsheet with ten tabs of unrelated things, or a huge CSS file all benefit from the same method: group by purpose, move a bit at a time, check after each move.
A small example
Imagine a single index.html with 120 lines of markup, 200 lines of styles and 500 lines of JavaScript for a tip calculator that grew into a bill splitter with saved presets. A sensible first split is three files: index.html, styles.css, app.js. The second split is inside app.js: pull the pure calculation functions (no page access, just numbers in and numbers out) into calc.js. Those are the easiest parts to test and the least likely to break, so they make a good starting point and a good place to build confidence.
What goes wrong
- Circular dependencies. File A needs B, and B needs A. A sign that the split lines are in the wrong place.
- Over-splitting. Twenty tiny files can be harder than one big one.
- The AI “improves” things. Quietly renaming functions or changing logic while moving. Insist on identical behaviour, and compare before and after.
- Lost comments. Moving code often drops the explaining notes. Keep them.
Key takeaways
- Split by purpose, not by length.
- Save a copy and define “working” first.
- Ask for a plan, then move one piece at a time.
- Test after every step.
- Keep the change purely organisational.
Related reading
Which file in your latest project is the one you dread opening?