Static Site Generation#

SSG (Static Site Generation) is a technical solution that generates complete static web pages at build time based on data and templates. This means that in a production environment, pages are pre-rendered with content and can be cached by a CDN. SSG can offer better performance and higher security for pages that do not require dynamic data.

Enabling SSG#

First, we need to enable the SSG feature by running pnpm run new:

? Please select the operation you want: Enable features
? Please select the feature name: Enable SSG

After running the command, register the SSG plugin in modern.config.ts:

import { ssgPlugin } from '@modern-js/plugin-ssg';

export default defineConfig({
  output: {
    ssg: true,
  },
  plugins: [..., ssgPlugin()],
});

Development Debugging#

Since SSG also renders pages in a Node.js environment, we can enable SSR during the development phase to expose code issues early and validate the SSG rendering effect:

export default defineConfig({
  server: {
    ssr: process.env.NODE_ENV === 'development',
  }
}

Using SSG in Conventional Routing#

In conventional routing, Modern.js generates routes based on the file structure under the entry point, allowing the framework to collect complete route information.

Basic Usage#

For example, the following is a project directory structure using conventional routing:

.
└── routes
    ├── layout.tsx
    ├── page.tsx
    └── user
        ├── layout.tsx
        ├── page.tsx
        └── profile
            └── page.tsx

The above file directory will generate the following three routes:

• /
• /user
• /user/profile

Add component code in src/routes/page.tsx:

export default () => {
  return <div>Index Page</div>;
};

Run the command pnpm run dev at the project root and check the dist/ directory, where only one HTML file main/index.html is generated.

Run the command pnpm run build at the project root, and after the build completes, check the dist/ directory again. This time, you'll find main/index.html, main/user/index.html, and main/user/profile/index.html files, each corresponding to the routes listed above.

Each route in conventional routing will generate a separate HTML file. Checking main/index.html, you will find it contains the text Index Page, which demonstrates the effect of SSG.

After running pnpm run serve to start the project, inspect the returned document in the Network tab of the browser's development tools. The document includes the fully rendered content from the component.

Preventing Default Behavior#

By default, all routes in conventional routing have SSG enabled. Modern.js provides another field to prevent the default SSG behavior.

For example, in the following directory structure, routes /, /user, and /user/profile all have SSG enabled:

.
├── src
│   └── routes
│       ├── layout.tsx
│       ├── page.tsx
│       └── user
│           ├── layout.tsx
│           ├── page.tsx
│           └── profile
│               └── page.tsx

You can disable the default behavior of certain routes by configuring preventDefault. After configuring as shown below, only the SSG pages for / and /user/profile will be generated:

export default defineConfig({
  output: {
    ssg: {
      preventDefault: ['/user'],
    },
  },
});

Using SSG in Manual Routing#

Manual routing defines routes through component code, requiring the application to run to obtain accurate route information. Therefore, you cannot use the SSG feature out of the box. Developers need to configure which routes require SSG.

For example, consider the following code with multiple routes. By setting output.ssg to true, it will only render the entry route (/) by default.

import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
import { StaticRouter } from '@modern-js/runtime/router/server';
import React from 'react';
import { useRuntimeContext } from '@modern-js/runtime';

const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;

export default () => {
  const { context } = useRuntimeContext();
  const pathname = context?.request?.pathname;
  return (
    <Router location={pathname}>
      <Routes>
        <Route index element={<div>index</div>} />
        <Route path="about" element={<div>about</div>} />
      </Routes>
    </Router>
  );
};

If you want to enable SSG for /about as well, you can configure output.ssg:

export default defineConfig({
  output: {
    ssg: {
      routes: ['/', '/about'],
    },
  },
});

After running pnpm run build, you will see a new main/about/index.html file in the dist/ directory.

After running pnpm run serve to start the project, inspect the returned document in the Network tab of the browser's development tools. The document includes the fully rendered content from the component.

Adding Route Parameters#

In Modern.js, some routes can be dynamic, such as /user/:id in manual routing or /user/[id]/page.tsx in conventional routing.

can configure specific parameters in output.ssg to render routes with specified parameters. For example:

export default defineConfig({
  output: {
    ssg: {
      routes: [
        {
          url: '/user/:id',
          params: [{
            id: 'modernjs',
          }],
        },
      ],
    },
  },
});

Here, the /user/modernjs route will be rendered, and the id parameter will be passed to the component during rendering. When multiple values are configured, multiple pages will be generated.

Configuring Request Headers for Rendering#

Modern.js supports configuring request headers for specific entries or routes. For example:

export default defineConfig({
  output: {
    ssg: {
      headers: {
        "x-tt-env": "ppe_modernjs"
      },
      routes: [
        '/',
        {
          url: '/about',
          headers: {
            "from": "modern-website"
          },
        },
      ],
    },
  },
});

In the above configuration, the x-tt-env request header is set for all routes, and the from request header is specifically set for the /about route.