Nuxt•19h ago

How to deploy a static nuxt app

export default defineNuxtConfig({
  compatibilityDate: '2024-11-01',
  devtools: { enabled: true },

  app: {
    baseURL: '/site/',
  },


  nitro: {
    static: true,
    output: {
      publicDir: '../dist'
    }
  },

  modules: ['@nuxt/ui', '@nuxt/icon'],


  ssr: true,
})

export default defineNuxtConfig({
  compatibilityDate: '2024-11-01',
  devtools: { enabled: true },

  app: {
    baseURL: '/site/',
  },


  nitro: {
    static: true,
    output: {
      publicDir: '../dist'
    }
  },

  modules: ['@nuxt/ui', '@nuxt/icon'],


  ssr: true,
})

I am having issues trying to deploy a static nuxt app so that my fastapi backend serves it at /site and redirects any rendered page to /site/**

10 Replies

kapa.ai•19h ago

Hi @Ken. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- To deploy a static Nuxt app to be served at a subpath (e.g., /site/) by your FastAPI backend, you need to ensure that: 1. Nuxt generates the site with the correct base URL for assets and routing. 2. The output is placed in a directory (dist/) that FastAPI can serve at /site. 3. All client-side navigation and direct URL access are handled (e.g., with a fallback to index.html or 200.html). 1. Nuxt Configuration Your config is mostly correct. The key part is setting app.baseURL: '/site/', which ensures all asset and router links are prefixed with /site/. This is confirmed to work for static builds as long as no environment variable (like NUXT_APP_BASE_URL) overrides it at build time. Double-check your .env files to avoid accidental overrides, as seen in this issue discussion. 2. Generating the Static Site Use the following command to generate your static site:

npx nuxi generate

npx nuxi generate

This will output your static files to the dist/ directory (as configured). You can then configure FastAPI to serve this directory at the /site route. 3. FastAPI Static Files Setup In FastAPI, you can mount the static directory like this:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()
app.mount("/site", StaticFiles(directory="dist", html=True), name="site")

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()
app.mount("/site", StaticFiles(directory="dist", html=True), name="site")

The html=True option ensures that unknown routes fall back to index.html, which is important for client-side routing in SPAs. 4. Redirects and Fallbacks For static hosting, Nuxt generates index.html, 200.html, and 404.html by default. If you want all unknown routes under /site to be handled by your Nuxt app (for client-side routing), ensure your FastAPI static files setup uses the fallback as above. If you need more advanced redirect logic, you may need to handle it in FastAPI before serving static files. 5. Troubleshooting - If your assets are not loading with the /site/ prefix, check your generated index.html and asset links. If they are missing the prefix, ensure no environment variable is overriding your baseURL (see this issue). - If you see 404s for client-side routes, make sure FastAPI is serving index.html as a fallback for all unknown routes under /site. References - Nuxt Static Hosting Guide - Nuxt baseURL issue discussion - Nuxt Deployment Docs If you follow these steps and ensure your baseURL is set correctly, your static Nuxt app should work at /site/ behind FastAPI. If you still encounter issues, double-check for environment variable overrides and verify the output paths in your generated files. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•19h ago

<@673071394615066629> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

KenOP•19h ago

so I have my project setup like this: API/Backend - FastAPI app API/frontend - Nuxt3 app API/dist - frontend build output for static @kapa.ai

kapa.ai•19h ago

Let me check the knowledge base for you again. One moment! :books: Sorry @Ken, I seem to be having a bit of trouble. Don't worry though, I've pinged my support and they will try to fix me up! :technologist: Perhaps try again in 15mins?

KenOP•19h ago

@kapa.ai can you write me a new nuxt cnfig file?

kapa.ai•19h ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Certainly! Based on the knowledge sources, here is a Nuxt 3 configuration file (nuxt.config.ts) for deploying a static site to a subdirectory (e.g., /site/). This config ensures that all assets and routes are correctly prefixed, and the output is generated in the dist/ directory:

export default defineNuxtConfig({
  compatibilityDate: '2024-11-01',
  devtools: { enabled: true },
  ssr: true, // Static generation still uses SSR at build time

  app: {
    baseURL: '/site/', // Prefix all routes and assets with /site/
  },

  nitro: {
    preset: 'static', // Use static site generation
    output: {
      publicDir: '../dist', // Output directory for static files
    },
  },

  modules: ['@nuxt/ui', '@nuxt/icon'],
})

export default defineNuxtConfig({
  compatibilityDate: '2024-11-01',
  devtools: { enabled: true },
  ssr: true, // Static generation still uses SSR at build time

  app: {
    baseURL: '/site/', // Prefix all routes and assets with /site/
  },

  nitro: {
    preset: 'static', // Use static site generation
    output: {
      publicDir: '../dist', // Output directory for static files
    },
  },

  modules: ['@nuxt/ui', '@nuxt/icon'],
})

Important notes: - Make sure you do not have a NUXT_APP_BASE_URL or similar environment variable in your .env file that could override the baseURL setting, as this can cause asset paths to be incorrect (see this issue for details). - To generate your static site, run npx nuxi generate. The output will be in the dist/ directory, ready to be served at /site/ by your backend. - This configuration is based on the official Nuxt documentation and real-world troubleshooting for static subdirectory deployments Nuxt Static Hosting Guide, baseURL issue discussion. If you need to serve the site from a different subdirectory, just change the baseURL accordingly. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•19h ago

<@673071394615066629> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

KenOP•18h ago

@kapa.ai

export default defineNuxtConfig({
  compatibilityDate: '2024-11-01',
  devtools: { enabled: true },
  ssr: true, // Static generation still uses SSR at build time

  app: {
    baseURL: '/site', // Prefix all routes and assets with /site/
  },

  nitro: {
    preset: 'static', // Use static site generation
    output: {
      publicDir: '../dist', // Output directory for static files
    },
  },

  modules: ['@nuxt/ui', '@nuxt/icon'],
})

export default defineNuxtConfig({
  compatibilityDate: '2024-11-01',
  devtools: { enabled: true },
  ssr: true, // Static generation still uses SSR at build time

  app: {
    baseURL: '/site', // Prefix all routes and assets with /site/
  },

  nitro: {
    preset: 'static', // Use static site generation
    output: {
      publicDir: '../dist', // Output directory for static files
    },
  },

  modules: ['@nuxt/ui', '@nuxt/icon'],
})

Still having issues where my nginx and fastapi isnt able to serve nuxt3app and I when I access the site, I keep getting `{'detail': "Not found'} API/Backend/main.py

app.mount("/site", StaticFiles(directory="../dist", html=True), name="frontend")

app.mount("/site", StaticFiles(directory="../dist", html=True), name="frontend")

kapa.ai•18h ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Your Nuxt config is almost correct, but there are a few important details to check based on the knowledge sources: 1. baseURL should end with a trailing slash
Nuxt expects app.baseURL to end with a trailing slash for correct asset and route resolution.
Change:

   app: {
     baseURL: '/site/', // <-- trailing slash is important!
   },

   app: {
     baseURL: '/site/', // <-- trailing slash is important!
   },

See this issue for confirmation. 2. Static output directory
By default, Nuxt outputs static files to .output/public. If you want to use ../dist, make sure your FastAPI StaticFiles mount points to the correct absolute path. Relative paths like "../dist" may not resolve as expected depending on your working directory. Try using an absolute path or ensure your working directory is correct. 3. Serving static files with FastAPI
Your FastAPI code should look like:

   from fastapi.staticfiles import StaticFiles
   app.mount("/site", StaticFiles(directory="dist", html=True), name="frontend")

   from fastapi.staticfiles import StaticFiles
   app.mount("/site", StaticFiles(directory="dist", html=True), name="frontend")

Make sure the dist directory exists at the expected location relative to where you run your FastAPI app. 4. Nginx configuration
The knowledge sources do not provide explicit Nginx configuration, but ensure that Nginx is proxying requests to FastAPI and not intercepting /site requests itself. 5. Check for environment variable overrides
If you have a .env file with NUXT_APP_BASE_URL, it will override your config and break asset paths. Remove or correct this if present see this issue. Summary of changes:

export default defineNuxtConfig({
  compatibilityDate: '2024-11-01',
  devtools: { enabled: true },
  ssr: true,
  app: {
    baseURL: '/site/', // <-- trailing slash
  },
  nitro: {
    preset: 'static',
    output: {
      publicDir: '../dist'
    }
  },
  modules: ['@nuxt/ui', '@nuxt/icon'],
})

export default defineNuxtConfig({
  compatibilityDate: '2024-11-01',
  devtools: { enabled: true },
  ssr: true,
  app: {
    baseURL: '/site/', // <-- trailing slash
  },
  nitro: {
    preset: 'static',
    output: {
      publicDir: '../dist'
    }
  },
  modules: ['@nuxt/ui', '@nuxt/icon'],
})

If you still get {'detail': "Not found"}: - Double-check the path to your static files. - Ensure the generated dist directory contains an index.html and _nuxt folder with assets. - Make sure FastAPI is running from the correct working directory so "dist" resolves properly. If these steps do not resolve your issue, the knowledge sources do not provide further troubleshooting for FastAPI static file serving with Nuxt static output. The main Nuxt-side requirements are the correct baseURL and output directory configuration, as described above Nuxt Static Hosting Guide, baseURL issue discussion. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•18h ago

<@673071394615066629> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Gaming

Programming

How to deploy a static nuxt app

Did you find this page helpful?