fix: warn users that still use CJS

Author: brillout

docs/headingsDetached.tsx

@@ -309,4 +309,8 @@ const headingsDetached = [
     title: "Vite's Lazy Transpiling",
     url: '/lazy-transpiling'
   },
+  {
+    title: 'CJS',
+    url: '/CJS'
+  }
 ] satisfies HeadingDetachedDefinition[]

docs/pages/CJS.page.server.mdx

@@ -0,0 +1,41 @@
+While you can use vite-plugin-ssr with
+[CJS code](https://nodejs.org/api/modules.html#modules-commonjs-modules:~:text=CommonJS%20modules%20are%20the%20original%20way%20to%20package%20JavaScript%20code%20for%20Node.js.%20Node.js%20also%20supports%20the%20ECMAScript%20modules%20standard%20used%20by%20browsers%20and%20other%20JavaScript%20runtimes.),
+we recommend writing
+[ESM code](https://nodejs.org/api/esm.html#modules-ecmascript-modules:~:text=ECMAScript%20modules%20are%20the%20official%20standard%20format%20to%20package%20JavaScript%20code%20for%20reuse.%20Modules%20are%20defined%20using%20a%20variety%20of%20import%20and%20export%20statements.)
+instead.
+
+> The code you write that is processed by Vite is already ESM. But [some of your server code may not be processed by Vite](https://github.com/brillout/vite-plugin-ssr/issues/562) and may be CJS.
+
+If you get the following warning:
+
+```
+[vite-plugin-ssr][Warning] We recommend setting package.json#type to "module" (and therefore
+writing ESM code instead of CJS code)
+```
+
+Then, in order to remove the warning, add this to your `package.json`:
+
+```json5
+// package.json
+{
+   // ...
+   type: "module"
+}
+```
+
+This [makes Node.js treat all .js files as ESM](https://nodejs.org/docs/latest-v13.x/api/esm.html#esm_package_json_type_field:~:text=Files%20ending%20with%20.js%20will%20be%20loaded%20as%20ES%20modules%20when%20the%20nearest%20parent%20package.json%20file%20contains%20a%20top%2Dlevel%20field%20%22type%22%20with%20a%20value%20of%20%22module%22.).
+
+This means that, if you have .js files written in CJS, then you'll have to migrate them to ESM. For example:
+
+```js
+-// CJS code
+-const express = require('express')
+-const { renderPage } = require('vite-plugin-ssr/server')
++// ESM code
++import express from 'express'
++import { renderPage } from 'vite-plugin-ssr/server'
+```
+
+> An escape hatch is to use [the `.cjs` and `.mjs` file extensions](https://nodejs.org/api/esm.html#enabling:~:text=Authors%20can%20tell%20Node.js%20to%20use%20the%20ECMAScript%20modules%20loader%20via%20the%20.mjs%20file%20extension), enabling you to determine/change the module system on a file-by-file basis regardless of whether `package.json#type` is set to `"module"` or `"commonjs"`.
+
+> You still want to use CJS? Let us know why and we'll create a new `config.disableCJSWarning`.

examples/react/.testRun.ts

@@ -9,19 +9,26 @@ import {
   autoRetry,
   fetchHtml,
   getServerUrl,
-  testScreenshotFixture
+  testScreenshotFixture,
+  expectLog
 } from '@brillout/test-e2e'
 import path from 'path'
 import url from 'url'
 import { createRequire } from 'module'
 
-function testRun(cmd: 'npm run dev' | 'npm run preview' | 'npm run prod') {
+function testRun(cmd: 'npm run dev' | 'npm run preview' | 'npm run prod', isCJS?: true) {
   run(cmd)
 
   test('page content is rendered to HTML', async () => {
     const html = await fetchHtml('/')
     expect(html).toContain('<h1>Welcome</h1>')
     expectHtmlCommon(html)
+    if (isCJS) {
+      expectLog(
+        'package.json#type to "module" (and therefore writing ESM code instead of CJS code), see https://vite-plugin-ssr.com/CJS',
+        (log) => log.logSource === 'stderr'
+      )
+    }
   })
 
   test('page is rendered to the DOM and interactive', async () => {

package.json

@@ -41,7 +41,7 @@
   "devDependencies": {
     "@brillout/bump-dependencies": "^0.1.1",
     "@brillout/dev-my-dep": "^0.1.5",
-    "@brillout/test-e2e": "^0.5.12",
+    "@brillout/test-e2e": "^0.5.13",
     "@brillout/test-types": "^0.1.6",
     "vitest": "^0.34.1"
   },

pnpm-lock.yaml

@@ -1,2 +1,2 @@
-import { testRun } from '../../examples/react/.testRun'
+import { testRun } from './testRun'
 testRun('npm run dev')

test/cjs/test-dev.test.ts

@@ -1,2 +1,2 @@
-import { testRun } from '../../examples/react/.testRun'
+import { testRun } from './testRun'
 testRun('npm run prod')

test/cjs/test-prod.test.ts

@@ -0,0 +1,8 @@
+export { testRun }
+
+import { testRun as testRun_ } from '../../examples/react/.testRun'
+
+type Cmd = Parameters<typeof testRun_>[0]
+function testRun(cmd: Cmd) {
+  testRun_(cmd, true)
+}

test/cjs/testRun.ts

@@ -1,9 +1,15 @@
 export { commonConfig }
 
 import type { Plugin, ResolvedConfig } from 'vite'
-import { assert, assertWarning, isValidPathAlias } from '../utils.js'
+import { assert, assertWarning, findUserPackageJsonPath, isValidPathAlias } from '../utils.js'
 import { assertRollupInput } from './buildConfig.js'
 import { installRequireShim_setUserRootDir } from '@brillout/require-shim'
+import pc from '@brillout/picocolors'
+import path from 'path'
+import { createRequire } from 'module'
+// @ts-ignore Shimed by dist-cjs-fixup.js for CJS build.
+const importMetaUrl: string = import.meta.url
+const require_ = createRequire(importMetaUrl)
 
 function commonConfig(): Plugin[] {
   return [
@@ -31,6 +37,7 @@ function commonConfig(): Plugin[] {
           workaroundCI(config)
           assertRollupInput(config)
           assertResolveAlias(config)
+          assertEsm(config.root)
         }
       }
     }
@@ -98,3 +105,21 @@ function getAliases(config: ResolvedConfig) {
     return alias
   }
 }
+
+function assertEsm(userViteRoot: string) {
+  const packageJsonPath = findUserPackageJsonPath(userViteRoot)
+  if (!packageJsonPath) return
+  const packageJson = require_(packageJsonPath)
+  let dir = path.dirname(packageJsonPath)
+  if (dir !== '/') {
+    assert(!dir.endsWith('/'))
+    dir = dir + '/'
+  }
+  assert(dir.endsWith('/'))
+  dir = pc.dim(dir)
+  assertWarning(
+    packageJson.type === 'module',
+    `We recommend setting ${dir}package.json#type to "module" (and therefore writing ESM code instead of CJS code), see https://vite-plugin-ssr.com/CJS`,
+    { onlyOnce: true }
+  )
+}

vite-plugin-ssr/node/plugin/plugins/commonConfig.ts

@@ -4,9 +4,16 @@ export { getStemPackages }
 export type { StemPackage }
 
 import path from 'path'
-import { assert, assertUsage, assertWarning, toPosixPath, assertPosixPath, getDependencyRootDir } from '../../utils.js'
+import {
+  assert,
+  assertUsage,
+  assertWarning,
+  toPosixPath,
+  assertPosixPath,
+  getDependencyRootDir,
+  findUserPackageJsonPath
+} from '../../utils.js'
 import { import_ } from '@brillout/import'
-import fs from 'fs'
 import { createRequire } from 'module'
 // @ts-ignore Shimed by dist-cjs-fixup.js for CJS build.
 const importMetaUrl: string = import.meta.url
@@ -68,20 +75,6 @@ function findUserRootDir(userAppRootDir: string): string {
   assertUsage(userPkgJsonPath, `Couldn't find package.json in any parent directory starting from ${userAppRootDir}`)
   return toPosixPath(path.dirname(userPkgJsonPath))
 }
-function findUserPackageJsonPath(userAppRootDir: string): null | string {
-  let dir = userAppRootDir
-  while (true) {
-    const configFilePath = path.join(dir, './package.json')
-    if (fs.existsSync(configFilePath)) {
-      return configFilePath
-    }
-    const dirPrevious = dir
-    dir = path.dirname(dir)
-    if (dir === dirPrevious) {
-      return null
-    }
-  }
-}
 
 function getStemPkgNames(userPkgJson: UserPkgJson): string[] {
   const stemPkgNames = Object.keys(userPkgJson.dependencies ?? {}).filter((depName) => {

vite-plugin-ssr/node/plugin/plugins/config/stemUtils.ts

@@ -23,3 +23,4 @@ export * from '../../utils/escapeRegex.js'
 export * from '../../utils/stripAnsi.js'
 export * from '../../utils/trimWithAnsi.js'
 export * from '../../utils/removeEmptyLines.js'
+export * from '../../utils/findUserPackageJsonPath.js'

vite-plugin-ssr/node/plugin/utils.ts

@@ -0,0 +1,20 @@
+export { findUserPackageJsonPath }
+
+import path from 'path'
+import fs from 'fs'
+
+function findUserPackageJsonPath(userDir: string): null | string {
+  let dir = userDir
+  while (true) {
+    const configFilePath = path.join(dir, './package.json')
+    if (fs.existsSync(configFilePath)) {
+      // return toPosixPath(configFilePath)
+      return configFilePath
+    }
+    const dirPrevious = dir
+    dir = path.dirname(dir)
+    if (dir === dirPrevious) {
+      return null
+    }
+  }
+}