Analyze, plan, and execute Replit SDK upgrades with breaking change detection.
Use when upgrading Replit SDK versions, detecting deprecations,
or migrating to new API versions.
Trigger with phrases like "upgrade replit", "replit migration",
"replit breaking changes", "update replit SDK", "analyze replit version".
Guide for upgrading Replit environments: Nix channel updates, package version bumps, database migrations (KV to PostgreSQL, dev to prod), deployment type changes, and Node.js/Python runtime upgrades.
Prerequisites
Existing Replit App with .replit and replit.nix
Git version control (recommended)
Backup of critical data before migration
Instructions
Step 1: Upgrade Nix Channel
Nix channels determine available package versions. Upgrade to get newer runtimes.
# .replit — before
[nix]
channel = "stable-23_05"
# .replit — after (2024-2025 stable)
[nix]
channel = "stable-24_05"
After changing the channel, reload the shell (exit Shell tab and re-enter). Then verify:
node --version # Should show newer version
python3 --version # Should show newer version
# .replit — update modules to match
modules = ["nodejs-20:v8-20230920-bd784b9"]
Verify after upgrade:
node --version # v20.x.x
npm --version # 10.x.x
npm test # Run tests to catch breaking changes
Step 3: Migrate from Replit KV to PostgreSQL
When your app outgrows the 50 MiB KV database limit:
// scripts/migrate-kv-to-postgres.ts
import Database from '@replit/database';
import { Pool } from 'pg';
const kv = new Database();
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
ssl: { rejectUnauthorized: false },
});
async function migrate() {
// Create table
await pool.query(`
CREATE TABLE IF NOT EXISTS kv_data (
key TEXT PRIMARY KEY,
value JSONB NOT NULL,
migrated_at TIMESTAMPTZ DEFAULT NOW()
)
`);
// Read all KV entries
const keys = await kv.list();
console.log(`Migrating ${keys.length} keys...`);
let migrated = 0;
let errors = 0;
for (const key of keys) {
try {
const value = await kv.get(key);
await pool.query(
'INSERT INTO kv_data (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = $2',
[key, JSON.stringify(value)]
);
migrated++;
} catch (err: any) {
console.error(`Failed to migrate key "${key}": ${err.message}`);
errors++;
}
}
console.log(`Migration complete: ${migrated} migrated, ${errors} errors`);
}
migrate().then(() => pool.end());
Step 4: Switch Deployment Type
# .replit — change deployment target
# From Autoscale (scales to zero):
[deployment]
deploymentTarget = "autoscale"
run = ["sh", "-c", "npm start"]
# To Reserved VM (always-on):
[deployment]
deploymentTarget = "cloudrun"
run = ["sh", "-c", "npm start"]
# To Static (frontend only):
[deployment]
deploymentTarget = "static"
publicDir = "dist"
After changing: click "Deploy" to create a new deployment with the new type.
Step 5: Migrate Large Files to Object Storage
// Move large values from KV to Object Storage
import Database from '@replit/database';
import { Client } from '@replit/object-storage';
const kv = new Database();
const storage = new Client();
async function migrateToObjectStorage(prefix: string) {
const keys = await kv.list(prefix);
for (const key of keys) {
const value = await kv.get(key);
const content = typeof value === 'string' ? value : JSON.stringify(value);
await storage.uploadFromText(`migrated/${key}`, content);
await kv.delete(key);
console.log(`Migrated: ${key}`);
}
}
Step 6: Pre-Migration Checklist
## Before Any Upgrade
- [ ] Git commit current working state
- [ ] Back up Replit KV data: export all keys to JSON file
- [ ] Back up PostgreSQL: pg_dump or Replit snapshot
- [ ] Note current deployment URL and settings
- [ ] Run full test suite: npm test
- [ ] Document current .replit and replit.nix content
## After Upgrade
- [ ] Reload shell (exit and re-enter Shell tab)
- [ ] Verify runtime versions
- [ ] npm install / pip install (rebuild packages for new runtime)
- [ ] Run full test suite
- [ ] Test in Workspace Webview
- [ ] Deploy and verify production health check
- [ ] Monitor for 24 hours for regressions
