explainx / blog
Learn what software environments are, why production, staging, and development exist as separate instances, and how environment variables prevent the kind of mistakes that charge real users with test credit cards.
Jun 27, 2026
Vercel takes your Next.js app from GitHub to a live URL in about sixty seconds. Here is exactly how it works, what it handles for you, how to configure environment variables for production, and when the free tier stops being enough.
Jun 27, 2026
Next.js from zero: what it is, why people use it, how to install it with create-next-app, and how to build your first pages with the App Router. Real commands, no assumed knowledge.
Jun 27, 2026
Railway is where you deploy the parts of your stack that need to stay running: PostgreSQL databases, background workers, WebSocket servers, and Python backends. Here is a practical walkthrough of deploying an app, adding a database, wiring environment variables, and understanding when to use Railway instead of Vercel.
Every broken deployment has a story. Here is one of the most common ones.
A developer builds a payment flow over a weekend. They test it thoroughly in their local app using Stripe's test mode. The card 4242 4242 4242 4242 goes through cleanly. They push to production on Monday morning, confident it works. Within an hour, real users are complaining that payments are failing. The developer checks the logs and finds the problem immediately: the Stripe test key (sk_test_xxx) is still set in production. Real credit cards cannot be processed with a test key. Every transaction is silently rejected.
The fix is a one-line change. But the real lesson is architectural: development and production should never share configuration. That is what environments are for.
An environment is a separate, isolated instance of your application running with its own configuration, data, and infrastructure. When you open your project on your laptop and hit npm run dev, you are running in one environment. When a real user visits your site from their browser, they are hitting a completely different environment — different server, different database, different API keys.
The separation is intentional. It means a bug you introduce at 2 AM does not immediately break the product your paying customers are using. It means you can test a new feature against realistic data before it is visible to the world. It means the test credit card you just ran through checkout does not appear on a real bank statement.
Professional software teams typically maintain three environments.
Development runs on your machine. It is yours to break. You can delete the database, push half-written code, enable verbose logging that prints every SQL query to the console, and crash the app twenty times before lunch. None of that affects anyone else.
Development typically uses:
localhost:5432, or SQLite in a file)The goal of the development environment is speed. You want fast feedback loops. You do not care about performance, uptime, or data integrity the way you would in production.
Staging is the environment most beginners skip — and missing it is where expensive mistakes happen.
Staging mirrors production as closely as possible: same infrastructure, same build configuration, same environment variables (swapped for staging-specific values), same Docker image if you are using containers. But it is not public. Only your team can access it, usually behind a password or a VPN.
Staging is used for:
localhost (webhooks, redirects, CORS headers)The rule: if something passes in staging, it is ready for production. If you skip staging and go straight from dev to production, you are making a bet that your localhost environment perfectly matches the live server. It almost never does.
Production is the live application. Real users, real data, real money. This is the environment where mistakes have consequences.
Production deployments follow strict rules at most companies:
In production, debug mode is off. Error details are hidden from users (but logged to a monitoring service). Performance matters. Uptime matters.
The core principle: production is conservative. You do not experiment in production.
The mechanism that makes environments work is environment variables — key-value pairs that are set outside your code and change per environment.
Instead of writing this in your code:
const stripe = new Stripe('sk_live_my_real_key_that_charges_money');
You write:
const stripe = new Stripe(process.env.STRIPE_KEY);
And then you define STRIPE_KEY separately in each environment. In development it is the test key. In production it is the live key. Your code never changes — only the value injected at runtime.
A .env file for development might look like this:
DATABASE_URL=postgresql://localhost:5432/myapp_dev
STRIPE_KEY=sk_test_xxx
ANTHROPIC_API_KEY=sk-ant-xxx
NEXT_PUBLIC_APP_URL=http://localhost:3000
And the production environment would have:
DATABASE_URL=postgresql://prod-server/myapp_prod
STRIPE_KEY=sk_live_xxx
NEXT_PUBLIC_APP_URL=https://myapp.com
The database URL points to different servers. The Stripe key switches from test to live. The app URL is the real domain instead of localhost. Same code, completely different runtime behavior.
If you are building with Next.js, the standard pattern is to use .env.local for your local development secrets. Next.js loads it automatically when you run next dev.
The naming convention matters:
.env — checked into git, used for non-secret defaults.env.local — never committed, used for local secrets (overrides .env).env.production — checked into git, used for non-secret production defaults.env.production.local — never committed, used for production secretsVariables prefixed with NEXT_PUBLIC_ are exposed to the browser. Everything else stays server-side only. Never put a secret API key in a NEXT_PUBLIC_ variable — it will be bundled into the JavaScript file that every visitor downloads.
The single most important rule about .env files: they must never be committed to version control.
Add this to your .gitignore:
.env
.env.local
.env.*.local
If a .env file with real API keys lands in a public GitHub repository, automated bots find it within minutes. Those bots are scanning GitHub continuously for leaked credentials. Once a key is exposed in git history, you must rotate it immediately — not delete the file, because the key is still in the commit history. Rotate it. Then delete the file and add it to .gitignore.
Some teams take environment separation further with feature flags. A feature flag is a configuration toggle that lets you deploy code to production but hide it from most users. You might deploy a new dashboard design but only show it to internal employees until it is polished. Or you might roll it out to 5% of users, watch the error rate, and expand the rollout if everything looks healthy.
Feature flags decouple deployment (pushing code to the server) from release (making a feature visible to users). This is safer than combining both into one step.
Tools like LaunchDarkly, Unleash, and PostHog feature flags implement this pattern. For smaller projects, a simple environment variable or a database row can serve as a basic flag.
A typical CI/CD (Continuous Integration / Continuous Deployment) pipeline works like this:
Each step is a gate. Broken tests block deployment to staging. A failed staging review blocks the merge. The goal is to catch problems as early as possible — in development, then in staging — so production stays clean.
If you are learning git and GitHub and want to understand how to push your code in the first place, the beginner guide to Git and GitHub covers that foundation.
Running database migrations directly in production. Always test migrations in staging first. A migration that drops a column, renames a table, or changes a data type can break a running app in unpredictable ways. Staging is where you discover that.
Using production API keys in development. If you use your live Stripe key locally and accidentally process a test charge, you may create accounting noise, trigger fraud detection, or incur unexpected fees. Always use test keys in development.
Committing secrets to git. Covered above, but worth repeating. Add .env.local to .gitignore before you create the file, not after.
Not having a staging environment at all. This feels fine until the first time you deploy a bug that was obvious when someone looked at it in a browser. Staging is cheap (or free on most platforms). The bugs it catches are not.
Assuming localhost behavior matches production. HTTPS redirects, cookie Secure flags, CORS headers, and environment-specific webhook URLs all behave differently locally. Staging with a real domain reveals these issues before production does.
| Development | Staging | Production | |
|---|---|---|---|
| Who uses it | You (developer) | Your team, QA | Real users |
| Data | Fake / seeded | Anonymised copy of prod | Real user data |
| API keys | Test keys | Test or staging keys | Live keys |
| Errors shown | Full detail, stack traces | Internal only | Hidden from users |
| Stability needed | Low — break freely | Medium | High |
| Deployments | Constant | On each PR merge | Deliberate, reviewed |
Understanding environments is one of those concepts that clicks quietly but then suddenly explains a dozen things that were confusing before — why .gitignore exists, why there are multiple database URLs in a config file, why the QA team has a separate website to test on. Once you see the separation, you start building with it from day one.