How to manage Rails dependencies in Replit

Replit uses Nix to manage system-level packages including the Ruby interpreter itself. Open the file tree, enable Show hidden files from the three-dot menu, and edit the replit.nix file. Add the Ruby package, Bundler, and any system libraries your gems need (such as PostgreSQL client libraries for the pg gem, or ImageMagick for image processing). After editing replit.nix, type exit in the Shell to restart the environment and load the new packages. Search for available packages at search.nixos.org/packages if you need additional system dependencies.

1# replit.nix
2{ pkgs }: {
3  deps = [
4    pkgs.ruby_3_2
5    pkgs.bundler
6    pkgs.postgresql
7    pkgs.libffi
8    pkgs.zlib
9    pkgs.openssl
10    pkgs.libyaml
11    pkgs.pkg-config
12    pkgs.nodejs-20_x
13  ];
14}

The Gemfile lists all Ruby gems your Rails application depends on. If you are starting from scratch, create a Gemfile in your project root. If you imported an existing Rails project, the Gemfile already exists. Add your gems with version constraints. Use pessimistic version constraints (~>) for most gems to allow minor updates while preventing breaking major changes. After editing the Gemfile, run bundle install in the Shell to download and install all listed gems. Bundler creates a Gemfile.lock that pins exact versions for reproducibility.

1# Gemfile
2source 'https://rubygems.org'
3
4ruby '3.2.2'
5
6gem 'rails', '~> 7.1'
7gem 'pg', '~> 1.5'
8gem 'puma', '~> 6.0'
9gem 'jbuilder', '~> 2.11'
10gem 'bcrypt', '~> 3.1'
11gem 'bootsnap', require: false
12
13group :development, :test do
14  gem 'debug', platforms: [:mri]
15  gem 'rspec-rails', '~> 6.0'
16end
17
18group :development do
19  gem 'web-console'
20end

Some gems like pg (PostgreSQL), nokogiri (XML parsing), and mini_magick (image processing) require native C libraries to compile their extensions. When bundle install fails with an error about missing headers or libraries, you need to add the corresponding Nix package to replit.nix. The error message usually tells you which library is missing. Common mappings: pg needs pkgs.postgresql, nokogiri needs pkgs.libxml2 and pkgs.libxslt, mini_magick needs pkgs.imagemagick, and bcrypt needs pkgs.libffi. After adding the Nix package, type exit in the Shell, reopen it, and run bundle install again.

1# If you see: "Can't find the 'libpq-fe.h header"
2# Add to replit.nix: pkgs.postgresql
3
4# If you see: "Could not find libxml2"
5# Add to replit.nix: pkgs.libxml2 and pkgs.libxslt
6
7# If bundle install still fails after adding Nix packages,
8# try configuring the build with bundle config:
9bundle config build.pg --with-pg-config=$(which pg_config)
10bundle config build.nokogiri --use-system-libraries
11
12# Then retry:
13bundle install

The .replit file tells Replit how to run your application. For Rails, set the run command to start the Puma server bound to 0.0.0.0 on port 3000. Binding to 0.0.0.0 is critical because Replit's preview panel and deployments cannot reach a server bound to localhost or 127.0.0.1. Configure the port mapping so Replit's external port 80 maps to your local port 3000. Also set the deployment commands for production builds.

1# .replit
2entrypoint = "config/routes.rb"
3run = "bundle exec rails server -b 0.0.0.0 -p 3000"
4
5[nix]
6channel = "stable-23_11"
7
8[[ports]]
9localPort = 3000
10externalPort = 80
11
12[deployment]
13build = "bundle install && bundle exec rails assets:precompile"
14run = ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000", "-e", "production"]

Keep your gems current by periodically running bundle outdated in the Shell to see which gems have newer versions available. Update specific gems with bundle update gem-name or update all gems with bundle update (use with caution). For major Rails version upgrades, follow the official Rails upgrade guide and update one major version at a time. Always test your application after gem updates by running your test suite with bundle exec rspec or bundle exec rails test, and check the Console for deprecation warnings.

1# Check for outdated gems
2bundle outdated
3
4# Update a specific gem
5bundle update puma
6
7# Update all gems (use carefully)
8bundle update
9
10# Run tests after updating
11bundle exec rspec
12
13# Check for security vulnerabilities
14bundle audit check --update