replit-known-pitfalls

name	replit-known-pitfalls
description	Avoid the top Replit anti-patterns: ephemeral filesystem, public secrets, port binding, Nix gotchas, and database limits. Use when reviewing Replit code, onboarding developers, or auditing existing Replit apps for common mistakes. Trigger with phrases like "replit mistakes", "replit anti-patterns", "replit pitfalls", "replit what not to do", "replit code review".
allowed-tools	Read, Grep
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","replit","audit","anti-patterns"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Replit Known Pitfalls

Overview

Real gotchas when building on Replit. Each pitfall includes what goes wrong, why, and the correct pattern. Based on common failures in Replit's ephemeral container model, Nix-based environment, and cloud hosting platform.

Pitfall Reference

1. Writing to Local Filesystem for Persistence

What happens: Data is lost when the container restarts, deploys, or sleeps.

# BAD — files disappear on container restart
with open("user_data.json", "w") as f:
    json.dump(data, f)

# GOOD — use Replit's persistent storage
from replit import db
db["user_data"] = data

# For files, use Object Storage
from replit.object_storage import Client
storage = Client()
storage.upload_from_text("user_data.json", json.dumps(data))

Rule: Anything written to the filesystem is ephemeral. Use PostgreSQL, KV Database, or Object Storage for data that must survive restarts.

---

2. Hardcoding Secrets in Source Code

What happens: Secrets are visible to anyone who views your Repl (public by default on free plans). Replit's Secret Scanner catches some cases but not all.

# BAD — exposed in public Repl
API_KEY = "sk-live-abc123"
DATABASE_URL = "postgresql://user:password@host/db"

# GOOD — use Replit Secrets (lock icon in sidebar)
import os
API_KEY = os.environ["API_KEY"]
DATABASE_URL = os.environ["DATABASE_URL"]

---

3. Binding to localhost Instead of 0.0.0.0

What happens: App starts but Webview is blank. Replit's proxy can't reach the app.

// BAD — unreachable from Webview and deployments
app.listen(3000, );
app.(, );


app.(, );


  = (process.. || );
app.(, );