It works here and not there

Two computers, six differences

The dev server on your laptop and the build running on your host are not the same program. Six differences account for nearly every first deployment failure, and all six are checkable in ten minutes.

1. Case sensitivity

Mac and Windows treat BookingCard.tsx and bookingcard.tsx as the same file. Linux, which your host runs, does not. An import with the wrong capitalisation works perfectly on your machine and fails on the server with Module not found.

This is the single most common one, it is invisible locally, and it is why the error message can look absurd: the file is right there.

git ls-files | grep -i bookingcard   # what git actually stored

Git can also hold the wrong case even after you rename the file, because it did not notice a change that your filesystem considers meaningless. git mv -f oldname newname forces it.

2. Environment variables

Your .env file never left your laptop, deliberately: it is in .gitignore. Every value in it must be entered again in your host’s settings panel, and one missing entry produces a failure that reads like a code bug.

Keep a committed .env.example listing every key with fake values. It is the checklist for a new environment, and it is the file that makes a fresh setup take five minutes instead of an afternoon of guessing.

3. Dev server versus build

The dev server compiles on demand, tolerates type errors, prints warnings and keeps going. The production build compiles everything ahead of time and stops on anything it does not like.

So run the build locally before you push:

npm run build

That one command catches most deployment failures on your own machine, in thirty seconds, where the feedback loop is fast. Put it in your rules file as something the agent runs before claiming a change is finished, and you will almost stop meeting this category.

4. Where the code runs

A component that reads window or localStorage works in the browser and crashes during a server render, because on the server there is no window. The error mentions window is not defined and the fix is either to guard it or to mark the component as client-only.

The dev server sometimes hides this by rendering differently. The build does not.

5. The database is not the same database

The tables you created locally do not exist on the new one. Your migrations have to be run against production, as a deliberate step, and forgetting it produces confident errors about missing columns.

Also: your production database is empty of the test data you have been relying on without noticing. A page that assumed at least one row will meet zero for the first time.

6. Versions and dependency types

Your host may default to a different Node version. Pin it: an engines field in package.json, or a .nvmrc file, or a setting in the host’s dashboard.

And a package installed with --save-dev that the running app actually needs will not be present in production, because dev dependencies are skipped during a production install.

The pre-deploy check, in order

git status              # nothing uncommitted that matters
npm ci                  # exactly the locked versions
npm run build           # the real build
npm run start           # run the built version, not the dev server

That fourth line is the one nobody does, and it is the closest thing to production you can run locally. Open the app and click through it. Several classes of bug appear only here.

When it fails only in production

Sometimes the build passes locally and the deployed app is still wrong. Then the difference is environment, not code, and there are exactly four places to look: the environment variables in the host’s panel, the build log, the runtime log, and whether migrations ran.

Read the build log from the bottom. Hosts print a great deal of progress output and one failure line, and it is not usually at the end.