Netlify

Netlify offers one-click deploys, automatic HTTPS, form handling, and edge functions. Excellent for documentation sites that need advanced features or scale beyond GitHub Pages' limits.

Netlify Configuration

Create netlify.toml in your project root:

[build]
  publish = ".output/public"
  command = "npm run generate"

[build.environment]
  NODE_VERSION = "20"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
  force = false

[[headers]]
  for = "/_nuxt/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/*.js"
  [headers.values]
    Content-Type = "text/javascript; charset=utf-8"

[[headers]]
  for = "/*.css"
  [headers.values]
    Content-Type = "text/css; charset=utf-8"

Deployment Methods

Git Integration

1. Go to netlify.com and sign up
2. Click New site from Git
3. Authorize and select your repository
4. Netlify auto-detects Nuxt and suggests settings
5. Click Deploy site

Deploys trigger automatically when you push to your connected branch.

CLI Deployment

# Install Netlify CLI
npm install -g netlify-cli

# Login to Netlify
netlify login

# Deploy (creates a new site)
netlify deploy --prod

Manual Deploy

1. Run npm run generate locally
2. Go to Netlify dashboard
3. Drag and drop .output/public folder to deploy

Environment Variables

Set in Site settings > Build & deploy > Environment:

NUXT_APP_BASE_URL=/
NUXT_PUBLIC_SITE_URL=https://docs.example.com

Or in netlify.toml:

[build.environment]
  NUXT_PUBLIC_SITE_URL = "https://docs.example.com"

Custom Domain

1. Go to Domain settings
2. Click Add custom domain
3. Configure DNS:
   • Option A: Use Netlify DNS (recommended)
   • Option B: Add CNAME pointing to *.netlify.app

Netlify automatically provisions and renews SSL certificates.

Advanced Features

Deploy Previews

Every pull request gets a unique preview URL. Share with collaborators to review changes before merging.

Enable in Site settings > Build & deploy > Deploy contexts.

Branch Deploys

Deploy multiple branches to different URLs:

[context.staging]
  command = "npm run generate"
  
[context.staging.environment]
  NUXT_PUBLIC_SITE_URL = "https://staging.docs.example.com"

Form Handling

Add Netlify's form handling without backend code:

<form name="feedback" method="POST" data-netlify="true">
  <input type="text" name="name" />
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>

Submissions appear in Forms in your Netlify dashboard.

Edge Functions

Run server-side logic at the CDN edge:

// netlify/edge-functions/hello.ts
export default async () => {
  return new Response("Hello from the edge!")
}

Troubleshooting

Build Failures

Check Deploys for detailed logs. Common issues:

• Node version mismatch (set in netlify.toml)
• Missing dependencies (run npm ci not npm install)
• Environment variables not set

Slow Builds

Enable build caching in Site settings > Build & deploy > Build settings:

[build]
  command = "npm run generate"
  
[build.processing]
  skip_processing = false

SPA Routing Issues

Ensure the redirect rule is present:

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
  force = false