Build Configuration
Customize your build process with commands, directories, and options
While Nixpacks handles most builds automatically, you can customize the build process for specific requirements.
Build Settings
Configure these settings in your service deployment page:
- Build Command: Custom command to build your application
- Start Command: Command to start your application
- Root Directory: Directory containing your application (for monorepos)
- Install Command: Custom dependency installation command
Custom Build Command
Override the default build command for your framework:
Vite with a custom build script
npm run buildReact with environment-specific build
REACT_APP_ENV=production npm run buildPython with pre-build steps
python manage.py collectstatic --noinputCustom Start Command
Specify how your application should start:
# Node.js with PM2pm2-runtime start ecosystem.config.js# Python with Gunicorngunicorn app:app --bind 0.0.0.0:$PORT --workers 4# Go binary./bin/server# Ruby on Railsbundle exec rails server -b 0.0.0.0 -p $PORT
$PORT environment variable for your application port. Replov assigns this automatically.Monorepo Configuration
For monorepos, specify the root directory of your service:
packages/apinpm run buildnpm startExample Monorepo Structure
my-monorepo/├── packages/│ ├── api/ ← Root Directory for API service│ │ ├── package.json│ │ └── src/│ ├── web/ ← Root Directory for Web service│ │ ├── package.json│ │ └── src/│ └── shared/│ └── package.json├── package.json ← Workspace root└── pnpm-workspace.yaml
Advanced: nixpacks.toml
For advanced customization, create a nixpacks.toml file in your repository root:
# Specify Nix packages[phases.setup]nixPkgs = ["nodejs-18_x", "python311", "postgresql"]# Custom install phase[phases.install]cmds = ["npm ci --production=false","pip install -r requirements.txt"]# Custom build phase[phases.build]cmds = ["npm run build","python manage.py collectstatic --noinput"]# Start command[start]cmd = "npm start"# Environment variables available during build[variables]NODE_ENV = "production"PYTHON_VERSION = "3.11"
nixpacks.toml file gives you full control over the build process but is rarely needed for standard applications.Build Caching
Replov automatically caches dependencies to speed up builds:
- Node.js:
node_modulescached - Python: pip cache and virtualenv cached
- Go: Module cache persisted
- Ruby: Gem cache maintained
Build-Time Environment Variables
Some environment variables are needed during the build process:
# React/Vite - must start with VITE_VITE_API_URL=https://api.example.com# Next.js - must start with NEXT_PUBLIC_NEXT_PUBLIC_API_URL=https://api.example.com# Create React App - must start with REACT_APP_REACT_APP_API_URL=https://api.example.com# General build variablesNODE_ENV=productionCI=true
Custom Dockerfile
If you need complete control, you can provide your own Dockerfile:
FROM node:18-alpineWORKDIR /app# Install dependenciesCOPY package*.json ./RUN npm ci --production=false# Copy sourceCOPY . .# BuildRUN npm run build# Remove dev dependenciesRUN npm prune --production# Expose portEXPOSE 3000# StartCMD ["npm", "start"]
When a Dockerfile is present in your repository root, Replov uses it instead of Nixpacks.
Build Hooks
Run custom scripts at different build stages using package.json scripts:
{"scripts": {"prebuild": "echo 'Running before build'","build": "next build","postbuild": "echo 'Running after build'","prestart": "node scripts/setup.js","start": "next start"}}
Build Optimization Tips
1. Use .dockerignore
Exclude unnecessary files from the build context:
node_modules.git.env*.log.DS_Storecoverage.next/cache
2. Optimize Dependencies
Use npm ci instead of npm install for faster, more reliable installs.
3. Multi-Stage Builds
Use multi-stage Dockerfiles to reduce final image size by excluding build tools.
4. Leverage Caching
Copy package files before source code to maximize cache hits.
Troubleshooting Builds
Build Timeout
Builds timeout after 15 minutes. Optimize your build process or contact support for extended limits.
Out of Memory
Builds have 2GB RAM limit. Reduce build concurrency or split into smaller builds.
Dependency Installation Fails
Check your lock files (package-lock.json, yarn.lock) are committed and up-to-date.