Deployment & Hosting Guide

The Tracepos Developer Hub is built on VuePress 2 and bundled with Vite. When compiled, VuePress generates a static Single Page Application (SPA) optimized for performance, SEO, and fast global delivery.

1. Building for Production

Compile your Markdown source documentation into production-ready static assets:

npm run docs:build

The output will be generated in docs/.vuepress/dist/. This directory contains static HTML, CSS, client-side JavaScript bundles, and static assets.

2. Recommended Hosting Targets

Platforms like Vercel and Netlify offer automated deployments on every Git push:

  • Build Command: npm run docs:build
  • Output Directory: docs/.vuepress/dist
  • Node Version: >= 18.x

Configuration (vercel.json)

{
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vuepress/dist",
  "framework": null
}

Option B: GitHub Pages

If your documentation is hosted on GitHub:

  1. Set up a GitHub Action (.github/workflows/docs.yml) to automatically build and push the dist/ directory to the gh-pages branch upon pushes to main.
  2. Configure custom domain mapping (e.g. developers.tracepos.com) with automated SSL certificates.

Option C: Nginx / Apache on Self-Hosted Servers

Serve the compiled dist/ directory directly with Nginx:

server {
    listen 80;
    server_name developers.tracepos.com;
    root /var/www/tracepos-api-docs/docs/.vuepress/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

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

3. Maintenance & Testing Checklist

Before deploying updates to the developer hub:

  1. Verify Route Matching: Ensure all Markdown files referenced in .vuepress/config.js navigation and sidebar configs exist.
  2. Validate Code Examples: Test cURL, Node.js, Python, and PHP snippets against real staging endpoints.
  3. Check Code Groups Syntax: Ensure VuePress 2 container syntax (:::: code-group and ::: code-group-item) is formatted properly with matching colons.
  4. Clean Production Build: Run npm run docs:build and verify exit code 0.