@kouovo/ph-vite-plugin-editor-api

A Vite plugin that provides a complete JSON and image editing API with a web-based frontend interface for development environments.

Overview

The @kouovo/ph-vite-plugin-editor-api package is a comprehensive Vite plugin that creates REST API endpoints for editing JSON files and managing images, along with a built-in web interface for easy file management during development.

Installation

npm install @kouovo/ph-vite-plugin-editor-api
# or
pnpm add @kouovo/ph-vite-plugin-editor-api
# or
yarn add @kouovo/ph-vite-plugin-editor-api

Usage

Basic Configuration

// vite.config.js
import { defineConfig } from 'vite';
import { ViteResourcesEditorApi } from '@kouovo/ph-vite-plugin-editor-api';

export default defineConfig({
  plugins: [
    ViteResourcesEditorApi({
      jsonDirectoryPath: './src/data',
      imagesDirectoryPath: './src/assets/images',
      apiBasePath: '/api/editable-json',
      frontendPath: '/json-editor',
      maxImageSize: 5 * 1024 * 1024, // 5MB
      allowedImageTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml']
    })
  ]
});

Alternative JSON-Only Configuration

// For JSON editing only (without image features)
import { ViteJsonEditorApi } from '@kouovo/ph-vite-plugin-editor-api';

export default defineConfig({
  plugins: [
    ViteJsonEditorApi({
      directoryPath: './src/data',
      apiBasePath: '/api/json-editor',
      frontendPath: '/json-editor'
    })
  ]
});

Configuration Options

ViteResourcesEditorApi Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | jsonDirectoryPath | string | Required | Path to directory containing JSON files | | imagesDirectoryPath | string | Required | Path to directory containing image files | | apiBasePath | string | '/api/editable-json' | Base path for API endpoints | | frontendPath | string \| null | '/json-editor' | Path for web interface (null to disable) | | maxImageSize | number | 1073741824 (1GB) | Maximum image upload size in bytes | | allowedImageTypes | string[] | ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml'] | Allowed image MIME types |

ViteJsonEditorApi Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | directoryPath | string | Required | Path to directory containing JSON files | | apiBasePath | string | '/api/editable-json' | Base path for API endpoints | | frontendPath | string \| null | '/json-editor' | Path for web interface (null to disable) |

API Endpoints

JSON Management Endpoints

GET /api/editable-json/list

Lists all JSON files in the configured directory.

Response:

["config.json", "data.json", "settings.json"]

GET /api/editable-json/get?filename={filename}

Retrieves the content of a specific JSON file.

Parameters:

• filename (query): Name of the JSON file to retrieve

Response:

{
  "key1": "value1",
  "key2": "value2",
  "nested": {
    "property": "value"
  }
}

POST /api/editable-json/save?filename={filename}

Saves content to a JSON file and synchronizes keys across other JSON files.

Parameters:

• filename (query): Name of the JSON file to save

Request Body:

{
  "key1": "updated value",
  "key2": "value2",
  "newKey": "new value"
}

Features:

• Validates JSON structure
• Automatically adds missing keys to other JSON files
• Pretty-prints JSON output
• Atomic file operations

Image Management Endpoints

GET /api/editable-json/images/list

Lists all supported image files in the configured directory.

Response:

["logo.png", "banner.jpg", "icon.svg"]

GET /api/editable-json/images/view/{filename}

Serves an image file with proper MIME type and caching headers.

Parameters:

• filename (path): Name of the image file to serve

Features:

• Automatic MIME type detection
• Security validation
• Caching headers
• Path traversal protection

POST /api/editable-json/images/upload

Uploads one or more image files with validation and security checks.

Request: multipart/form-data

• image (file): Image file(s) to upload (multiple files supported)

Response:

{
  "message": "Processed 2 file(s). 2 succeeded, 0 failed.",
  "results": [
    {
      "originalFilename": "photo.jpg",
      "filename": "photo.jpg",
      "success": true,
      "message": "Uploaded successfully."
    }
  ]
}

Features:

• Multiple file upload support
• File type validation
• Size limit enforcement
• Secure filename sanitization
• Detailed upload results

DELETE /api/editable-json/images/delete?filename={filename}

Deletes an image file from the directory.

Parameters:

• filename (query): Name of the image file to delete

Response:

{
  "message": "Image 'filename.jpg' deleted successfully."
}

Web Interface Features

JSON Editor

• Interactive Key-Value Editor: Visual editor for JSON object properties
• Real-time Validation: Immediate feedback on JSON syntax errors
• Change Detection: Tracks unsaved changes with visual indicators
• File Management: Switch between multiple JSON files
• Auto-sync: Automatically propagates new keys to other JSON files

Image Manager

• Visual Gallery: Grid view of all available images
• Drag & Drop Upload: Support for multiple file uploads
• Image Previews: Thumbnails with click-to-enlarge modal
• Integration: Direct image filename insertion into JSON values
• File Management: Delete images with confirmation

Advanced Features

• Responsive Design: Works on desktop and mobile devices
• Keyboard Shortcuts: Efficient navigation and editing
• Progress Indicators: Real-time feedback for uploads and operations
• Error Handling: Comprehensive error messages and recovery
• Accessibility: WCAG compliant interface elements

Security Features

Input Validation

• JSON Structure Validation: Ensures valid JSON object format
• Filename Sanitization: Prevents path traversal attacks
• File Type Validation: Strict MIME type checking
• Size Limits: Configurable upload size restrictions

Path Security

• Directory Containment: Operations limited to configured directories
• Filename Restrictions: Blocks dangerous characters and patterns
• Extension Validation: Only allows specified file extensions
• Buffer Analysis: Uses file-type detection for robust validation

Development Features

Hot Reload Support

• File Watching: Automatically reflects external file changes
• State Persistence: Maintains editor state across reloads
• Error Recovery: Graceful handling of file system changes

Integration

• Vite Plugin API: Full integration with Vite development server
• Middleware Support: Custom request processing
• Error Handling: Comprehensive error reporting and logging

Error Handling

The plugin includes comprehensive error handling for:

• File System Errors: Missing files, permission issues
• Validation Errors: Invalid JSON format, unsupported file types
• Network Errors: Upload failures, connection issues
• Security Errors: Path traversal attempts, unauthorized access

Performance Optimizations

• Parallel Operations: Concurrent file processing
• Efficient Caching: Optimized file serving with cache headers
• Memory Management: Streaming file operations where possible
• Lazy Loading: On-demand resource loading in the frontend

TypeScript Support

The package is fully typed with comprehensive TypeScript definitions:

• Configuration option interfaces
• API response types
• Error handling types
• Plugin integration types

Browser Support

• Modern browsers with ES6+ support
• File API for drag & drop uploads
• Fetch API for HTTP requests
• Grid and Flexbox CSS support

Development Commands

# Build the plugin
npm run build

# Type checking
npm run typecheck

# Development (if using examples)
npm run dev

License

MIT