Base URL

What is the Base URL? The Base URL (aka Public Path) configures the URL root of your website. For example, instead of serving your website at https://example.org/* (the Base URL is /), you can serve your website at https://example.org/some-base/* by setting the Base URL to /some-base/.

`base`

To change the Base URL:

Set vite.config.js#base.

// vite.config.js
export default {
  base: '/some-base/'
}

Use import.meta.env.BASE_URL to implement a <Link> component that prepends the Base URL. Example: /examples/base-url/components/Link.jsx.
Use import.meta.env.BASE_URL for referencing static assets living in public/. Example: /examples/base-url/renderer/+onRenderHtml.jsx.

<!-- view-source:https://my-website.com/some-base/ -->
 
<!-- Website is served at https://my-website.com/some-base/ and
     asset URLs are prepended with the Base URL /some-base/ -->
 
<html>
  <head>
    <link href="/some-base/logo.svg" rel="icon">
    <link href="/some-base/style.css" rel="stylesheet" type="text/css">
  </head>
  <body>
    <nav>
      <a href="/some-base/">Landing Page</a>
      <a href="/some-base/about">About Page</a>
    </nav>
    <script src="/some-base/script.js" type="module"></script>
  </body>
</html>

Example:

/examples/base-url/

`baseAssets`

You can change the base only for your asset URLs, while the base of your page URLs is left unchanged.

The most common use case is when deploying assets to a CDN.

// pages/+config.js
 
export default {
  baseAssets: 'https://cdn.example.org/my-website-assets/'
}

The base of your page URLs isn't changed: your website is still served at https://my-website.com/* (the Base URL is still /).

<!-- view-source:https://my-website.com/ -->
 
<html>
  <head>
    <!-- Base URL is 'https://cdn.example.org/my-website-assets/' -->
    <link
      href="https://cdn.example.org/my-website-assets/logo.svg"
      rel="icon"
    >
    <link
      href="https://cdn.example.org/my-website-assets/style.css"
      rel="stylesheet"
      type="text/css"
    >
  </head>
  <body>
    <nav>
      <!-- Base URL is '/' -->
      <a href="/">Landing Page</a>
      <a href="/about">About Page</a>
    </nav>
    <!-- Base URL is 'https://cdn.example.org/my-website-assets/' -->
    <script src="https://cdn.example.org/my-website-assets/script.js" type="module">
  </body>
</html>

You can use process.env.BASE_ASSETS and import.meta.env.BASE_ASSETS to access the baseAssets value in your code.

Example:

/examples/base-url-cdn/

By default, the baseAssets setting applies to both development and production. You can apply it only to production by using process.env.NODE_ENV:

// pages/+config.js
 
const isProduction = process.env.NODE_ENV === 'production'
const baseAssets = isProduction ? 'https://cdn.example.org/my-website-assets/' : undefined
 
export default {
  baseAssets
}

There is work-in-progress to apply it only in production by default.

`baseServer`

You can do both:

Deploy your static assets to a CDN using the baseAssets setting.
Change the Base URL of your server using the baseServer setting.

// pages/+config.js
 
export default {
  baseAssets: 'https://cdn.example.org/my-website-assets/',
  baseServer: '/some-base/'
}

<!-- view-source:https://my-website.com/some-base/ -->
 
<html>
  <head>
    <!-- Base URL is 'https://cdn.example.org/my-website-assets/' -->
    <link
      href="https://cdn.example.org/my-website-assets/logo.svg"
      rel="icon"
    >
    <link
      href="https://cdn.example.org/my-website-assets/style.css"
      rel="stylesheet"
      type="text/css"
    >
  </head>
  <body>
    <nav>
      <!-- Base URL is '/some-base/' -->
      <a href="/some-base/">Landing Page</a>
      <a href="/some-base/about">About Page</a>
    </nav>
    <!-- Base URL is 'https://cdn.example.org/my-website-assets/' -->
    <script src="https://cdn.example.org/my-website-assets/script.js" type="module">
  </body>
</html>

You can use process.env.BASE_SERVER and import.meta.env.BASE_SERVER to access the baseServer value in your code.

Example:

/examples/base-url-server/

Setup

If you set a Base URL for your SSR server, then make sure to properly install renderPage().

Make sure you use renderPage() only for URLs that include the Base URL, for example with Express.js:

// Make sure `/some-base/` aligns with your base setting
app.get('/some-base/*', async (req, res) => {
  // Keep the Base URL (Vike expects it)
  const pageContextInit = { urlOriginal: req.url }
  const pageContext = await renderPage(pageContextInit)
  assert(!pageContext.isBaseMissing)
  // ...
})

Or use pageContext.isBaseMissing:

app.get('*', async (req, res, next) => {
  const pageContextInit = { urlOriginal: req.url }
  const pageContext = await renderPage(pageContextInit)
  if (pageContext.isBaseMissing) return next()
  // ...
})

Both approaches work equally well.

When the Base URL is missing then await renderPage() is effectively synchronous and very quick: the superflous Vike middleware call is negligible.