dev-prod-parity
Skill1 starsChanged 3 months agoMITView on GitHub
Validate that what works in the dev preview will also work in the published (deployed) app. Use before every publish/deploy, after adding a new backend service or artifact, and whenever a user reports "works in preview but broken in production" (404s, HTML-instead-of-JSON, failed subprocesses, wrong URLs).
- Reads credentials
In this repository5 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- defi-protocol-templatesSkill
- solidity-securitySkill
- web3-testingSkill
- Monad Testnet Safe Transfer PreviewSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Check: every backend the frontend calls appears in some artifact.toml with [[services]], localPort, paths, production build/run blocks.
- Very specific: line 34
Never resolve sibling/asset files via process.cwd().
- Very specific: line 60
Check artifact.toml coverage: every path the frontend fetches maps to a registered service's paths.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Dev/Prod Parity Validation
Production on Replit differs from the dev preview in specific, predictable ways. Every "works in preview, broken when published" bug in this project came from one of the gaps below. Run this checklist before publishing and when debugging production-only failures.
The 6 parity gaps (each caused a real production bug)
1. Service must be registered for production, not just a dev workflow
A workflow only runs in dev. Production only starts services declared in an artifact's .replit-artifact/artifact.toml with a [services.production] build + run config.
- Symptom: API returns the frontend's
index.html("DOCTYPE is not valid JSON") or 404 because requests fall through to a static catch-all. - Check: every backend the frontend calls appears in some artifact.toml with
[[services]],localPort,paths, production build/run blocks. - Note:
verifyAndReplaceArtifactTomlcannot create a new artifact.toml or change id/kind/version. To productionize an unregistered service, add it as a second[[services]]block in an existing registered artifact's toml.
2. Production proxy forwards the FULL path, unstripped
Dev routing may strip the path prefix; the production proxy does not. A service at paths = ["/foo"] receives GET /foo/api/x, not /api/x.
- Fix: first Express middleware strips the prefix with a strict boundary check:
const prefix = "/foo"; app.use((req, _res, next) => { if (req.url === prefix || req.url.startsWith(`${prefix}/`) || req.url.startsWith(`${prefix}?`)) { req.url = req.url.slice(prefix.length) || "/"; } next(); }); - Health check paths in
[services.production.health.startup]are proxy-visible: use/foo/healthz, not/healthz.
3. Working directory differs
Dev (pnpm --filter <pkg> run dev) runs with cwd = the artifact dir. Production (node artifacts/<pkg>/dist/index.mjs) runs with cwd = workspace root.
- Never resolve sibling/asset files via
process.cwd(). Use:import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; const here = dirname(fileURLToPath(import.meta.url)); - Symptom: subprocesses die instantly ("MCP error -32000: Connection closed"), missing-file errors that never happen in dev.
4. Environment variables differ
REPLIT_DEV_DOMAIN / REPLIT_DOMAINS are dev-only or hold the dev domain. Any externally-advertised URL (agent cards, webhooks, OG tags) must come from an explicit env var (e.g. PUBLIC_BASE_URL) set in the service's [services.production.run.env], using the real production URL from getDeploymentInfo() — never guessed.
- Symptom: production advertises
http://localhost:PORTor a.replit.devURL.
5. Frontend URLs must be base-path relative
Root-relative fetches (/api/...) escape the artifact's path prefix. Use import.meta.env.BASE_URL (Vite) or the scaffold's helper. Compile-time env vars (VITE_*) are baked at build; confirm they're set for the production build or have safe relative defaults.
6. Stale production build
The published app is a snapshot. If a fix was merged after the last publish, production still runs the old code — republish before concluding something is "broken in production."
Pre-publish validation procedure
- Simulate production locally. For each runnable service, from the workspace root:
Then curl the health endpoint with the path prefix (cd /home/runner/workspace && PORT=<freePort> NODE_ENV=production node <prod run args...>/foo/healthz) and one real API route with the prefix. This alone catches gaps 2 and 3. - Grep for landmines in server code:
process.cwd(),REPLIT_DEV_DOMAIN, hardcodedlocalhost, hardcoded ports. - Check artifact.toml coverage: every path the frontend fetches maps to a registered service's
paths. - After publishing, smoke-test the live URL (from
getDeploymentInfo().primaryUrl): health endpoints, one real API call, and any externally-advertised URLs (agent card, webhooks) contain the production domain. - Check deployment logs (RefreshAllLogs / deployment log files) for
healthcheck failedandrunnable=N— N must equal the number of backend services you expect.
Debugging a production-only failure
- "DOCTYPE is not valid JSON" → gap 1 (service not deployed) or gap 5 (wrong fetch URL).
- HTTP 404 from a deployed service → gap 2 (prefix not stripped).
- Subprocess/file errors only in prod → gap 3 (cwd).
- Wrong/localhost URLs advertised → gap 4.
- Feature missing entirely → gap 6 (stale build).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

