Skip to main content

Static-Site Generation

tramvai can generate pages of your application at build time to static HTML files, this feature is usually called Static Site Generation (SSG)

Explanation​

tramvai static <appName> command run production build of the application, then starts application server, and make requests to all application routes. All responses are saved to .html files inside dist/static directory.

This feature is suitable for applications where all pages are independent of dynamic server-side data. You can serve generated HTML files without tramvai server by CDN or any static server.

Usage​

Development​

  1. Run development build as usual:

    tramvai start <appName>

  2. Open server with exported pages at http://localhost:3000/

Production build​

  1. Run SSG command:

    tramvai static <appName>

  2. Deploy HTML pages to your server and static assets to your CDN

Preview pages​

  1. Run SSG command with --serve flag:

    tramvai static <appName> --serve

  2. Open server with exported pages at http://localhost:3000/

Static Assets​

All static resources (js, css files) will be loaded according to the url specified in ASSETS_PREFIX env variable.

If you build HTML pages with static prefix, for example ASSETS_PREFIX=https://your.cdn.com/, this variable injecting in HTML in build time, and you can't change ASSETS_PREFIX in deploy time.

Select pages to build​

You can specify the comma separated paths list for static HTML generation with --onlyPages flag:

tramvai static <appName> --onlyPages=/about/,/blog/

Custom page request headers​

You can specify HTTP headers for pages requests with --headers flag, for example if you need generate different HTML for devices with mobile User-Agent:

tramvai static <appName> --header "User-Agent: ..."

This can be combined with --folder flag, which allows to generate different HTML files in subfolder and prevent conflicts:

tramvai static <appName> --header "User-Agent: ..." --folder "mobile"

HTML pages will be generated in dist/static/mobile folder.

Limitations​

Dynamic pages (routes like /foo/bar/:id) is not supported, tramvai static command only show warnings for this pages. For now you can use only query parameters for this case.

Server-side Application Lifecycle and Navigation Flow will be executed only once at build time. It means than some data will be non-existed, empty or outdated, for example User-Agent will not be parsed.