feat: add an interactive playground to the documentation site

Author: mnahkies

packages/documentation/next.config.mjs

@@ -1,4 +1,5 @@
 import nextra from "nextra"
+import NodePolyfillPlugin from "node-polyfill-webpack-plugin"
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
@@ -8,6 +9,20 @@ const nextConfig = {
   images: {
     unoptimized: true,
   },
+  webpack: (config, {buildId, dev, isServer, defaultLoaders, webpack}) => {
+    config.experiments = {...config.experiments, syncWebAssembly: true}
+    config.plugins.push(new NodePolyfillPlugin())
+    config.module.rules.push({
+      test: /node:.+/i,
+      use: "null-loader",
+    })
+    config.module.rules.push({
+      test: /@biomejs\/wasm-nodejs/i,
+      use: "null-loader",
+    })
+
+    return config
+  },
   async redirects() {
     return [{source: "/", destination: "/overview/about", permanent: false}]
   },

packages/documentation/package.json

@@ -18,23 +18,34 @@
   },
   "scripts": {
     "clean": "rm -rf ./.next ./dist",
-    "dev": "next dev",
-    "build": "next build",
-    "lint": "next lint",
+    "dev": "yarn copy-sample-data && next dev",
+    "build": "yarn copy-sample-data && next build",
+    "lint": "yarn run -T lint",
+    "format": "yarn run -T format",
+    "copy-sample-data": "tsx ./scripts/copy-sample-data.ts",
     "publish:gh-pages": "yarn gh-pages -d ./dist -b gh-pages --cname openapi-code-generator.nahkies.co.nz --nojekyll"
   },
   "dependencies": {
+    "@hookform/resolvers": "^3.9.1",
+    "@monaco-editor/react": "^4.6.0",
+    "@nahkies/openapi-code-generator": "*",
+    "monaco-editor": "^0.52.2",
+    "monaco-editor-auto-typings": "^0.4.6",
     "next": "15.1.2",
     "nextra": "^3.3.0",
     "nextra-theme-docs": "^3.3.0",
+    "node-polyfill-webpack-plugin": "^4.1.0",
     "react": "19.0.0",
-    "react-dom": "19.0.0"
+    "react-dom": "19.0.0",
+    "react-hook-form": "^7.54.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
     "@types/react": "^19.0.2",
     "@types/react-dom": "^19.0.2",
     "gh-pages": "^6.2.0",
+    "null-loader": "^4.0.1",
+    "tsx": "^4.19.2",
     "typescript": "^5.7.2"
   }
 }

packages/documentation/scripts/copy-sample-data.ts

@@ -0,0 +1,22 @@
+import {copyFile} from "node:fs/promises"
+import {dirname, resolve} from "node:path"
+import {fileURLToPath} from "node:url"
+import {sampleFilenames} from "../src/lib/playground/consts"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+for (const sample of sampleFilenames) {
+  const sourcePath = resolve(
+    __dirname,
+    `../../../integration-tests-definitions/${sample}`,
+  )
+  const destinationPath = resolve(__dirname, `../public/samples/${sample}`)
+
+  try {
+    await copyFile(sourcePath, destinationPath)
+    console.log(`Copied ${sample} to ${destinationPath}`)
+  } catch (error) {
+    console.error(`Failed to copy ${sample}:`, error)
+  }
+}

packages/documentation/src/lib/loading-spinner.module.css

@@ -0,0 +1,19 @@
+.loader {
+  width: 1rem;
+  height: 1rem;
+  border: 5px solid #363636;
+  border-bottom-color: transparent;
+  border-radius: 50%;
+  display: inline-block;
+  box-sizing: border-box;
+  animation: rotation 1s linear infinite;
+}
+
+@keyframes rotation {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}

packages/documentation/src/lib/loading-spinner.tsx

@@ -0,0 +1,5 @@
+import styles from "./loading-spinner.module.css"
+
+export const LoadingSpinner = () => {
+  return <span className={styles.loader} />
+}

packages/documentation/src/lib/playground.module.css

@@ -0,0 +1,13 @@
+.editorContainer {
+  display: grid;
+  grid-template-columns: 1fr;
+  grid-template-rows: auto;
+
+  /*
+  TODO: rendering side-by-side results in weird stuff happening
+        when breakpoints change, stick with the vertical stack for now.
+  @media (min-width: 1536px) {
+    grid-template-columns: 1fr 1fr;
+  }
+   */
+}