VitePress

How to Integrate and Deploy VitePress with Strapi

Integrating VitePress with Strapi creates a powerful stack, combining dynamic content management with fast static site generation. Here’s how to set up and deploy these technologies for production.

1. Set Up the Development Environment

Create separate directories for the VitePress frontend and Strapi backend:

project-root/
├── frontend/             # VitePress application
│   ├── docs/
│   ├── .vitepress/
│   └── package.json
├── backend/              # Strapi application
│   ├── src/
│   ├── config/
│   └── package.json
└── README.md

Initialize VitePress in the frontend directory:

npm init vitepress

Set up Strapi in the backend directory:

npx create-strapi-app@latest .

2. Configure API Endpoints

Create necessary content types and API endpoints through the Strapi admin panel.

Then set up an API client in your VitePress project:

// .vitepress/api/strapi.js
import axios from 'axios'

const apiURL = import.meta.env.VITE_API_URL || 'http://localhost:1337/api'

const api = axios.create({
  baseURL: apiURL,
  headers: {
    'Content-Type': 'application/json'
  }
})

export default api

3. Use Data Fetching Strategies

Create modular fetch functions for different content types:

// .vitepress/api/articles.js
import api from './strapi'

export const getArticles = async (params = {}) => {
  try {
    const response = await api.get('/articles', { params })
    return response.data
  } catch (error) {
    console.error('Error fetching articles:', error)
    return { data: [] }
  }
}

4. Implement Dynamic Route Generation

Generate routes based on your Strapi content:

// .vitepress/config.js
import { defineConfig } from 'vitepress'
import { getArticles } from './api/articles'

5. Adopt Deployment Best Practices

Use environment variables for API URLs, but do not expose sensitive tokens in client-accessible variables like VITE_API_TOKEN. Store and use tokens securely on the server side.

Implement proper caching strategies:

// .vitepress/api/cache.js
const cache = new Map()

export const getCachedData = async (key, fetchFn, ttl = 60000) => {
  const cachedItem = cache.get(key)
  
  if (cachedItem && Date.now() - cachedItem.timestamp < ttl) {
    return cachedItem.data
  }
  
  const data = await fetchFn()
  
  cache.set(key, {
    data,
    timestamp: Date.now()
  })
  
  return data
}

Configure CORS in Strapi for production by exporting an array with the 'strapi::cors' middleware in 'config/middlewares.js', like this:

module.exports = [
  // ...other middlewares
  {
    name: 'strapi::cors',
    config: {
      origin: ['https://your-vitepress-site.com'],
      headers: ['Content-Type', 'Authorization', 'Origin'],
      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
    },
  },
];

Set up a webhook in Strapi to trigger VitePress rebuilds:

// Strapi webhook configuration
{
  "name": "Trigger VitePress rebuild",
  "url": "https://api.netlify.com/build_hooks/your-build-hook-id",
  "headers": {
    "Content-Type": "application/json"
  },
  "events": [
    "entry.create",
    "entry.update",
    "entry.delete"
  ]
}

The configuration of webhooks in Strapi lets you automate your static site generation process. This approach is similar to static site generation with Strapi, where changes in content trigger site rebuilds.

Optimize Strapi queries for performance:

const getOptimizedArticles = async () => {
  const response = await api.get('/articles', {
    params: {
      fields: ['title', 'slug', 'publishedAt'],
      populate: {
        featuredImage: {
          fields: ['url', 'alternativeText']
        }
      },
      pagination: {
        page: 1,
        pageSize: 10
      },
      sort: ['publishedAt:desc']
    }
  })
  return response.data
}

These steps will help you create a robust integration between VitePress and Strapi that is ready for production. This setup gives you dynamic content management with the speed benefits of static sites.

We recommend updating both platforms, implementing proper error handling, and monitoring your deployment. This will give you a flexible, scalable solution for content-driven websites that can grow with your needs.

Project Example (+ GitHub Project Repo)

Let's walk through a real-world example of how integrating VitePress with Strapi works.

Project Architecture

The architecture follows a clean separation of concerns:

• Strapi Backend: Handles content creation and storage.
• VitePress Frontend: Generates static pages based on Strapi content.
• API Layer: Connects Strapi with VitePress.

This setup allows content editors to work within Strapi while developers focus on frontend development with VitePress.

Key Integration Points

There are three core elements that drive the integration:

1. Content Fetching: VitePress fetches data from Strapi’s API during the build process.
2. Dynamic Route Generation: VitePress generates routes based on Strapi content.
3. Markdown Rendering: Strapi’s content is converted to Markdown for VitePress to process.

Code Walkthrough

Let's examine key code snippets from a sample GitHub project showing Strapi integration (note: this example uses React, but the concepts apply to VitePress):

For API configuration:

// api.js
import axios from 'axios';

const api = axios.create({
  baseURL: 'http://localhost:1337/api',
});

export const fetchArticles = async () => {
  try {
    const response = await api.get('/articles');
    return response.data;
  } catch (error) {
    console.error('Error fetching articles:', error);
    return [];
  }
};

This creates a reusable API client for fetching Strapi data. You can use this during the build process in VitePress.

For dynamic route generation, VitePress relies on its file-based routing system and does not support an asynchronous 'buildEnd' hook for injecting routes. Instead, generate route files or use available plugins and build-time scripts to create content dynamically.

For content rendering, create a Vue component:

<!-- ArticleContent.vue -->
<script setup>
import { ref, onMounted } from 'vue'
import { fetchArticles } from '../api'

const articles = ref([])

onMounted(async () => {
  const response = await fetchArticles()
  articles.value = response.data
})
</script>

<template>
  <div>
    <article v-for="article in articles" :key="article.id">
      <h2>{{ article.attributes.title }}</h2>
      <div v-html="article.attributes.content"></div>
    </article>
  </div>
</template>

You can use this component within VitePress Markdown files:

# Our Blog

Here are our latest articles:

<ArticleContent />

This setup combines the best of both worlds—content management through Strapi and static site generation through VitePress. Content editors manage content in Strapi's interface, while developers benefit from VitePress for high-performance, static site generation.

Strapi Open Office Hours

If you have any questions about Strapi 5 or just would like to stop by and say hi, you can join us at Strapi's Discord Open Office Hours, Monday through Friday, from 12:30 pm to 1:30 pm CST: Strapi Discord Open Office Hours.

For more details, visit the Strapi documentation and the Vitepress documentation.