Guides

How to split code into files — export and import in 6 steps, without breaking anything

Illustration: a long scroll cut into neat sheets, each tucked into its own folder

You've been building a project with AI, and at some point app.js grew to 1,500 lines. The model starts getting confused: it edits the wrong thing, forgets the top of the file, breaks something next door. And you're scrolling for five minutes to find the function you need.

There's one fix for this — split the file into several small ones. Sounds scary, but the mechanics are simple: two words, export and import. Let's go step by step on a real example.

How files see each other

First, one important idea. Every module file is a closed room. Whatever is declared inside is invisible from outside.

To share a function, a file has to explicitly put it out with the word export. And another file has to explicitly call it in with import. No export–import pair means no connection.

That's not bureaucracy — it's protection. You always see where things came from. And no function sneaks in where it wasn't invited.

Splitting a file, step by step

Say app.js mixes price formatting, cart logic and page rendering.

  1. Find the seams. Skim the file and group functions by topic. Everything about formatting — one pile. Everything about the cart — another. Each pile becomes a file. Don't split finer than you need: a 5-line file is awkward too.

  2. Create a new file and move the pile there. For example, utils/format.js. Move the functions whole — cut and paste.

  3. Put export in front of what's needed outside.

    // utils/format.js
    export function formatPrice(value) {
      return "$" + value.toLocaleString("en-US")
    }
    

    Helper functions needed only inside the file stay without export. Let them sit in their room.

  4. Import it in the old file. At the very top of app.js:

    import { formatPrice } from "./utils/format.js"
    

    The path here is counted from the file doing the importing, not from the folder you started the program in. ./ means "next to me". If paths make you wobble, see the breakdown of what a file path is.

  5. Run it and check. Open the page or run the script. If everything works as before — the step worked. Commit right away so you have something to roll back to.

  6. Repeat for the next pile. One file at a time. Move — check — commit. Don't move everything at once: if it breaks, you won't know where.

Three errors you'll almost certainly hit

Don't panic at the red text — it's a normal stage. Here's what it usually means. More on reading these messages in how to read an error message.

  • Cannot find module or Failed to resolve import. The path is wrong. Check ./, the folder name and the .js extension. In the plain browser and Node the extension is required. Bundlers like Vite let you leave it out.
  • does not provide an export named .... You're importing something the file didn't put out. A missing export or a typo in the name.
  • Cannot use import statement outside a module. The environment doesn't know these are modules. In the browser you need <script type="module">. In Node — "type": "module" in package.json. In React or Vite projects this is already set up.

Named vs default export

You'll see two kinds of export. The difference is the curly braces.

  • Named: export function formatPrice. Imported strictly by name, in braces: import { formatPrice } from .... One file can export as many as you like.
  • Default: export default function Cart. Imported without braces, any name: import Cart from .... There's only one per file.

A simple rule for beginners: use named ones. With them a typo gives an error right away instead of quiet confusion.

Ask AI to do it for you

Splitting a file is classic refactoring: the code changes shape, but not behavior. AI handles it well if you say so directly.

Weak promptSplit app.js into files
Strong promptSplit app.js into several files by topic: formatting, cart, rendering. Rules: 1) the program behavior does not change in any detail; 2) use named export and import with an explicit .js extension; 3) do not rename functions; 4) first show a plan of which functions go to which file, and wait for my ok; 5) move one file per step.

The plan rule matters most. You see the layout before AI starts cutting. And you catch oddities like "the payment function moved into utils" before they happen.

How many files should I split into?

A rule of thumb: when a file no longer fits in your head or on one or two screens. Usually that's 200–300 lines. But meaning matters more: one file — one topic.

What is a circular import?

It's when file A imports B, and B imports A again. The code may run, but some function will turn out undefined. The fix is to move the shared part into a third file.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →