​Dev Portal Migration Guide

Prepare Your Environment

Clone your existing Zuplo project locally. We recommend trying this in a branch and deploying to a preview environment first.

git clone https://github.com/my-org/my-api
cd my-api
git checkout -b dev-portal-migration
bash

Create Directory Structure

Set up your new directory structure by creating the following files and folders:

• Create docs/zudoku.config.ts as an empty file, the contents will be added later.
• Create docs/package.json as an empty file, the contents will be added later.
• Create docs/tsconfig.json as an empty file, the contents will be added later.
• Create a directory docs/pages for your markdown files
• Create a directory docs/public for images and other static assets

Once these files are created your directory structure should look like this. Note, that the old dev portal files are still in place. You will delete them later.

my-api/
├─ config/
│  ├─ dev-portal.json # <- Your existing dev-portal.json
│  ├─ routes.oas.json
│  ├─ policies.json
├─ docs/
│  ├─ sidebar.json # <- Your existing sidebar.json
│  ├─ theme.css # <- Your existing theme.css
│  ├─ zudoku.config.ts
│  ├─ package.json
│  ├─ tsconfig.json
│  ├─ pages/
│  │  ├─ doc.md # <- Your existing markdown files
│  ├─ public/ # <- Your images and other static assets
├─ .gitignore
├─ package.json
├─ tsconfig.json
├─ README.md
txt

Update Typescript Configuration File

If you haven't already, create a tsconfig.json file in the docs folder and update the file with the following content.

docs/tsconfig.json
{
  "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,
    "types": ["zudoku/client"],
    "jsx": "react-jsx"
  }
}
json

Update package.jsonFile

If you haven't already, create a package.json file in the docs folder and update the file with the following content.

docs/package.json
{
  "name": "docs",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "scripts": {
    "dev": "zudoku dev --zuplo",
    "build": "zudoku build --zuplo"
  },
  "dependencies": {
    "react": ">19.0.0",
    "react-dom": ">19.0.0",
    "zudoku": "^0.39"
  },
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^22",
    "@types/react": "^19",
    "@types/react-dom": "^19"
  }
}
json

Update Root Package.json

Add the workspaces configuration to your root package.json file. Optionally, add a new script docs to run the dev portal.

package.json
{
  "name": "my-api",
  "version": "0.1.0",
  "scripts": {
    "dev": "zuplo dev",
    "test": "zuplo test",
    "docs": "npm run dev --workspace docs"
  },
  "workspaces": {
    "packages": ["docs"]
  }
}
json

Migrate Dev Portal Configuration

If you haven't already done so, create a new zudoku.config.ts file in the docs directory to replace your existing dev-portal.json.

Here's how several fields map from old to new format. See the configuration documentation for a complete list of options.

Example configuration:

docs/zudoku.config.ts
import type { ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  site: {
    title: "My API", // Was pageTitle in the old format
    favicon: "https://www.example.org/favicon.ico", // Was faviconUrl
  },
  topNavigation: [
    { id: "documentation", label: "Documentation" },
    { id: "api", label: "API Reference" },
  ],
  sidebar: {
    documentation: [
      {
        type: "category",
        label: "Overview",
        items: ["introduction", "other-example"],
      },
    ],
  },
  redirects: [{ from: "/", to: "/introduction" }],
  apis: {
    type: "file",
    input: "../config/routes.oas.json",
    navigationId: "api",
  },
  docs: {
    files: "/pages/**/*.{md,mdx}",
  },
  authentication: {
    type: "auth0", // Was provider in the old format
    domain: process.env.ZUPLO_PUBLIC_AUTH0_DOMAIN,
    clientId: process.env.ZUPLO_PUBLIC_AUTH0_CLIENT_ID,
  },
};

export default config;
ts

Migrate Sidebar Configuration

Move your sidebar configuration from sidebar.json to the sidebar property in zudoku.config.ts:

Old format (sidebar.json):

[
  {
    "type": "category",
    "label": "Getting Started",
    "items": ["introduction", "quickstart"]
  },
  {
    "type": "doc",
    "id": "api-reference"
  }
]
json

New format (in zudoku.config.ts):

sidebar: {
  documentation: [
    {
      type: "category",
      label: "Getting Started",
      items: ["introduction", "quickstart"]
    },
    {
      type: "doc",
      id: "api-reference"
    }
  ],
  // You can add additional sidebar sections here
}
ts

Move Markdown Files

Move your markdown files to the docs/pages directory. The front matter format remains largely the same:

---
title: Introduction
sidebar_label: Intro
description: Introduction to our API
---
md

Set Up Images and Assets

Create a docs/public directory for your images and other static assets. See the documenation for more information on how to use static files in the new dev portal.

Install Dependencies

Run npm install from your project root to install all dependencies for both your API and documentation.

Test Locally

Start the dev portal locally with npm run docs and verify that:

• All pages load correctly
• Authentication works (if using it)
• All links between pages work
• API reference section loads your OpenAPI definitions
• Images and assets display properly

Delete Legacy Files

After confirming everything works, delete these files:

• /config/dev-portal.json
• /docs/sidebar.json
• /docs/theme.css

Deploy and Verify

Deploy your changes by either pushing to a git branch or by running npx zuplo deploy. After the deployment has completed, perform these final checks:

• Test all site navigation paths
• Verify authentication flows work correctly
• Check API reference documentation renders properly
• Test across different browsers and devices
• Verify custom styling and theming is applied correctly