Dependencies, Packages and Why Builds Break Elsewhere

The one-sentence version: code you didn't write, that your app relies on anyway

Almost nothing you build starts from a completely blank slate. Instead of writing your own date-formatting logic, your own component library, your own payment SDK, your AI agent adds a package, someone else's already-written, already-tested code, and your app uses it directly. This is the normal, efficient way modern software gets built, not a shortcut or a compromise. Our guide to the folder structure of an AI-built app already names the file where your project's list of packages lives, package.json; this page covers what actually goes wrong around that file and why.

Where dependencies actually live: package.json and the lockfile

package.json lists every package your project depends on, along with an acceptable version range for each. Alongside it sits a lockfile, package-lock.json or an equivalent depending on the specific tool, which records the exact version of every one of those packages, and every package those packages themselves depend on, that was actually installed the last time everything worked. The distinction matters: package.json says "a version like this is fine," the lockfile says "this exact version, precisely, is what actually ran."

Why adding one package can silently break another

Packages depend on other packages, often several layers deep, and two packages you add separately can each expect a different, incompatible version of something they both rely on underneath. This isn't a mistake in the code your AI agent wrote, it's a genuine, occasionally unavoidable consequence of how a real dependency tree works: hundreds of packages can sit behind the handful you explicitly asked for. When something breaks right after adding a new package, describing exactly what changed and what broke, the same discipline this site's own guide to describing a bug so your AI agent can actually fix it covers, gets to the actual conflict faster than a vague "it's broken now."

The lockfile: why "it worked a minute ago" sometimes means a different install happened

A fresh install, your builder's own preview refreshing, a deploy to a separate host, a teammate cloning a connected GitHub repository, reads package.json's version ranges and installs whatever currently satisfies them. Without a respected lockfile, that install can quietly pick up a newer version than the one your app was actually built and tested against, even though nothing in your own code changed at all. The lockfile exists specifically to stop this: as long as it's present and respected, every fresh install reproduces the exact same versions, not just "something compatible."

Why this shows up most clearly once you deploy somewhere else

Your builder's own preview and a separate deploy target can each run their own install, and if that install doesn't reproduce the same dependency versions, "works in preview, breaks once deployed" is exactly what results. A version mismatch can break the build itself, which can leave the live site blank. Our guide to a blank screen after deploying covers the four settings to rule out first, a missing environment variable and a wrong publish folder among them, and what the build log shows when the build itself failed; the guide to environment variables not working after deploy covers the first of those in more depth.

Not every platform exposes this the same way

Lovable and Bolt.new both generate a standard package.json your AI agent edits directly through your prompts, visible and readable the way any other project file is. Base44 also produces a standard React project with its own package.json, but manages more of the routine dependency handling behind its own interface, exposing less of the raw mechanics day to day than Lovable or Bolt.new do. Either way, you rarely need to read or edit the file yourself; describing what you need is enough for your AI agent to add the right package correctly.