Skip to main content
Skip to content
Template Empire

Resources

Why your SaaS starter works locally but breaks in production

Last updated 31 May 2026 · Dan Tinsley, Halbon Labs

The most frustrating SaaS starter bug is the one that appears after the demo worked.

The app ran locally. Login worked. The dashboard loaded. Checkout redirected. Then production added a new URL, a different environment, stricter cookies, missing secrets, changed filesystem behaviour, build-time constraints, and webhook endpoints that no longer point at your laptop.

This is why a production-ready starter should be tested across local, preview, and production assumptions before it is sold.

Local success is not production proof

Local development is forgiving.

You control the port. You can restart services. You can inspect logs instantly. You may be using test keys, local cookies, relaxed HTTPS assumptions, and a database with seed data.

Production is different:

  • environment variables are managed by the host;
  • build and runtime may be separated;
  • callbacks need public URLs;
  • cookies may require HTTPS;
  • webhooks need public endpoints;
  • the filesystem may be ephemeral;
  • background tasks may time out;
  • preview deployments may have different URLs;
  • caching behaviour can change what users see.

A starter that ignores those differences creates deployment debt.

1. Environment variables drift between environments

Most production bugs begin with configuration.

Common issues:

  • missing DATABASE_URL in production;
  • using test Stripe keys with live webhook secrets;
  • wrong public app URL;
  • OAuth callback URL mismatch;
  • email provider configured locally but not in production;
  • secrets available at build time but not runtime;
  • preview variables copied from production by accident.

A good template should include environment variable documentation and validation. If a required variable is missing, the app should fail loudly during setup rather than fail silently during checkout.

2. Auth callbacks depend on public URLs

OAuth and magic-link flows are URL-sensitive.

Local development can use localhost. Production needs the real domain. Preview deployments may create temporary URLs. Custom domains may require additional provider configuration.

A starter should document:

  • local callback URL;
  • production callback URL;
  • preview callback strategy;
  • canonical app URL variable;
  • cookie domain behaviour;
  • HTTPS requirements.

If auth only works on the seller’s demo domain, the buyer has not inherited a complete auth system.

3. Webhooks need public endpoints and matching secrets

Local webhook testing usually uses a CLI forwarder. Production uses a deployed endpoint.

That means the endpoint secret can change. The URL definitely changes. Event delivery can be retried. Errors show up in provider dashboards, not only app logs.

Deployment docs should explain:

  • production webhook endpoint URL;
  • which events to subscribe to;
  • where to store the endpoint secret;
  • how to inspect failed deliveries;
  • how to replay events;
  • how to separate test and live mode.

Billing bugs in production are often webhook configuration bugs.

4. File storage assumptions break on serverless hosts

Some templates write files to local disk. That may work on a laptop. It may fail or disappear in production depending on the host.

Uploads, generated PDFs, exports, avatars, and image processing should have explicit storage assumptions.

Ask:

  • Does this template write to disk?
  • Is storage local, S3-compatible, database-backed, or provider-specific?
  • Does static export change upload behaviour?
  • Are generated files temporary or durable?
  • Are file-size limits documented?

A production-ready template should not hide storage decisions.

5. Background work may not fit request/response functions

SaaS products often need work after the user action:

  • send emails;
  • process webhooks;
  • generate reports;
  • sync subscriptions;
  • import data;
  • export account data;
  • run scheduled cleanup;
  • retry failed jobs.

If a template assumes every task can happen inside a web request, production can expose timeouts and reliability issues.

A starter should explain whether it supports background jobs, scheduled tasks, queues, or provider-specific alternatives. If it does not, the docs should be honest about the limitation.

6. Build-time and runtime are not the same

Next.js applications can evaluate code at build time and runtime. Problems appear when code expects runtime secrets during build, reads unavailable files, or fetches data from services that are not reachable during deployment.

Common signs:

  • build fails only on host;
  • page statically generated with stale data;
  • environment variable exists locally but not during build;
  • dynamic route is treated as static accidentally;
  • server-only code leaks into client bundles.

A template should document which commands are expected to pass before deployment:

bash
pnpm lint
pnpm typecheck
pnpm test
pnpm build

The buyer should not discover build assumptions by trial and error.

7. Preview deployments need their own policy

Preview deployments are useful, but they can be dangerous if treated like production.

Questions to answer:

  • Do preview deployments use test billing?
  • Can preview deployments send real emails?
  • Are OAuth callbacks configured for preview URLs?
  • Is the preview database shared or isolated?
  • Can preview webhooks mutate production data?
  • Are secrets scoped correctly?

For agencies and teams, preview deployment policy is part of delivery quality.

8. Docker support should be real, not decorative

“Docker-ready” should mean more than a Dockerfile that has never been used.

For a SaaS starter, useful Docker support may include:

  • app service;
  • database service;
  • migration command;
  • health check;
  • environment variable example;
  • volume configuration;
  • production image notes;
  • self-hosting caveats.

Docker Compose is valuable because it can define the multi-service local stack in one place. But it still needs documentation.

9. Observability decides whether you can fix production

A template does not need a full observability platform. It does need basic visibility.

At minimum:

  • structured errors;
  • request logs for API routes;
  • webhook logs;
  • auth error states;
  • health check route;
  • clear build output;
  • admin-visible audit trails for sensitive actions.

When a production user says “I paid but nothing happened,” logs are the difference between diagnosis and guesswork.

Production readiness checklist

Before deploying a SaaS starter, verify:

  • All required environment variables are documented and validated.
  • Auth callback URLs are configured for production.
  • Preview deployment behaviour is defined.
  • Stripe webhook endpoint and secret are production-specific.
  • Test and live billing are separated.
  • Database migrations run safely.
  • Seed data is not accidentally used as production data.
  • File storage assumptions are explicit.
  • Background job limitations are known.
  • lint, typecheck, and build pass in CI or locally.
  • Health checks exist.
  • Logs are sufficient to diagnose auth, billing, and API failures.
  • The deployment guide covers the host you intend to use.

Template Empire angle

Template Empire’s full-stack templates are positioned around deployable foundations: Docker readiness, health checks, quality-gate reports, and buyer simulation. The goal is not simply “runs on my machine.” The goal is a handoff that survives the first real deployment.

Further reading