Adds support for Zuplo dev-portal.json configuration (#433)

* Add support for zuplo dev-portal.json

* Added support for dev-portal.json config

* updated type import

* Fixed server output path

* generate code for @zudoku/config

.eslintrc.cjs

@@ -2,7 +2,7 @@
 module.exports = {
   root: true,
   parser: "@typescript-eslint/parser",
-  ignorePatterns: ["dist", ".eslintrc.cjs"],
+  ignorePatterns: ["dist", ".eslintrc.cjs", "packages/config/src/index.d.ts"],
   parserOptions: {
     project: "./tsconfig.eslint.json",
     ecmaFeatures: {

.vscode/launch.json

@@ -0,0 +1,34 @@
+{
+  "version": "0.2.0",
+  "inputs": [
+    {
+      "type": "promptString",
+      "description": "The example to use",
+      "id": "example",
+      "default": "with-config"
+    }
+  ],
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "zudoku:build",
+      "env": {
+        "NODE_ENV": "development"
+      },
+      "smartStep": true,
+      "runtimeExecutable": "nx",
+      "args": ["run", "${input:example}:build", "--debugPort=9229"],
+      "skipFiles": ["<node_internals>/**"],
+      "console": "integratedTerminal",
+      "sourceMaps": true,
+      "resolveSourceMapLocations": [
+        "${workspaceFolder}/apps/**/dist/**",
+        "${workspaceFolder}/packages/**/dist/**",
+        "${workspaceFolder}/sdks/**/dist/**",
+        "${workspaceFolder}/test-fixtures/**/dist/**",
+        "!**/node_modules/**"
+      ]
+    }
+  ]
+}

examples/with-zuplo/.gitignore

@@ -0,0 +1,10 @@
+.zuplo/
+.cache/
+dist/
+node_modules/
+.env
+.env.zuplo
+.husky/_
+
+# OS Stuff
+.DS_Store

examples/with-zuplo/config/policies.json

@@ -0,0 +1,3 @@
+{
+  "policies": []
+}

examples/with-zuplo/config/routes.oas.json

@@ -0,0 +1,8 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "version": "1.0.0",
+    "title": "My Zuplo API"
+  },
+  "paths": {}
+}

examples/with-zuplo/dev-portal.json

@@ -0,0 +1,25 @@
+{
+  "basePath": "/docs",
+  "topNavigation": [
+    { "id": "docs", "label": "Documentation" },
+    { "id": "api", "label": "API Reference" }
+  ],
+  "sidebar": {
+    "docs": [
+      {
+        "type": "category",
+        "label": "Overview",
+        "items": ["/introduction"]
+      }
+    ]
+  },
+  "redirects": [{ "from": "/", "to": "/introduction" }],
+  "apis": {
+    "type": "file",
+    "input": "config/routes.oas.json",
+    "navigationId": "api"
+  },
+  "docs": {
+    "files": "/pages/**/*.mdx"
+  }
+}

examples/with-zuplo/env.example

@@ -0,0 +1,2 @@
+EXAMPLE_SECRET=👀 What you looking at?
+EXAMPLE_CONFIG=https://twitter.com/zuplo

examples/with-zuplo/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "with-zuplo",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "zudoku dev",
+    "build": "zudoku build"
+  },
+  "nx": {
+    "tags": [
+      "example"
+    ],
+    "targets": {
+      "build": {
+        "dependsOn": [
+          "zudoku:build"
+        ]
+      }
+    }
+  },
+  "dependencies": {
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "@mdx-js/react": "3.0.1",
+    "zudoku": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}

examples/with-zuplo/pages/introduction.mdx

@@ -0,0 +1,29 @@
+---
+title: Welcome
+description: Welcome to your new Zudoku documentation site.
+---
+
+## Welcome to Zudoku
+
+Zudoku is a documentation generator that allows you to create beautiful documentation sites with ease. It supports MDX, OpenAPI, and is entirely customizable.
+
+### Start customizing
+
+You can customize your documentation site by modifying the `zudoku.config.js` file in the root of your project. Why not try changing the primary color of your site?
+
+```json
+{
+  // ...
+  "theme": {
+    "light": {
+      "primary": "316 100% 50%",
+      "primaryForeground": "360 100% 100%"
+    },
+    "dark": {
+      "primary": "316 100% 50%",
+      "primaryForeground": "360 100% 100%"
+    }
+  }
+  // ...
+}
+```

examples/with-zuplo/project.json

