start

The start command runs your built Refine application in production mode.

Usage

refine start [options] [args...]

Before running start, you must first build your application with refine build.

Options

-p, --platform <platform>

string

Specify the platform to run the start command on. The CLI auto-detects your project type, but you can override it.Choices: vite, nextjs, remix, remix-spa, remix-vite, craco

refine start --platform nextjs

args...

string[]

Additional arguments passed directly to the underlying server

refine start --port 8080

How It Works

The start command:

Detects your project type (Vite, Next.js, Remix, etc.)
Runs the appropriate production server command
Serves the built application from the output directory

Platform-Specific Commands

The CLI runs these commands based on your project type:

Vite: vite preview
Next.js: next start
Remix: remix-serve build
Remix SPA: vite preview

Examples

Basic Usage

Build and start your application:

refine build
refine start

Output (Next.js)

▲ Next.js 14.0.0
- Local:        http://localhost:3000
- Network:      http://192.168.1.100:3000

✓ Ready in 1.2s

Output (Vite)

  ➜  Local:   http://localhost:4173/
  ➜  Network: http://192.168.1.100:4173/

Custom Port

Start on a specific port:

refine start --port 8080

Output

  ➜  Local:   http://localhost:8080/
  ➜  Network: http://192.168.1.100:8080/

Expose to Network

Make the server accessible on your local network:

refine start --host 0.0.0.0

Override Platform

Force a specific platform:

refine start --platform nextjs

Production Checklist

Before running in production:

Build your application: refine build
Set environment variables
Configure your reverse proxy (nginx, Apache)
Set up SSL/TLS certificates
Configure monitoring and logging
Test all functionality

Environment Variables

Set production environment variables:

NODE_ENV=production PORT=8080 refine start

For different platforms:

Vite

.env.production

VITE_API_URL=https://api.production.com
VITE_APP_TITLE=My Production App

Next.js

.env.production

NEXT_PUBLIC_API_URL=https://api.production.com
DATABASE_URL=postgresql://...

Package Manager Scripts

Add to your package.json:

package.json

{
  "scripts": {
    "dev": "refine dev",
    "build": "refine build",
    "start": "refine start",
    "start:prod": "NODE_ENV=production refine start --port 8080"
  }
}

Run with:

npm start

Deployment

Using PM2

Keep your app running with PM2:

npm install -g pm2
pm2 start "refine start" --name "refine-app"

pm2 status
pm2 logs refine-app
pm2 restart refine-app

Using Docker

Create a Dockerfile:

Dockerfile

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm ci --only=production
EXPOSE 4173
CMD ["npx", "refine", "start"]

Build and run:

docker build -t refine-app .
docker run -p 4173:4173 refine-app

Using systemd

Create a systemd service:

/etc/systemd/system/refine-app.service

[Unit]
Description=Refine Application
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/refine-app
ExecStart=/usr/bin/npm start
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable refine-app
sudo systemctl start refine-app
sudo systemctl status refine-app

Reverse Proxy Configuration

nginx

/etc/nginx/sites-available/refine-app

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:4173;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Apache

/etc/apache2/sites-available/refine-app.conf

<VirtualHost *:80>
    ServerName example.com
    
    ProxyPreserveHost On
    ProxyPass / http://localhost:4173/
    ProxyPassReverse / http://localhost:4173/
</VirtualHost>

Platform-Specific Notes

Vite

Uses vite preview to serve the built files
Serves from dist/ directory
Not intended for production use - use a proper static file server or CDN

Next.js

Runs a Node.js server for SSR and API routes
Requires Node.js runtime in production
Can use standalone output for smaller deployments

Remix

Uses remix-serve for full-stack Remix apps
Can deploy to edge runtimes (Cloudflare Workers, etc.)
SPA mode uses Vite preview

Monitoring

Health Checks

Create a health check endpoint:

src/pages/health.tsx

export default function Health() {
  return new Response('OK', { status: 200 })
}

Check from your monitoring tool:

curl http://localhost:4173/health

Logging

Capture logs for monitoring:

refine start 2>&1 | tee -a logs/app.log

Troubleshooting

Port Already in Use

Change the port:

refine start --port 8080

Build Directory Not Found

Ensure you’ve built the app first:

refine build
refine start

Environment Variables Not Loading

Check your .env.production file and ensure variables are prefixed correctly:

Vite: VITE_*
Next.js: NEXT_PUBLIC_* for client-side

High Memory Usage

For Next.js, reduce memory usage:

NODE_OPTIONS="--max-old-space-size=512" refine start

Getting Started

Commands

Usage

Options

How It Works

Platform-Specific Commands

Examples

Basic Usage

Custom Port

Expose to Network

Override Platform

Production Checklist

Environment Variables

Vite

Next.js

Package Manager Scripts

Deployment

Using PM2

Using Docker

Using systemd

Reverse Proxy Configuration

nginx

Apache

Platform-Specific Notes

Vite

Next.js

Remix

Monitoring

Health Checks

Logging

Troubleshooting

Port Already in Use

Build Directory Not Found

Environment Variables Not Loading

High Memory Usage

Next Steps

Build docs developers (and LLMs) love

Getting Started

Commands

​Usage

​Options

​How It Works

​Platform-Specific Commands

​Examples

​Basic Usage

​Custom Port

​Expose to Network

​Override Platform

​Production Checklist

​Environment Variables

​Vite

​Next.js

​Package Manager Scripts

​Deployment

​Using PM2

​Using Docker

​Using systemd

​Reverse Proxy Configuration

​nginx

​Apache

​Platform-Specific Notes

​Vite

​Next.js

​Remix

​Monitoring

​Health Checks

​Logging

​Troubleshooting

​Port Already in Use

​Build Directory Not Found

​Environment Variables Not Loading

​High Memory Usage

​Next Steps

Build docs developers (and LLMs) love

Usage

Options

How It Works

Platform-Specific Commands

Examples

Basic Usage

Custom Port

Expose to Network

Override Platform

Production Checklist

Environment Variables

Vite

Next.js

Package Manager Scripts

Deployment

Using PM2

Using Docker

Using systemd

Reverse Proxy Configuration

nginx

Apache

Platform-Specific Notes

Vite

Next.js

Remix

Monitoring

Health Checks

Logging

Troubleshooting

Port Already in Use

Build Directory Not Found

Environment Variables Not Loading

High Memory Usage

Next Steps