How to run an Express server in Replit

Start by creating a new App on Replit using the Node.js template. Once the workspace loads, open the Shell tab from the Tools sidebar and install Express. Replit's Node.js template includes npm by default. The npm install command downloads Express and adds it to your package.json. You can also install common companion packages like cors for cross-origin requests and dotenv for local environment variable loading, though Replit Secrets handles environment variables natively.

1# In the Replit Shell
2npm install express cors

Create an index.js file (or edit the existing one) with a basic Express server. The most critical Replit-specific detail is binding to 0.0.0.0 instead of the default localhost. When Express listens on localhost or 127.0.0.1, only processes on the same machine can reach it. Replit's Preview panel and deployment infrastructure access your server through a proxy, which requires the server to listen on all network interfaces (0.0.0.0). Use port 3000 as the default and configure it to read from the PORT environment variable as a fallback for deployment environments.

1const express = require('express');
2const cors = require('cors');
3
4const app = express();
5const PORT = process.env.PORT || 3000;
6
7// Middleware
8app.use(cors());
9app.use(express.json());
10app.use(express.urlencoded({ extended: true }));
11
12// Root route
13app.get('/', (req, res) => {
14  res.json({ message: 'Express server running on Replit', status: 'ok' });
15});
16
17// CRITICAL: Bind to 0.0.0.0, not localhost
18app.listen(PORT, '0.0.0.0', () => {
19  console.log(`Server running on http://0.0.0.0:${PORT}`);
20});

The .replit file controls how Replit runs your application. Open it from the file tree (enable Show hidden files if needed) and configure the entrypoint, run command, and port mapping. The port mapping is essential: it tells Replit to forward external port 80 (what users see) to your local port 3000 (where Express listens). Without this mapping, deployments will not route traffic to your server. Also set the deployment section with production-appropriate commands.

1# .replit
2entrypoint = "index.js"
3run = "node index.js"
4
5[nix]
6channel = "stable-23_11"
7
8[[ports]]
9localPort = 3000
10externalPort = 80
11
12[deployment]
13run = ["node", "index.js"]
14deploymentTarget = "cloudrun"

Organize your Express routes using the Router module for clean separation. Create a routes directory and define route files for each resource. Import them in your main index.js. Each route file exports a Router instance with its endpoints. This structure keeps your codebase maintainable as it grows and makes it easy for Replit Agent to modify individual routes without affecting others. Follow RESTful conventions with GET for reading, POST for creating, PUT for updating, and DELETE for removing resources.

1// routes/users.js
2const express = require('express');
3const router = express.Router();
4
5let users = [
6  { id: 1, name: 'Alice', email: 'alice@example.com' },
7  { id: 2, name: 'Bob', email: 'bob@example.com' }
8];
9
10// GET all users
11router.get('/', (req, res) => {
12  res.json(users);
13});
14
15// GET single user
16router.get('/:id', (req, res) => {
17  const user = users.find(u => u.id === parseInt(req.params.id));
18  if (!user) return res.status(404).json({ error: 'User not found' });
19  res.json(user);
20});
21
22// POST create user
23router.post('/', (req, res) => {
24  const { name, email } = req.body;
25  if (!name || !email) {
26    return res.status(400).json({ error: 'Name and email are required' });
27  }
28  const newUser = { id: users.length + 1, name, email };
29  users.push(newUser);
30  res.status(201).json(newUser);
31});
32
33module.exports = router;
34
35// In index.js, add:
36const userRoutes = require('./routes/users');
37app.use('/api/users', userRoutes);

Express needs centralized error handling to catch unhandled errors and return consistent error responses. Add an error handling middleware at the end of your middleware chain (after all routes). This catches any errors thrown in route handlers and returns a structured JSON error response instead of crashing the server or exposing stack traces. In production, never send stack traces to clients as they reveal internal implementation details.

1// Add after all routes in index.js
2
3// 404 handler for unmatched routes
4app.use((req, res) => {
5  res.status(404).json({
6    error: 'Not Found',
7    message: `Route ${req.method} ${req.path} does not exist`,
8    status: 404
9  });
10});
11
12// Global error handler
13app.use((err, req, res, next) => {
14  console.error('Unhandled error:', err.stack);
15  const isProduction = process.env.REPLIT_DEPLOYMENT === '1';
16  res.status(err.status || 500).json({
17    error: 'Internal Server Error',
18    message: isProduction ? 'An unexpected error occurred' : err.message,
19    ...(isProduction ? {} : { stack: err.stack })
20  });
21});

API keys, database URLs, and authentication secrets must be stored in Replit's Secrets tool, not in your code. Open Tools in the left sidebar and click Secrets. Add each secret with a key and value. Access them in your Express app through process.env. For deployment, you must add secrets separately in the Deployment pane because workspace secrets do not automatically carry to deployments. This is the most common cause of deployed Express apps failing with undefined configuration errors.

1// Access secrets in your Express app
2const API_KEY = process.env.API_KEY;
3const DATABASE_URL = process.env.DATABASE_URL;
4const JWT_SECRET = process.env.JWT_SECRET;
5
6// Validate required secrets at startup
7const required = ['DATABASE_URL', 'JWT_SECRET'];
8const missing = required.filter(key => !process.env[key]);
9if (missing.length > 0) {
10  console.error('Missing required secrets:', missing.join(', '));
11  console.error('Add them in Tools > Secrets');
12  process.exit(1);
13}