Vercel

Use Vercel rewrites to serve your blog at yoursite.com/blog. Rewrites proxy requests to Waldium without changing the URL in the visitor's browser, creating a seamless experience.

How Rewrites Work

Vercel rewrites map incoming requests to different destinations transparently. When someone visits yoursite.com/blog, Vercel fetches content from your-subdomain.waldium.app/blog and returns it—but the visitor's browser still shows yoursite.com/blog.

This differs from redirects, which send users to a new URL entirely.

Configuration

Add rewrites to your vercel.json file. Replace [SUBDOMAIN] with your Waldium subdomain (found in your dashboard URL).

{
  "rewrites": [
    {
      "source": "/blog",
      "destination": "https://[SUBDOMAIN].waldium.app/blog"
    },
    {
      "source": "/blog/:path*",
      "destination": "https://[SUBDOMAIN].waldium.app/blog/:path*"
    },
    {
      "source": "/waldium-assets/:path*",
      "destination": "https://[SUBDOMAIN].waldium.app/waldium-assets/:path*"
    },
    {
      "source": "/_waldium/:path*",
      "destination": "https://[SUBDOMAIN].waldium.app/_waldium/:path*"
    },
    {
      "source": "/api/waldium-request",
      "destination": "https://[SUBDOMAIN].waldium.app/_waldium/api/request"
    }
  ]
}

What Each Rewrite Does

Name
/blog
Description
Routes the base blog URL to Waldium.
Name
/blog/:path*
Description
Catches all blog subpaths (individual posts, categories, etc.) and routes them to Waldium.
Name
/waldium-assets/:path*
Description
Proxies static assets like CSS, JavaScript, and images.
Name
/_waldium/:path*
Description
Handles internal Waldium API routes and functionality.
Name
/api/waldium-request
Description
Routes API requests for interactive features.

Ordering Matters

Vercel processes rewrites in order. If you have other rewrites in your configuration, place the blog rewrites appropriately:

More specific patterns should come before general patterns
The /blog/:path* pattern should come after the exact /blog match
Your existing rewrites shouldn't conflict with /blog paths

Custom Subpath

If you want to host your blog at a path other than /blog (for example, /articles or /news), update all the source patterns:

{
  "rewrites": [
    {
      "source": "/articles",
      "destination": "https://[SUBDOMAIN].waldium.app/articles"
    },
    {
      "source": "/articles/:path*",
      "destination": "https://[SUBDOMAIN].waldium.app/articles/:path*"
    },
    {
      "source": "/waldium-assets/:path*",
      "destination": "https://[SUBDOMAIN].waldium.app/waldium-assets/:path*"
    },
    {
      "source": "/_waldium/:path*",
      "destination": "https://[SUBDOMAIN].waldium.app/_waldium/:path*"
    }
  ]
}

When using a custom subpath, ensure your Waldium site is also configured for the same path. Contact support if you need to change your blog's base path.

Headers Configuration

If you need to set custom headers (for security or CORS), add them to vercel.json:

{
  "rewrites": [
    // ... your rewrites
  ],
  "headers": [
    {
      "source": "/blog/(.*)",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "SAMEORIGIN"
        }
      ]
    }
  ]
}

For Content Security Policy configuration, see the CSP configuration guide.

Deploy and Test

After updating vercel.json:

Commit and push your changes
Wait for deployment to complete
Visit your blog URL at yoursite.com/blog
Test navigation between blog pages
Verify assets load correctly (images, styles, scripts)

Troubleshooting

Blog returns 404:

Verify your Waldium subdomain is correct
Check that rewrites are properly formatted in JSON
Ensure no conflicting rewrites intercept /blog paths

Styles or scripts not loading:

Confirm the /waldium-assets/:path* rewrite is present
Check browser developer tools for blocked requests
Review CSP headers if you have security policies

Interactive features not working:

Ensure the /_waldium/:path* rewrite exists
Check for JavaScript console errors
Verify API routes are properly proxied