How to customize build scripts in Replit

The .replit file supports three different command hooks, each serving a different purpose. The 'run' command executes when you press the Run button during development. The 'onBoot' command runs once when the Repl first starts (ideal for installing dependencies). The '[deployment] build' command runs before each deployment to prepare your app for production. Understanding which hook to use for each task is the key to a reliable build pipeline. Open .replit (enable 'Show hidden files' in the file tree menu) to see and edit these values.

1# .replit file — three command hooks
2
3# Runs once when the Repl first starts
4onBoot = "npm install"
5
6# Runs every time you press the Run button
7run = "node index.js"
8
9# Runs before each deployment
10[deployment]
11build = ["sh", "-c", "npm install && npm run build"]
12run = ["sh", "-c", "node dist/index.js"]

For development, you often need to compile code before running it. Update the run command to chain multiple steps using the double-ampersand (&&) operator, which stops execution if any step fails. This ensures that if compilation fails, the app does not start with stale code. You can also run multiple processes in parallel using the single ampersand (&) for cases like running a frontend dev server alongside a backend API.

1# Sequential build steps (stops on first failure)
2run = "npm run build && node dist/index.js"
3
4# Parallel processes (frontend + backend)
5run = "cd client && npm run dev & cd server && node index.js & wait"
6
7# TypeScript compilation then run
8run = "npx tsc --noEmit && npx ts-node index.ts"

The onBoot command runs once when the Repl first starts or restarts. This is the ideal place for dependency installation since it only needs to happen once, not on every Run press. Common use cases include npm install, pip install -r requirements.txt, or any other setup command that should only run at startup. This reduces the delay when pressing Run repeatedly during development.

1# Install dependencies on boot
2onBoot = "npm install"
3
4# Multiple boot steps
5onBoot = "npm install && npx prisma generate"
6
7# Python equivalent
8onBoot = "pip install -r requirements.txt"

The [deployment] build command runs in a clean environment before each deployment. This is where you install dependencies, compile TypeScript, bundle assets, run tests, and prepare your production-ready code. The build command must be self-contained — assume nothing is pre-installed. Chain all necessary steps with && so the deployment fails early if any step encounters an error. This prevents broken code from reaching production.

1[deployment]
2build = ["sh", "-c", "npm ci && npm test && npm run build"]
3run = ["sh", "-c", "NODE_ENV=production node dist/index.js"]
4deploymentTarget = "cloudrun"

Your build scripts may need different behavior in development versus production. Use the [run.env] section in .replit to set environment variables for the development run command. For deployment, set environment variables in the Deployments pane under Settings. You can also check the REPLIT_DEPLOYMENT variable in your code — it is set to '1' in deployed environments and undefined in development.

1# .replit file with environment variables
2run = "node index.js"
3
4[run.env]
5NODE_ENV = "development"
6DEBUG = "app:*"
7PORT = "3000"
8
9[deployment]
10build = ["sh", "-c", "npm ci && npm run build"]
11run = ["sh", "-c", "NODE_ENV=production node dist/index.js"]
12deploymentTarget = "cloudrun"

For builds with many steps, keep the .replit run command simple and put the complexity in package.json scripts. This makes each step individually testable from Shell and keeps the .replit file clean. Create separate scripts for each phase — clean, compile, test, build — and a single combined script that runs them all in order.

1{
2  "scripts": {
3    "clean": "rm -rf dist",
4    "compile": "tsc",
5    "test": "jest --passWithNoTests",
6    "build": "npm run clean && npm run compile && npm run test",
7    "start": "node dist/index.js",
8    "dev": "npx ts-node index.ts"
9  }
10}