feat(ssg): introduce disableSSG and onlySSG

[yusukebe]

This PR introduces disbleSSG and onlySSG middleware.

Usage

Your application:

const app = new Hono()
app.get('/', (c) => c.html(<h1>Hello</h1>))
app.get('/api', disableSSG(), (c) => c.text('an-api'))
app.get('/static-page', onlySSG(), (c) => c.html(<h1>Welcome to my site</h1>))

Difference from #2033

This Middleware is similar to isSSG and isSSR proposed in #2033 but different.

1. Focus on SSG - SSG Helper is for SSG only and does not take care of Server-Side-Rendering. Therefore, we can only specify whether to enable SSG or not.
2. Using headers - Add custom headers instead of adding properties to the Request/Response object. We need to extend the objects. And, without using this middleware, it can check the Request header, and user can write their own process if it has x-hono-ssg.

Author should do the followings, if applicable

• Add tests
• Run tests
• yarn denoify to generate files for Deno

[watany-dev]

@yusukebe
Regarding disableSSG, it's clear that the c.header method can be used to maintain state, which is quite efficient!

However, I have some questions about onlySSG. In this case, it seems that every request must go through toSSG, meaning that all file writings have to be executed before any routing within the app occurs. This approach appears to potentially impact performance.

Analysis

I haven't fully delved into the code, but it seems that routes registered with new Hono() prioritize previously registered routes. Therefore, by serving static files from the folder generated by toSSG before app registration, static file routing might be given priority.

Work

Here are some experiments to support this theory:

1. In this case, the serveStatic static route is prioritized, and the HTML file is displayed.

app.use('*', serveStatic({ root: './static' }))
app.get('/ssg', (c) => c.html(<SSGPage />));

or

app.use('*', serveStatic({ root: './static' }))
app.get('/ssg', (c) => c.notFound());

2. In this case, app.get('/ssg') is prioritized, and the HTML file assembled within the routing is displayed.

app.get('/ssg', (c) => c.html(<SSGPage />));
app.use('*', serveStatic({ root: './static' }))

3. In this case, app.get('/ssg') is prioritized, and a notFound response is returned.

app.get('/ssg', (c) => c.notFound());
app.use('*', serveStatic({ root: './static' }))

Appendix

If the purpose of onlySSG is to be used only during static builds and to be inactive in regular routing, it might be sufficient to simply override with c.notFound without adding header logic.

[yusukebe]

Hi @watany-dev, thanks fo the comment.

First, let's get a clear understanding of how toSSG should be used.

This is my scenario for a hybrid SSG/SSR app.

1. Write my application

For example, name it src/index.ts:

// src/index.ts

import { Hono } from 'hono'
import { disableSSG, onlySSG } from 'hono/ssg'

const app = new Hono()

app.get('/', (c) => c.html(<h1>Hello</h1>))
app.get('/api', disableSSG(), (c) => c.text('an-api'))
app.get('/static-page', onlySSG(), (c) => c.html(<h1>Welcome to my site</h1>))

export default app

2. Development

Developing with a local server. If we also want to see /static-page, we might have to do the following, although it is verbose. This could be improved, but for now I think it is fine the way it is.

import { env } from 'hono/adapter'

// ...

app.get(
  '/static-page',
  async (c, next) => {
    if (env<{ mode: string }>(c).mode === 'production') {
      await onlySSG()(c, next)
    } else {
      await next()
    }
  },
  (c) => c.html(<h1>Welcome to my site</h1>)
)

3. Deploy - SSG

Use toSSG to export HTML statically and deploy it to such as Cloudflare Pages.

Create a build script to run on Node.js. Name it build.ts.

// build.ts

import fs from 'node:fs/promises'
import { toSSG } from 'hono/ssg'
import app from './src/index'

toSSG(app, fs, { dir: 'dist' })

Build pages with the build.ts.

tsx ./build.ts

Deploy them using Wrangler.

wrangler pages deploy dist/

4. Deploy - SSR

For example, we can deploy the application as an SSR to Cloudflare Workers.

wrangler deploy src/index.ts

---

Maybe your scenario is something completely different. We need to share.

[nakasyou]

If we don't make default option, we can probably write this code:

app.use('*', disableSSG())
app.get('/', c => c.json('Hello world!'))
app.get('/', onlySSG(),  c => c.json('Hello world!'))

I think it's cool.
Do you think this code is good?

[watany-dev]

@yusukebe

Thanks, I understand the use case. That use case makes sense to me. I think it is good.

[yusukebe]

@nakasyou

If we don't make default option, we can probably write this code:

Yeah, exactly. We can write the code.

@watany-dev

Thank you for understanding. If we are going with this use case, I think this issue you mentioned is no longer a problem. How about it?

However, I have some questions about onlySSG. In this case, it seems that every request must go through toSSG, meaning that all file writings have to be executed before any routing within the app occurs. This approach appears to potentially impact performance.

@nakasyou @watany-dev

If you are OK, I'll merge this PR and close #2033 ( but thanks for @nakasyou ).

[watany-dev]

@yusukebe
Yes, there is nothing to block because the use case is different. I think we can merge them!

[nakasyou]

@yusukebe

If you are OK, I'll merge this PR and close #2033 ( but thanks for @nakasyou ).

Yes, I don't have dissatisfaction for this PR.

[yusukebe]

Thanks both! Merge now!