@@ -0,0 +1,13 @@
+{
+  "name": "with-zuplo",
+  "$schema": "../node_modules/nx/schemas/nx-schema.json",
+  "targets": {
+    "build": {
+      "options": {
+        "env": {
+          "ZUPLO": "1"
+        }
+      }
+    }
+  }
+}

examples/with-zuplo/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ESNext", "DOM", "DOM.Iterable", "WebWorker"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "useDefineForClassFields": true,
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "useUnknownInCatchVariables": false,
+    "jsx": "react-jsx"
+  },
+  "include": ["src", "zudoku.config.ts"]
+}

package.json

@@ -10,11 +10,13 @@
     "lint:ci": "eslint .",
     "format": "prettier --write .",
     "format:ci": "prettier --check .",
-    "clean": "git clean -Xfde !.env",
     "prepare": "husky",
     "release:pre": "gh workflow run release.yaml -f releaseType=prerelease",
     "release:minor": "gh workflow run release.yaml -f releaseType=minor",
-    "local": "cp .env.example .env"
+    "local": "cp .env.example .env",
+    "build:clean": "tsc --build --clean",
+    "reset": "nx reset && npm run build:clean",
+    "clean": "git clean -Xfde !.env"
   },
   "lint-staged": {
     "**/*.{ts,tsx,json,md,yml,js,jsx,css,html}": [

packages/config/README.md

@@ -0,0 +1,5 @@
+# @zudoku/config
+
+This module is for internal use only. It is used to load the configuration of Zudoku projects when running as part of the Zuplo build.
+
+This module may change at any time. Do not rely on it in your own projects.

packages/config/package.json

@@ -17,19 +17,24 @@
     ".": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
-    "build": "tsc"
+    "build": "node ./scripts/build.mjs"
   },
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {
-    "tsx": "4.19.1"
-  },
   "devDependencies": {
     "@types/node": "20.16.11",
-    "typescript": "5.7.2"
+    "esbuild": "^0.24.0",
+    "typescript": "5.7.2",
+    "zod-to-ts": "^1.2.0"
+  },
+  "dependencies": {
+    "tsx": "^4.19.2",
+    "zod": "3.23.8",
+    "zod-validation-error": "3.4.0"
   }
 }

packages/config/project.json

@@ -4,15 +4,20 @@
   "targets": {
     "build": {
       "inputs": [
-        "{projectRoot}/**/*.ts",
+        "{workspaceRoot}/zudoku/src/**/*.ts",
+        "{projectRoot}/src/**/*.ts",
         "{projectRoot}/tsconfig.json",
-        "{projectRoot}/package.json"
+        "{projectRoot}/package.json",
+        "{projectRoot}/scripts/build.mjs"
       ],
       "outputs": ["{projectRoot}/dist"],
       "cache": true
     },
-    "build:ci": {
+    "build:types": {
       "dependsOn": ["build"]
+    },
+    "build:ci": {
+      "dependsOn": ["build:types"]
     }
   }
 }

packages/config/scripts/build.mjs

@@ -0,0 +1,46 @@
+import esbuild from "esbuild";
+import { copyFile, writeFile } from "node:fs/promises";
+import { createTypeAlias, printNode, zodToTs } from "zod-to-ts";
+import { CommonConfigSchema } from "../../zudoku/dist/config/validators/common.js";
+
+/**
+ * This file does three things:
+ * 1. Build the index.ts file using esbuild - this references the functions
+ *    from zudoku we need to bundle in this module
+ * 2. Generates the CommonConfig type alias from the zod type in zoduku
+ * 3. Copies the manually written index.d.ts file to the dist folder
+ */
+
+const result = await esbuild.build({
+  entryPoints: [new URL("../src/index.ts", import.meta.url).pathname],
+  outdir: "dist",
+  bundle: true,
+  target: "es2022",
+  splitting: true,
+  format: "esm",
+  platform: "node",
+  packages: "external",
+  metafile: true,
+});
+
+const externals = Object.values(result.metafile?.inputs)
+  .map((input) => input.imports)
+  .flat()
+  .filter((input) => input.external);
+
+await writeFile(
+  new URL("../dist/meta.json", import.meta.url).pathname,
+  JSON.stringify(externals, null, 2),
+);
+
+const { node } = zodToTs(CommonConfigSchema, "User");
+const typeAlias = createTypeAlias(node, "CommonConfig");
+const nodeString = printNode(typeAlias);
+
+const code = `export ${nodeString}`;
+
+await writeFile(new URL("../dist/config.d.ts", import.meta.url).pathname, code);
+await copyFile(
+  new URL("../src/index.d.ts", import.meta.url).pathname,
+  new URL("../dist/index.d.ts", import.meta.url).pathname,
+);