Integrate VitePress at a Specific Route within Nuxt Project

[r00tmeister]

Title: Integrate VitePress at a Specific Route within Nuxt Project

Description:

I'm working on a Nuxt project and would like to integrate VitePress to serve documentation at a desired route (e.g., /docs). I'm encountering challenges in configuring and seamlessly embedding VitePress within the existing Nuxt structure.

Key Questions:

• How can I set up VitePress to function as a subdirectory/route within the Nuxt application?
• What's the recommended way to handle potential conflicts between Nuxt routing and VitePress routing?
• Are there any Nuxt-specific configuration considerations to be aware of?

Desired Outcome:

• A clear step-by-step integration guide.
• Best practices for managing Nuxt and VitePress routing together.
• Troubleshooting tips for common issues that might arise.

Additional Context:

• Nuxt Version: [Nuxt 3.11.1 with Nitro 2.9.6]
• VitePress Version: [vitepress v1.1.0]
• Deployment Environment: (Azure App Service - Static Web App)

On local machine both work:

Nuxt: http://localhost:3000/
Vitepress: http://localhost:5173/

** Current Nuxt config: **

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  postcss: {
    plugins: {
      tailwindcss: {},
      autoprefixer: {},
    },
  },
  css: [
    "~/assets/css/tailwind.css"
  ],
  debug: true,
  app: {
    head: {
      link: [
        { rel: "stylesheet", href: "https://fonts.googleapis.com/css2?family=Lato:wght@400;700&display=swap%22%3E" },
      ]
    },
  },
  modules: ['@pinia/nuxt', '@nuxtjs/tailwindcss', '@nuxt/test-utils','@nuxt/test-utils/module'],
  pinia: {
    storesDirs: ['./stores/**', './custom-folder/stores/**'],
  },
  devtools: {
    enabled: true,

    timeline: {
      enabled: true,
    },
  },
});

** Current azure Github actions pipeline **

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened] 

jobs:
  build_and_deploy:
    if: github.event_name == 'push' || github.event_name == 'pull_request' 
    runs-on: ubuntu-latest
    name: Build and Deploy

    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true 
          lfs: false

      - name: Clean up and Install Dependencies
        run: |
          rm -rf package-lock.json node_modules
          npm install
      - name: Build
        run: npm run build && npm run generate

      - name: Deploy 
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API__05638FA03 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} 
          action: "upload"
          app_location: "/"
          api_location: ".output/server"
          output_location: ".output/public"


  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API__05638FA03 }}
          action: "close"

Thank you for your assistance!

[randomseed42]

I also had the same thought earlier, while when I tried to design it, it seems a lot of conflicts not only in routing but also design part, like in Nuxt there is the app header with logo and nav etc, where should the vitepress app header exist? I believe it can be resolved with customize vitepress theme, but it lost the original purpose of using VitePress for fast and pretty documentation. Per my thought, there might be two solutions: 1. use separate sites for Nuxt main web app and Vitepress as documentation, 2. try the under developing @nuxt/content module. Just my two cents...

[randomseed42]

I did some further study and test, it seems using iframe can work almost seamlessly. Basically just use docs:build to generate vitepress static html and assets and put them in nuxt's public sub folder like public/docs, then add a nuxt page like content to hold the iframe with src=/docs. Some settings to be done to make sure the links are well connected. Below is what I did:

• create nuxt project
• pnpm add vitepress and pnpm vitepress init and set root as ./docs
• in package.json set docs:build as vitepress build docs --base /docs/ --outDir public/docs
• in docs/.vitepress/config.ts', add config vite: { build: { assetsDir: "../" } }(this one is tricky, otherwise you may seeHydration completed but contains mismatches.` errors)
• in docs/.vitepress/theme/style.css set .VPNav { display: none } which will hide vitepress header to avoid conflict with your nuxt app-header
• in nuxt pages like content.vue, insert `<iframe src="/docs" frameborder="0" w-100vw/>"
• then do pnpm docs:build && pnpm generate, then serve the dist folder like serve -l 8080 dist
• you can go to localhost:8080/content to see the embeded iframe then, since it is an iframe which is served in your nuxt public folder, there should be no cors issue or routing issues

https://codesandbox.io/p/devbox/nuxt-vitepress-ywhvwq

[Dragoneel]

Why not keeping things simple and build VitePress directly into the "public/docs" folder, you will not have any route conflict (as long as you open your doc in a new tab) and your documentation will be accessible under yourdomain.com/docs

[randomseed42]

Why not keeping things simple and build VitePress directly into the "public/docs" folder, you will not have any route conflict (as long as you open your doc in a new tab) and your documentation will be accessible under yourdomain.com/docs

yes, that's exactly what I'm doing now :) thanks for the advice!