Skip to Content
Vuesho

Deploy

Build your site, then put it on a static host or a server.

vuesho build builds your site with Nitro into .output:

  • .output/public: the pages generated at build time, the files of the browser, and generated files like the sitemap.
  • .output/server: the server, which renders everything else on demand.

Vuesho requires Node.js 24 or later.

Vite Config

The vuesho command runs Vite. A site without a vite.config.ts runs with the Vuesho plugin and its defaults. To pass options to the plugin, or to add other Vite plugins, write the config yourself, and the command uses it:

vite.config.ts
import { defineConfig } from "vite";
import vuesho from "vuesho/vite";

export default defineConfig({
  plugins: [vuesho({ pagesDir: "src/routes" })],
});

vuesho dev, vuesho build and vuesho preview take --host, --port, --open, --base and --mode. With a config, vite dev, vite build and vite preview work too.

What Renders on Demand

A page is either generated at build time into .output/public, or rendered by the server on demand. Three levels set the render mode of a page, and each level overrides the one before it.

Content Sources

The kind of a content source gives the default of its pages:

  • A static source is generated at build time. Your Markdown collections are static, and so is a custom source whose files is a list.
  • A dynamic source, whose files is a function, renders on demand, so the server reads it again while it runs.

Routes

A route sets its own render mode with render. Views, custom pages without params and data routes are generated at build time by default. Custom pages with params and without staticPaths, and API routes with handlers, render on demand by default.

A route that lists your pages, like the sitemap, llms.txt, the search index and the page tree the browser loads, renders on demand as soon as one page it lists does.

Route Rules

The routeRules of Nitro override both levels by path. prerender: false renders the matching pages on demand, here a section of the site:

vite.config.ts
import { defineConfig } from "vite";
import vuesho from "vuesho/vite";

export default defineConfig({
  plugins: [vuesho({ nitro: { routeRules: { "/internal/**": { prerender: false } } } })],
});

To render the whole site on demand, use the pattern "/**". The most specific rule of a path wins, so "/internal/public": { prerender: true } keeps one page of that section generated. A rule names the URL of a page, and the data the browser loads for that page follows it. A rule in nitro.config.ts, or one that a preset adds, applies too.

The build lists the paths it generates from your pages and routes, so the prerender options of Nitro, like routes, crawlLinks and ignore, fail the build. To generate another path, add a prerender: true rule for it or give its route render: "static", and to skip a path, add a prerender: false rule. Only prerender.autoSubfolderIndex is read: with false, which the netlify preset sets, a page is written as guide.html instead of guide/index.html.

A file that a build hook emits has no route on the server. When a rule excludes its path, the build fails and asks for a prerender: true rule of that file.

Session Checks

A page that renders on demand reaches middleware, so a middleware can check a session before it renders. page is the page a request is for, also when the browser loads the data of that page, so one check guards both. This one guards the pages under /internal/ of the example above:

vuesho.config.ts
createSite(docs.toFumadocsSource()).plugins({
  name: "site:session",
  async middleware(request, next, { page }) {
    // `hasSession()` is your own check, like the cookie of your auth library
    if (page.startsWith("/internal/") && !(await hasSession(request))) {
      return new Response("Unauthorized", { status: 401 });
    }
    return next();
  },
});

With "/**": { prerender: false }, every request reaches the server, so a middleware can check the session of the whole site without a list of paths.

The compiled Markdown of a page in your collections is still a file of .output/public, which the browser imports and the host serves without the server. A session check guards the HTML of the page and its data, not that file, so keep content that must stay private out of your collections. The page tree and the search index also list the titles and URLs of a guarded section, unless a meta.json or the filter of the search leaves them out.

Static Hosting

A site where nothing renders on demand is fully static: upload .output/public to any static host. A docs site with Markdown collections and the default plugins is fully static.

A static preset of Nitro, like static or github-pages, builds a static output, which has no server. The build then reads a dynamic source once and generates its pages. What still needs a server fails the build, with each route named: a route that renders on demand, an API route with a handler for another method than GET, and a page that a route rule excludes. A middleware runs while the build generates the pages but never for a request, so the build warns about it.

The build writes 404.html, the not found page of your site. Most static hosts serve it for a URL without a file, so it renders the NotFound of your theme, never a custom page with params.

The build also writes .nojekyll. GitHub Pages leaves out the folders starting with _ without this file, and the data the browser loads for each page is under /_vuesho/.

A host serves a file with the type that its name gives, so a route that isn't a page and has no extension in its path, like /feed, loses the type of its response in the output, and the build warns about it. Give such a route a path with an extension, like /feed.xml.

Server Deployment

By default, the server is a Node.js server. Start it with:

node .output/server/index.mjs

To deploy to a platform, pass the Nitro preset of that platform to the nitro option of the Vite plugin:

vite.config.ts
import { defineConfig } from "vite";
import vuesho from "vuesho/vite";

export default defineConfig({
  plugins: [vuesho({ nitro: { preset: "vercel" } })],
});

The nitro option takes the config of Nitro. Pages generated at build time are still served as files, and the server renders the rest.

Headers and Caching

routeRules of the nitro option sets the headers and the caching of responses by path:

vite.config.ts
import { defineConfig } from "vite";
import vuesho from "vuesho/vite";

export default defineConfig({
  plugins: [
    vuesho({
      nitro: {
        routeRules: {
          "/assets/**": { headers: { "cache-control": "public, max-age=31536000, immutable" } },
          "/api/stars": { cache: { maxAge: 60 } },
        },
      },
    }),
  ],
});

headers apply to pages and files too, prerender sets what renders on demand, and cache keeps the response of a route that renders on demand for maxAge seconds. The server applies route rules, so a static host that serves .output/public without the server doesn't. A rule other than prerender doesn't change a file of the build either: the build writes the page your site renders at a path, even when a redirect rule sends that path elsewhere on the server.

A page of a dynamic source with a staleTime has a Cache-Control header of its own, public, s-maxage=<staleTime in seconds>, so a CDN keeps it as long as the server keeps the files of the source. A staleTime of 0 sends none. A middleware can replace it on the response. See Revalidation.

Environment Variables

process.env is read on the server, when the code runs. A page or route generated at build time has the value of the build in its file, while a route that renders on demand reads the value of the deployment on each request.

The code of your site that runs on the server, like plugins and the props of a custom page, also runs in the build, which generates the pages with it. The build runs that code without the runtime of Nitro, so an import from nitro/*, like useRuntimeConfig() of nitro/runtime-config, fails there: read process.env instead.

In the browser, import.meta.env has the variables starting with VITE_, which Vite writes into the JavaScript at build time. Anyone can read them, so keep secrets in process.env on the server.

Base Path

To serve your site under a path, like https://example.com/docs/, set the base of Vite:

vite.config.ts
export default defineConfig({
  base: "/docs/",
  plugins: [vuesho()],
});

Links and images in your content, the href and src of your head tags, and paths in plugins stay without the base path, and the site adds it. Set site.baseUrl in your config to the origin of the site, like https://example.com, for the canonical links and the sitemap.

Build Errors

A page that fails to render fails the build, so a broken page never reaches a deployment. The error names the URL of the page, like a Markdown page that uses a component the theme doesn't have.

On a server, a page that fails to render answers with a 500 status.