zuplo 6.67.32 → 6.68.0

package/docs/dev-portal/migration.mdx

@@ -0,0 +1,526 @@
+---
+title: Dev Portal Migration Guide
+sidebar_label: Migration Guide
+description:
+  Instruction for migrating from the legacy developer portal to Zudoku.
+---
+
+This guide walks you through migrating your existing documentation from the
+current Dev Portal to the new Dev Portal powered by Zudoku. Follow these steps
+sequentially for a smooth transition.
+
+## Before you begin
+
+It's important to note that this migration is to a completely new developer
+portal. As such, there could be things that are different or don't map exactly
+to the old developer portal. This new developer portal is more powerful and
+flexible, but it may require some adjustments to your existing content and
+configuration.
+
+A few things to keep in mind before starting the migration:
+
+### Separate domain for Dev Portal
+
+New Dev Portals run on their own dedicated domain instead of a `/docs` path
+under your API. You must create a redirect route on `/docs` to maintain existing
+links. You can use the
+[Legacy Dev Portal Handler](/docs/handlers/legacy-dev-portal-handler) to achieve
+this.
+
+:::note
+
+Builder plans have been automatically upgraded to include two custom domains
+instead of one. This allows you to have a custom domain for both your API and
+your developer portal.
+
+:::
+
+### Authentication changes
+
+Not all authentication providers from the old Dev Portal are supported in the
+new Developer Portal. The previous "external" provider isn't supported. If you
+were using that provider, you will need to switch to a supported provider such
+as Auth0 or implement a custom authentication solution.
+
+### Other considerations
+
+- **Theming**: Custom CSS from the old Dev Portal isn't directly supported. You
+  will need to reapply any custom styles using the new theming options in
+  Zudoku.
+- **Navigation**: Navigation in the new developer portal is much more flexible,
+  but this does mean you will likely need to update your navigation structure.
+- **Dark Mode**: The new Dev Portal has built-in support for dark mode, which
+  wasn't available in the old portal. You may want to use a different logo for
+  dark mode.
+
+### Test in a preview environment
+
+Don't perform the migration directly on your production environment. Instead,
+create a preview environment to test the migration. This allows you to verify
+that everything works as expected before making the changes live.
+
+Things to test in the preview environment:
+
+- Navigation between pages
+- Authentication flows
+- API reference rendering
+- API Playground functionality
+- Custom theming and styles
+
+## Migration options
+
+There are three ways to migrate your existing Dev Portal to the new version.
+Choose the one that best fits your needs:
+
+- Migrate in the portal (for simple setups)
+- Quick migration with CLI (for most projects)
+- Manual migration process (for full control)
+
+### Migrate in the portal
+
+If you have a simple Dev Portal setup and prefer to migrate directly in the
+Zuplo Portal, you can use the built-in migration tool by opening the
+`config/dev-portal.json` file in the Zuplo Portal and clicking the **Migrate to
+Zudoku** button at the top of the editor. This will automatically create the
+necessary files and move your existing configuration and markdown files to the
+new format.
+
+<YouTubeEmbed videoId="g4AVK12nMAY" title="Dev Portal Migration" />
+
+### Quick migration with CLI
+
+For most projects, you can use the Zuplo CLI to automate the migration process:
+
+```bash
+npx zuplo source migrate dev-portal
+```
+
+This command will automatically:
+
+- Create the required directory structure
+- Generate necessary configuration files
+- Migrate your existing dev portal configuration
+- Move markdown files to the correct location
+
+See the [Source Commands](../cli/source-migrate.mdx) documentation for more
+details and options.
+
+If you prefer to understand each step or need more control over the migration
+process, continue with the manual migration steps below.
+
+### Manual migration process
+
+<Stepper>
+
+1. **Prepare Your Environment**
+
+   Clone your existing Zuplo project locally. We recommend trying this in a
+   branch and deploying to a preview environment first.
+
+   ```bash
+   git clone https://github.com/my-org/my-api
+   cd my-api
+   git checkout -b dev-portal-migration
+   ```
+
+   :::caution
+
+   Currently, this migration must be done locally. It cannot be done in the
+   Zuplo Portal.
+
+   :::
+
+1. **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.
+
+   ```txt
+   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
+   ```
+
+1. **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.
+
+   ```json title="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"
+     }
+   }
+   ```
+
+1. Update `package.json`File
+
+   If you haven't already, create a `package.json` file in the `docs` folder and
+   update the file with the following content.
+
+   ```json title="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"
+     }
+   }
+   ```
+
+1. **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.
+
+   ```json title="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"]
+     }
+   }
+   ```
+
+1. **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](./zudoku/configuration/overview.mdx) documentation for a
+   complete list of options.
+
+   | Old (`dev-portal.json`)    | New (`zudoku.config.ts`)                         |
+   | -------------------------- | ------------------------------------------------ |
+   | `pageTitle`                | `site.title`                                     |
+   | `faviconUrl`               | `metadata.favicon`                               |
+   | `enableAuthentication`     | Implied by presence of `authentication` property |
+   | `authentication.provider`  | `authentication.type`                            |
+   | `authentication.authority` | Provider-specific properties                     |
+   | (from sidebar.json)        | `navigation` array                               |
+
+   Example configuration:
+
+   ```ts title="docs/zudoku.config.ts"
+   import type { ZudokuConfig } from "zudoku";
+
+   const config: ZudokuConfig = {
+     site: {
+       title: "My API", // Was pageTitle in the old format
+     },
+     metadata: {
+       favicon: "https://www.example.org/favicon.ico", // Was faviconUrl
+     },
+     navigation: [
+       {
+         type: "category",
+         label: "Documentation",
+         items: [
+           "introduction", // Using shorthand for docs
+           "other-example",
+         ],
+       },
+       { type: "link", to: "/api", label: "API Reference" },
+     ],
+     redirects: [{ from: "/", to: "/introduction" }],
+     apis: [
+       {
+         type: "file",
+         input: "../config/routes.oas.json",
+         path: "/api",
+       },
+     ],
+     apiKeys: {
+       // Enable API Key Management, disabled by default
+       enabled: true,
+     },
+     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;
+   ```
+
+   :::tip
+
+   Environment variables are now referenced using `process.env` instead of
+   `$env()`.
+
+   :::
+
+1. **Migrate Sidebar Configuration**
+
+   Move your [sidebar configuration](./zudoku/configuration/navigation.mdx) from
+   `sidebar.json` to the `navigation` array in `zudoku.config.ts`:
+
+   **Old format (`sidebar.json`):**
+
+   ```json
+   [
+     {
+       "type": "category",
+       "label": "Getting Started",
+       "items": ["introduction", "quickstart"]
+     },
+     {
+       "type": "doc",
+       "id": "api-reference"
+     }
+   ]
+   ```
+
+   **New format (in `zudoku.config.ts`):**
+
+   ```ts
+   navigation: [
+     {
+       type: "category",
+       label: "Documentation",
+       items: [
+         {
+           type: "category",
+           label: "Getting Started",
+           items: [
+             {
+               type: "doc",
+               file: "introduction", // Note: no path prefix needed
+             },
+             {
+               type: "doc",
+               file: "quickstart",
+             },
+           ],
+         },
+         "authentication", // Directly reference doc files
+       ],
+     },
+     {
+       type: "link",
+       to: "/api",
+       label: "API Reference",
+     },
+   ];
+   ```
+
+1. **Move Markdown Files**
+
+   Move your markdown files to the `docs/pages` directory. The front matter
+   format remains largely the same:
+
+   ```md
+   ---
+   title: Introduction
+   sidebar_label: Intro
+   description: Introduction to our API
+   ---
+   ```
+
+1. **Set Up Images and Assets**
+
+   Create a `docs/public` directory for your images and other static assets. See
+   the [documentation](./zudoku/guides/static-files.mdx) for more information on
+   how to use static files in the new dev portal.
+
+1. **Install Dependencies**
+
+   Run `npm install` from your project root to install all dependencies for both
+   your API and documentation.
+
+1. **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
+
+1. **Delete Legacy Files**
+
+   After confirming everything works, delete these files:
+   - `/config/dev-portal.json`
+   - `/docs/sidebar.json`
+   - `/docs/theme.css`
+
+   :::caution
+
+   It is critical that you delete the `config/dev-portal.json` file after
+   completing the migration. If that file is not deleted, the Zuplo build system
+   will use the legacy dev portal.
+
+   :::
+
+1. **Deploy and Verify**
+
+   Deploy your changes by either pushing to a git branch or by running
+   [`npx zuplo deploy`](../cli/deploy.mdx). After the deployment has completed,
+   perform these final checks:
+   - Test all site navigation paths
+   - Verify authentication flows work correctly
+   - Check API reference documentation renders
+   - Test across different browsers and devices
+   - Verify custom styling and theming is applied correctly
+
+</Stepper>
+
+## Theming
+
+For instructions on theming the dev portal, see
+[Colors & Theme](./zudoku/customization/colors-theme.mdx) and
+[Fonts](./zudoku/customization/fonts.mdx).
+
+## Redirect legacy URLs
+
+The previous Dev Portal was hosted on a path on the same domains your Zuplo API
+(i.e. `https://api.example.com/docs`). The new Dev Portal is hosted on its own
+domain and can have its own custom domain (i.e. `https://docs.example.com`).
+Learn more about setting up custom domains in the
+[Custom Domains documentation](/docs/articles/custom-domains).
+
+If you were using the previous Dev Portal, you can redirect all requests from
+the legacy path to the new domain using the
+[Legacy Dev Portal Handler](/docs/handlers/legacy-dev-portal-handler). This
+allows you to maintain backwards compatibility for users who may have bookmarked
+or linked to the old Dev Portal URL.
+
+### Setup Instructions
+
+1. **Create a New Routes File**: In your Zuplo project, create a new OpenAPI
+   file called `legacy.oas.json` (or any name you prefer).
+
+2. **Add a Route**: Inside this file, add a route that matches the legacy path
+   and redirects to the new Dev Portal domain. You must set the path to the path
+   used by the previous Dev Portal, such as `/docs(.*)`. It's important not to
+   make the route `/docs(.*)` not `/docs/(.*)` in order to also match the root
+   path `/docs`.
+
+   For example:
+
+   ```json
+   {
+     "openapi": "3.1.0",
+     "info": {
+       "version": "1.0.0",
+       "title": "Dev Portal Redirect"
+     },
+     "paths": {
+       "/docs(.*)": {
+         "x-zuplo-path": {
+           "pathMode": "url-pattern"
+         },
+         "get": {
+           "summary": "Redirect",
+           "description": "Redirect to the new Dev Portal domain",
+           "x-zuplo-route": {
+             "corsPolicy": "none",
+             "handler": {
+               "export": "legacyDevPortalHandler",
+               "module": "$import(@zuplo/runtime)",
+               "options": {
+                 "mode": "redirect"
+               }
+             },
+             "policies": {
+               "inbound": []
+             }
+           },
+           "operationId": "dev-portal-redirect"
+         }
+       }
+     }
+   }
+   ```
+
+After you redeploy your Zuplo project, whenever the user navigates to the legacy
+developer portal paths, they will be redirected to the new Dev Portal domain.
+
+For more detailed information about the handler, including how to configure
+proxy mode to keep your developer portal on the same domain, see the
+[Legacy Dev Portal Handler](/docs/handlers/legacy-dev-portal-handler)
+documentation.
+
+### Additional redirects
+
+Your new developer portal may also change other paths. To create redirects for
+specific docs or other path in your new Dev Portal, we recommend using the
+`redirects` configuration in the `zudoku.config.ts` file. This allows you to
+specify multiple redirects easily. For more information, see the
+[Redirects section in the configuration docs](/docs/dev-portal/zudoku/configuration/overview#redirects)
+
+## Troubleshooting
+
+If you encounter issues during migration, check these common problems:
+
+- **Missing dependencies**: Ensure you've run `npm install` from the project
+  root.
+- **Authentication issues**: Verify your environment variables are correctly set
+  and authentication is properly configured.
+- **Sidebar not showing**: Check your sidebar configuration in
+  `zudoku.config.ts` and make sure file IDs match your markdown files.
+- **Images not loading**: Confirm image paths have been updated to point to the
+  new location.
+- **Environment variables not working**: Use `process.env.VARIABLE_NAME` instead
+  of `$env(VARIABLE_NAME)`.

package/docs/dev-portal/node-modules.mdx

@@ -0,0 +1,45 @@
+---
+title: Node Modules & Customization
+description:
+  Guide to installing custom node modules in Zuplo's developer portal.
+---
+
+The Dev Portal supports installing and using custom node modules in your
+documentation. This allows you to extend your documentation with custom React
+components, utilities, or any other npm packages.
+
+## Installing Custom Packages
+
+Inside your project's `/docs` directory, you can install any npm package using
+the standard npm commands:
+
+```bash
+npm install your-package-name
+```
+
+## Using Custom React Components
+
+You can import and use custom React components directly in the
+`zudoku.config.tsx` file or your MDX files:
+
+```jsx
+import { MyCustomComponent } from "your-package-name";
+
+<MyCustomComponent />;
+```
+
+## TypeScript Support
+
+The Dev Portal includes full TypeScript support for your custom components. Make
+sure your `tsconfig.json` includes the appropriate type definitions for your
+packages.
+
+## Limitations
+
+While you can use most npm packages, be mindful of:
+
+- Package size impact on build time
+- Browser compatibility for client-side components
+- Node.js-specific packages (like `fs` or `path`) cannot be used in
+  `zudoku.config.tsx` since it runs in both server and browser environments -
+  use environment-agnostic code only

package/docs/dev-portal/updating.mdx

@@ -0,0 +1,28 @@
+---
+title: Updating Versions
+description:
+  How to update Zuplo's developer portal to keep it up to date with the latest
+  changes.
+---
+
+When developing your Dev Portal locally, you likely want to keep your version of
+the Dev Portal up-to-date with the latest changes. This guide will walk you
+through the process of installing the latest version of the Dev Portal.
+
+Inside of your project's `/docs` directory, run the following command to update
+the Dev Portal's dependencies:
+
+```bash
+npm install zudoku@latest
+```
+
+Occasionally, there may be peer dependencies such as `react` that need to be
+updated. If you encounter any messages that indicate that peer dependencies need
+to be updated, run the following command:
+
+```bash
+npm install react@latest react-dom@latest
+```
+
+Updates that require more than just updating the dependencies will be noted in
+the changelog.