chore: migrate docs to es modules (#4143)

* chore: migrate docs site to esm

* chore: lintfix

* chore: update site package.json to reference mjs files

* chore: change back docs site type to commonjs as it breaks the x0 dependency

Co-authored-by: Erez Rokah <erezrokah@users.noreply.github.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

package.json

@@ -65,7 +65,7 @@
     "test:ci:ava:integration": "c8 -r json ava --concurrency 1 --no-worker-threads tests/integration/**/*.test.js",
     "test:affected": "node ./tools/affected-test.js",
     "e2e": "node ./tools/e2e/run.mjs",
-    "docs": "node ./site/scripts/docs.js",
+    "docs": "node ./site/scripts/docs.mjs",
     "watch": "c8 --reporter=lcov ava --watch",
     "site:build": "run-s site:build:*",
     "site:build:install": "cd site && npm ci --no-audit",

site/config.mjs

@@ -0,0 +1,9 @@
+import { join } from 'path'
+import { fileURLToPath } from 'url'
+
+export const rootDir = fileURLToPath(new URL('..', import.meta.url))
+
+export const docs = {
+  srcPath: join(rootDir, 'docs'),
+  outputPath: join(rootDir, 'site/src'),
+}

site/fs.mjs

@@ -0,0 +1,44 @@
+import { promises as fs } from 'fs'
+import { join, dirname } from 'path'
+import { promisify } from 'util'
+
+import rimraf from 'rimraf'
+
+const rimrafAsync = promisify(rimraf)
+
+export const copyDirRecursiveAsync = async (src, dest) => {
+  try {
+    fs.mkdir(dest, { recursive: true })
+  } catch {
+    // ignore erros for mkdir
+  }
+
+  const childrenItems = await fs.readdir(src)
+
+  await Promise.all(
+    childrenItems.map(async (item) => {
+      const srcPath = join(src, item)
+      const destPath = join(dest, item)
+
+      const itemStat = await fs.lstat(srcPath)
+
+      if (itemStat.isFile()) {
+        fs.copyFile(srcPath, destPath)
+      } else {
+        await copyDirRecursiveAsync(srcPath, destPath)
+      }
+    }),
+  )
+}
+
+export const ensureFilePathAsync = async (filePath) => {
+  try {
+    await fs.mkdir(dirname(filePath), { recursive: true })
+  } catch {
+    // ignore any errors with mkdir - it will throw if the path already exists.
+  }
+}
+
+export const removeRecursiveAsync = async (filePath) => {
+  await rimrafAsync(filePath)
+}

site/package.json

@@ -3,6 +3,7 @@
   "version": "1.0.0",
   "description": "Docs site for Netlify CLI",
   "private": true,
+  "type": "commonjs",
   "author": "Netlify Inc.",
   "contributors": [
     "David Wells <david.wells@netlify.com> (https://davidwells.io/)",
@@ -16,12 +17,12 @@
     "start": "npm run sync && run-p start:*",
     "build": "npm run clean && run-s build:*",
     "postbuild": "cp src/_redirects dist/_redirects",
-    "build:docs": "node scripts/docs.js",
+    "build:docs": "node scripts/docs.mjs",
     "build:site": "npm run sync && x0 build src",
     "start:site": "x0 src",
-    "start:watch": "node ./watch.js",
-    "watch": "node ./watch.js",
-    "sync": "node ./sync.js",
+    "start:watch": "node ./watch.mjs",
+    "watch": "node ./watch.mjs",
+    "sync": "node ./sync.mjs",
     "clean": "rimraf dist"
   },
   "engines": {

site/scripts/docs.js → site/scripts/docs.mjs

@@ -1,13 +1,17 @@
 // @ts-check
-const path = require('path')
-const process = require('process')
+import { basename, join } from 'path'
+import { env } from 'process'
+import { fileURLToPath } from 'url'
 
-const markdownMagic = require('markdown-magic')
-const stripAnsi = require('strip-ansi')
+import markdownMagic from 'markdown-magic'
+import stripAnsi from 'strip-ansi'
 
-const { generateCommandData } = require('./generate-command-data')
+import { generateCommandData } from './generate-command-data.mjs'
 
-process.env.DOCS_GEN = 'TRUE'
+const rootDir = fileURLToPath(new URL('../..', import.meta.url))
+const markdownFiles = [join(rootDir, 'README.md'), join(rootDir, 'docs/**/**.md')]
+
+env.DOCS_GEN = 'TRUE'
 
 const commandData = generateCommandData()
 
@@ -16,7 +20,7 @@ const newLine = '\n\n'
 const config = {
   transforms: {
     GENERATE_COMMANDS_DOCS(content, options, instance) {
-      const command = path.basename(instance.originalPath, '.md')
+      const command = basename(instance.originalPath, '.md')
       // console.log('command', command)
       const info = commandData[command]
       // console.log('info', info)
@@ -60,9 +64,6 @@ const config = {
   },
 }
 
-const rootDir = path.join(__dirname, '..', '..')
-const markdownFiles = [path.join(rootDir, 'README.md'), path.join(rootDir, 'docs/**/**.md')]
-
 /* Start - Docs Templating logic */
 const commandExamples = function (examples) {
   if (!examples || examples.length === 0) {

site/scripts/generate-command-data.js → site/scripts/generate-command-data.mjs

@@ -1,8 +1,8 @@
 // @ts-check
-const { createMainCommand } = require('../../src/commands')
-const { sortOptions } = require('../../src/utils')
+import main from '../../src/commands/index.js'
+import utils from '../../src/utils/index.js'
 
-const program = createMainCommand()
+const program = main.createMainCommand()
 
 /** @type {Array<import('../../src/commands/base-command').BaseCommand>} */
 // @ts-ignore typecast needed
@@ -21,7 +21,7 @@ const parseCommand = function (command) {
 
   const flags = command.options
     .filter((option) => !option.hidden)
-    .sort(sortOptions)
+    .sort(utils.sortOptions)
     .reduce((prev, cur) => {
       const name = cur.long.replace('--', '')
       const contentType = cur.argChoices ? cur.argChoices.join(' | ') : 'string'
@@ -49,7 +49,7 @@ const parseCommand = function (command) {
   }
 }
 
-const generateCommandData = function () {
+export const generateCommandData = function () {
   return (
     commands
       // filter out sub commands
@@ -58,5 +58,3 @@ const generateCommandData = function () {
       .reduce((prev, command) => ({ ...prev, [command.name()]: parseCommand(command) }), {})
   )
 }
-
-module.exports = { generateCommandData }

site/sync.js → site/sync.mjs

@@ -1,12 +1,12 @@
-const fs = require('fs').promises
-const path = require('path')
+import { promises as fs } from 'fs'
+import { join, basename, dirname } from 'path'
 
-const config = require('./config')
-const { copyDirRecursiveAsync } = require('./fs')
+import { docs } from './config.mjs'
+import { copyDirRecursiveAsync } from './fs.mjs'
 
 const readDir = async function (dir, allFiles = []) {
   const filenames = await fs.readdir(dir)
-  const files = filenames.map((file) => path.join(dir, file))
+  const files = filenames.map((file) => join(dir, file))
   allFiles.push(...files)
   await Promise.all(
     files.map(async (file) => {
@@ -18,8 +18,8 @@ const readDir = async function (dir, allFiles = []) {
 }
 
 const syncLocalContent = async function () {
-  const src = path.join(config.docs.srcPath)
-  const destination = path.join(config.docs.outputPath)
+  const src = join(docs.srcPath)
+  const destination = join(docs.outputPath)
 
   await copyDirRecursiveAsync(src, destination)
   console.log(`Docs synced to ${destination}`)
@@ -35,8 +35,8 @@ const removeMarkDownLinks = async function (filePath) {
   const content = await fs.readFile(filePath, 'utf-8')
   const newContent = content.replace(/(\w+)\.md/gm, '$1').replace(/\/docs\/commands\//gm, '/commands/')
   // Rename README.md to index.md
-  if (path.basename(filePath) === 'README.md') {
-    const newPath = path.join(path.dirname(filePath), 'index.md')
+  if (basename(filePath) === 'README.md') {
+    const newPath = join(dirname(filePath), 'index.md')
     // Delete README.md from docs site
     await fs.unlink(filePath)
     // Write index.md

site/watch.js → site/watch.mjs

@@ -1,17 +1,17 @@
 /* Syncs blog content from repo to /site/blog */
-const fs = require('fs').promises
-const path = require('path')
+import { promises as fs } from 'fs'
+import { join } from 'path'
 
-const sane = require('sane')
+import sane from 'sane'
 
-const config = require('./config')
-const { ensureFilePathAsync, removeRecursiveAsync } = require('./fs')
+import { docs } from './config.mjs'
+import { ensureFilePathAsync, removeRecursiveAsync } from './fs.mjs'
 
-const watcher = sane(config.docs.srcPath, { glob: ['**/*.md'] })
+const watcher = sane(docs.srcPath, { glob: ['**/*.md'] })
 
 /* Watch Files */
 watcher.on('ready', function onReady() {
-  console.log(`Watching ${config.docs.srcPath} files for changes`)
+  console.log(`Watching ${docs.srcPath} files for changes`)
 })
 
 watcher.on('change', async function onChange(filepath) {
@@ -33,8 +33,8 @@ watcher.on('delete', async function onDelete(filepath) {
 /* utils */
 const getFullPath = function (filePath) {
   return {
-    src: path.join(config.docs.srcPath, filePath),
-    destination: path.join(config.docs.outputPath, filePath),
+    src: join(docs.srcPath, filePath),
+    destination: join(docs.outputPath, filePath),
   }
 }