replit-upgrade-migration

name	replit-upgrade-migration
description	Upgrade Replit Nix channels, migrate between database types, and update deployment targets. Use when upgrading Nix channel versions, migrating from Replit DB to PostgreSQL, switching deployment types, or updating system dependencies. Trigger with phrases like "upgrade replit", "replit nix upgrade", "migrate replit database", "replit version update", "replit channel update".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(pip:*)
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","replit","migration","nix","upgrade"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Replit Upgrade & Migration

Current State

!cat .replit 2>/dev/null | head -15 || echo 'No .replit found' !cat replit.nix 2>/dev/null || echo 'No replit.nix found'

Overview

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

Step 2: Upgrade Node.js or Python Runtime

# replit.nix — update runtime packages

# Before (Node 18)
{ pkgs }: {
  deps = [
    pkgs.nodejs-18_x
    pkgs.nodePackages.typescript
  ];
}

# After (Node 20)
{ pkgs }: {
  deps = [
    pkgs.nodejs-20_x
    pkgs.nodePackages.typescript-language-server
    pkgs.nodePackages.pnpm
  ];
}

# .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: