DGate API Documentation View

A modern, type-safe React component library for rendering and managing API documentation interfaces. Built with Zustand for state management and designed for scalability and developer experience.

Features

• 🎯 Type-Safe State Management: Built with Zustand and TypeScript for reliable state handling
• 🏗️ Modular Architecture: Separation of concerns between view and editor states
• ⚡ Performance Optimized: Selective subscriptions to minimize unnecessary re-renders
• 🛠️ Developer Experience: Comprehensive TypeScript support with excellent IDE integration
• 🎨 Theme Support: Built-in light/dark theme switching capabilities
• 📝 Content Editing: Integrated editor state management for content modification workflows

Quick Start

Installation

pnpm install

Development

pnpm run build

Usage Example

import { useStore } from './store'

function MyComponent() {
  // State access
  const theme = useStore((state) => state.view.theme)
  const isEditing = useStore((state) => state.editor.isEditing)

  // Actions
  const setTheme = useStore((state) => state.setTheme)
  const startEdit = useStore((state) => state.startEdit)

  return (
    <div className={`theme-${theme}`}>
      <button onClick={() => setTheme('dark')}>Switch Theme</button>
      <button onClick={() => startEdit('content')}>Edit Content</button>
    </div>
  )
}

Architecture

Store Organization

The application state is organized into two primary domains:

• View State: UI preferences, display data, and user interface state
• Editor State: Content editing, form management, and modification tracking

Key Components

• src/store/: Centralized state management with Zustand
• src/store/README.md: Complete usage guide with examples
• src/types/: TypeScript definitions and interfaces

State Management Patterns

Direct State Access

const count = useStore((state) => state.view.count)

Action Dispatching

const increment = useStore((state) => state.increment)
increment()

Computed Values

const totalItems = useStore((state) => state.getItemCount())

Development Guidelines

Adding New Features

1. Define interfaces in the store types
2. Add initial state values
3. Implement actions with proper typing
4. Create computed getters as needed
5. See src/store/README.md for detailed examples

Best Practices

• Use TypeScript strictly for all implementations
• Leverage Immer for immutable state updates
• Organize actions by domain (view vs editor)
• Implement computed values for derived state
• Use selective subscriptions for performance

Technical Stack

• Zustand: Lightweight state management
• TypeScript: Type safety and developer experience
• Immer: Immutable state updates
• React: UI component framework
• DevTools: Debugging and state inspection

Local Development Setup

Linking this package locally with pnpm

This guide explains how to link @digi-frontend/dgate-api-documentation with a separate React app for live development.

Folder layout

Place the app and this library side-by-side (for example, on Desktop):

Desktop/
  dgate-api-documentation/       ← this repo (the library)
  your-react-app/                 ← the consuming app

1) In the app: install peer dependencies

The app must provide the library's required peers:

cd .\your-next-app
pnpm add react react-dom antd @ant-design/cssinjs

In the library, keep react, react-dom, antd, and @ant-design/cssinjs in peerDependencies (and optionally in devDependencies for local lib testing).
Do not put them in dependencies in the lib.

2) In the app: link the library by relative path

Remove any previous install and add the link:

pnpm remove @digi-frontend/dgate-api-documentation
pnpm add @digi-frontend/dgate-api-documentation@link:../dgate-api-documentation

If the path has spaces, quote it:

pnpm add @digi-frontend/dgate-api-documentation@link:"../dgate-api-documentation"

3) In the app: Next.js config (webpack-only)

Use webpack in dev and let Next transpile the linked package.

next.config.ts (in the app):

import type { NextConfig } from 'next'

const config: NextConfig = {
  // Transpile the linked library if it ships TS/ESM source
  transpilePackages: ['@digi-frontend/dgate-api-documentation'],

  webpack(config) {
    // Follow pnpm symlinks so HMR works across repos
    config.resolve.symlinks = true
    return config
  },

  eslint: { ignoreDuringBuilds: true },
}

export default config

Start dev (webpack):

pnpm dev

Don't pass --turbo/--turbopack. Turbopack does not follow out-of-tree links.

4) In the library: start development mode

To enable live updates, run the development server in the library package:

cd ../dgate-api-documentation
pnpm dev

This will start the library in watch mode, allowing changes to be reflected immediately in the consuming app.

5) Verify the link

From the app folder:

# Show that the dependency is linked
pnpm list @digi-frontend/dgate-api-documentation

# Show the symlink target path on disk
(Get-Item ./node_modules/@digi-frontend/dgate-api-documentation).Target

Optionally resolve the entry file:

# CJS resolution (works if the package exposes a CJS entry)
node -p "require.resolve('@digi-frontend/dgate-api-documentation')"

If your package is ESM-only:

node --input-type=module -p "import.meta.resolve('@digi-frontend/dgate-api-documentation')"

If require.resolve('@pkg/package.json') fails with ERR_PACKAGE_PATH_NOT_EXPORTED,
that's normal unless you explicitly export ./package.json in the lib's exports.

6) Troubleshooting

Fast Refresh performs full reload
A module from the lib is likely imported both inside and outside the React render tree.
Split React components/hooks and non-React utilities into separate modules/entries (e.g., @pkg/react vs @pkg/core).

"Invalid hook call" (duplicate React)

• Ensure the lib keeps react and react-dom in peerDependencies (not dependencies).
• The app must install compatible versions.
• If needed, hard-dedupe to the app's React in next.config.ts:

webpack(config) {
  config.resolve.alias = {
    ...(config.resolve.alias ?? {}),
    react: require('path').resolve(__dirname, 'node_modules/react'),
    'react-dom': require('path').resolve(__dirname, 'node_modules/react-dom'),
  }
  return config
}

File watching on Windows is flaky
Enable polling temporarily:

$env:WATCHPACK_POLLING="true"; pnpm dev

Avoid pnpm link --global
Global links resolve peers relative to the lib folder and can cause missing/duplicate React/AntD in the app.

7) Unlink / switch back to registry

From the app folder:

pnpm remove @digi-frontend/dgate-api-documentation
pnpm add @digi-frontend/dgate-api-documentation    # install from registry again

8) Alternatives (if you don't want a live symlink)

Local tarball

# in the lib
pnpm pack  # creates a .tgz
# in the app
pnpm add ../dgate-api-documentation/@digi-frontend/dgate-api-documentation-x.y.z.tgz

file: protocol (no live updates)

{
  "dependencies": {
    "@digi-frontend/dgate-api-documentation": "file:../dgate-api-documentation"
  }
}

pnpm install

Summary

• Link with:

pnpm add @digi-frontend/dgate-api-documentation@link:../dgate-api-documentation

• Run webpack dev (pnpm dev, no Turbopack).
• Keep peers in the app, not as dependencies in the lib.
• Verify with pnpm list and Get-Item … .Target.