Skip to main content
The build command creates an optimized production build of your Refine application.

​
Usage

refine build [options] [args...]

​
Options

​
-p, --platform <platform>
string
Specify the platform to run the build command on. The CLI auto-detects your project type, but you can override it.Choices: vite, nextjs, remix, remix-spa, remix-vite, craco
refine build --platform vite
​
args...
string[]
Additional arguments passed directly to the underlying build tool
refine build --mode production

​
How It Works

The build command:
  1. Detects your project type (Vite, Next.js, Remix, etc.)
  2. Runs the appropriate build command for your platform
  3. Creates optimized production assets
  4. Outputs build artifacts to the dist or build directory

​
Platform-Specific Commands

The CLI runs these commands based on your project type:
  • Vite: vite build
  • Next.js: next build
  • Remix: remix build
  • Craco: craco build

​
Examples

​
Basic Usage

Build your application: 
refine build
Output
vite v5.0.0 building for production...
✓ 1234 modules transformed.
dist/index.html                   0.45 kB │ gzip:  0.30 kB
dist/assets/index-a1b2c3d4.css   24.32 kB │ gzip:  6.54 kB
dist/assets/index-e5f6g7h8.js   152.41 kB │ gzip: 49.23 kB
✓ built in 3.45s

​
Override Platform

Force a specific platform build: 
refine build --platform nextjs
Output
✓ Creating an optimized production build
✓ Compiled successfully
✓ Linting and checking validity of types
✓ Collecting page data
✓ Generating static pages (5/5)
✓ Finalizing page optimization

​
Production Build with Source Maps

For Vite projects: 
refine build --sourcemap

​
Analyze Bundle Size

For Vite projects with the rollup-plugin-visualizer: 
refine build --mode analyze

​
Build with Custom Mode

For Vite projects: 
refine build --mode staging

​
Build Output

​
Vite Projects

Build artifacts are output to dist/: 
dist/
├── index.html
├── assets/
│   ├── index-[hash].css
│   └── index-[hash].js
└── favicon.ico

​
Next.js Projects

Build artifacts are output to .next/: 
.next/
├── static/
│   ├── chunks/
│   └── css/
├── server/
└── build-manifest.json

​
Remix Projects

Build artifacts are output to build/: 
build/
├── index.js
├── client/
└── server/

​
Package Manager Scripts

Add to your package.json:
package.json
{
  "scripts": {
    "build": "refine build",
    "build:analyze": "refine build --mode analyze",
    "build:staging": "refine build --mode staging"
  }
}
Run with: 
npm run build

​
Environment Variables

Set environment-specific variables: 
NODE_ENV=production refine build
For Vite projects, create environment files:
.env.production
VITE_API_URL=https://api.production.com
VITE_APP_TITLE=My Production App

​
Optimization

The build command automatically:
  • Minifies JavaScript and CSS
  • Tree-shakes unused code
  • Code-splits for optimal loading
  • Optimizes assets (images, fonts)
  • Generates source maps (if configured)

​
Common Build Configurations

​
Vite Build Config

vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    outDir: 'dist',
    sourcemap: true,
    minify: 'terser',
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
        },
      },
    },
  },
})

​
Next.js Build Config

next.config.js
module.exports = {
  output: 'standalone',
  compress: true,
  generateBuildId: async () => {
    return 'my-build-id'
  },
}

​
After Building

Once your build completes:
  1. Test the production build locally: 
    refine start
  2. Deploy to your hosting provider:
    • Vercel, Netlify (for static/SSR)
    • AWS, Google Cloud (for custom hosting)
    • Docker containers
  3. Verify the build:
    • Check bundle sizes
    • Test all routes
    • Verify environment variables

​
Troubleshooting

​
Build Fails with Memory Error

Increase Node.js memory limit: 
NODE_OPTIONS="--max-old-space-size=4096" refine build

​
Type Errors During Build

For TypeScript projects: 
npm run type-check
Fix any type errors before building.

​
Missing Dependencies

Ensure all dependencies are installed: 
npm install
refine build

​
Build is Too Large

  1. Analyze bundle size
  2. Remove unused dependencies
  3. Enable code splitting
  4. Optimize imports (use tree-shakeable imports)
// Instead of:
import { Button } from 'antd'

// Use:
import Button from 'antd/es/button'

​
CI/CD Integration

​
GitHub Actions

.github/workflows/deploy.yml
name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v3
        with:
          name: build
          path: dist/

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us