For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /configure/app/output/ssg.md.

output.ssg

  • Type: boolean | object
  • Default Value: undefined

Configuration to enable the application’s SSG (Static Site Generation) feature.

Enabling SSG

This configuration takes effect only when SSG is enabled. Please read the Static Site Generation documentation to understand how to enable SSG and its use cases.

Recommended Reading

The SSG feature is closely related to routing. It is recommended to understand the routing solution before using SSG.

Info
  • Use output.ssg for single-entry apps.
  • For multi-entry apps, prefer output.ssgByEntries.
  • If output.ssg is true and output.ssgByEntries is not set, SSG is enabled for all entries, using the route collection rules below.

Boolean Type

When this configuration is set to true, the SSG feature will be enabled for all entries by default. For manual routing, the root route of the entry will be rendered. For conventional routing, non-dynamic routes and paths returned by page-level ssgParams generators will be rendered. Dynamic routes without a generator are skipped.

export default defineConfig({
  output: {
    ssg: true,
  },
});

Object Type

When the value type is Object, the following attributes can be configured.

Configuration Type

type SSGRouteOptions =
  | string
  | {
      url: string;
      output?: string;
      headers?: Record<string, any>;
    };

type SSGOptions = {
  headers?: Record<string, any>;
  routes?: SSGRouteOptions[];
};

Route Collection

  • With routes omitted or set to [], conventional routing automatically includes non-dynamic routes and paths generated by ssgParams in file-system page.data.ts or $.data.ts files. Generator discovery does not apply to config routes.
  • With a non-empty routes list, render the listed paths and paths from ssgParams. Other non-dynamic routes are skipped. When an explicit route and ssgParams resolve to the same URL, render it once using the explicit route's options, including headers and output.
  • Setting the entry's SSG option to false also disables its parameter generators.

These rules also apply to each entry configured through output.ssgByEntries. See generating parameters alongside a loader for parameter types, encoding, and examples.

Example

In the example configuration below, SSG will render the pages corresponding to the /, /about, and /user/:id routes.

For the /user/:id route, cookies will be added to the request headers.

modern.config.ts
export default defineConfig({
  output: {
    ssg: {
      routes: [
        '/',
        '/about',
        {
          url: '/user/modernjs',
          headers: {
            cookies: 'name=modernjs',
          },
        },
      ],
    },
  },
});