Deploying Nuxt Static Sites with Nginx

When it comes to deploying modern web applications, Nuxt 3's static site generation (SSG) offers an excellent balance of performance, SEO, and simplicity. Combined with Nginx's battle-tested serving capabilities, you get a deployment setup that's fast, reliable, and cost-effective. Let's walk through the complete process.

Why Static Site Generation?

Static site generation pre-renders your application at build time, producing pure HTML, CSS, and JavaScript files that can be served from any static file server. The benefits are compelling:

• Performance: No server-side rendering overhead means instant page loads
• SEO: Search engines get fully rendered HTML
• Simplicity: No Node.js server required in production
• Cost: Can host on any basic web server
• Reliability: Fewer moving parts means fewer things can break

Configuring Nuxt for Static Generation

First, configure your Nuxt app to generate static files. In your nuxt.config.ts:

export default defineNuxtConfig({
  ssr: false,  // Disable server-side rendering for static generation
})

The ssr: false setting tells Nuxt to generate a static site. This is essential for our use case.

Building Your Static Site

Generate your static files with a single command:

pnpm run generate

This command:

1. Builds your application
2. Generates static HTML for all your routes
3. Optimizes assets (CSS, JS, images)
4. Creates a .output/public directory ready for deployment

The output will contain:

• index.html - Your main entry point
• /_nuxt/ - Hashed JavaScript and CSS bundles
• Other static assets (images, fonts, etc.)

Deploying to Nginx

Step 1: Package Your Site

Create a compressed archive of your built site:

cd .output/public
tar -czf package.tgz *

Step 2: Upload and Extract

On your server, deploy with this script:

#!/bin/bash
# Check if target directory exists, remove if it does
if [ -d "/var/www/zhongjing" ]; then
    echo "Removing existing directory: /var/www/zhongjing"
    rm -rf /var/www/zhongjing
fi

# Create target directory
mkdir -p /var/www/zhongjing

# Extract archive to target directory
tar -xzf /var/www/package.tgz -C /var/www/zhongjing

# Set proper ownership
sudo chown -R www-data:www-data zhongjing/

echo "Deployment complete"

This approach ensures clean deployments with no stale files.

Configuring Nginx

Here's a production-ready Nginx configuration optimized for Nuxt static sites:

server {
    server_name zhongjing.hitdic.com;

    root /var/www/zhongjing;
    index index.html;

    # 1. Handle Nuxt static assets (highest priority)
    # Nuxt bundles are in _nuxt folder with hashes, no directory checks needed
    location ^~ /_nuxt/ {
        alias /var/www/zhongjing/_nuxt/;
        expires 1y;
        add_header Cache-Control "public, immutable";
        # Only find files, 404 if not found (avoid $uri/ redirects)
        try_files $uri =404;
    }

    # 2. Handle other static files
    location ~* \.(css|js|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        try_files $uri =404;
    }

    # 3. Main site logic (SPA routing)
    location / {
        # Remove $uri/ to avoid directory redirect interference
        try_files $uri /index.html;

        # Disable HTML caching
        if ($request_uri ~ ^/(.*)\.(html|htm)$) {
            expires -1;
        }
    }
}

Deplot nginx configuation

sudo ln -sf /etc/nginx/sites-available/data.hitdic.com /etc/nginx/sites-enabled/

Key Configuration Points

Asset Caching (/_nuxt/ and static files)

• expires 1y: Long cache lifetime for hashed assets
• Cache-Control "public, immutable": Tells browsers assets won't change
• try_files $uri =404: Directly return 404 for missing assets (no redirects)

SPA Routing

• try_files $uri /index.html: Falls back to index.html for non-file routes
• This enables client-side routing to work correctly

HTML Caching

• expires -1: Prevents HTML caching to ensure fresh content

Clearing Browser Cache

Very important: clear your browser cache! ERR_TOO_MANY_REDIRECTS (301) errors are aggressively cached by browsers. Make sure to:

• Use Incognito Mode to test the page
• Or open DevTools (F12) and right-click the refresh button to select "Empty Cache and Hard Reload"

If you still see errors, check the browser's Network panel to see what URLs are being requested (look for double slashes // or unusual paths).

Performance Optimization Tips

1. Enable Gzip Compression

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
gzip_min_length 1000;

2. Use HTTP/2

listen 443 ssl http2;

Conclusion

Deploying a Nuxt static site with Nginx gives you a fast, reliable, and cost-effective hosting solution. The key is proper configuration:

1. Generate static files with ssr: false
2. Use proper Nginx location blocks for asset routing
3. Implement aggressive caching for hashed assets
4. Handle SPA routing with try_files $uri /index.html
5. Clear browser cache when troubleshooting redirect issues

This setup scales well, handles high traffic, and provides an excellent user experience with minimal maintenance overhead. Whether you're deploying a personal portfolio or a production application, this configuration has you covered.

Happy deploying!