OAC Vite Plugin

A Vite plugin that enables Ontology as Code (OAC) development by automatically generating ontology assets from TypeScript/JavaScript ontology definitions. This plugin handles the complete pipeline from ontology source code to ready-to-use OSDK (Ontology SDK) TypeScript files.

Features

• Automatic Asset Generation: Converts .ontology/ontology.mjs files into IR, full metadata, and OSDK TypeScript files
• Development Mode: File watching with hot reload - changes to ontology files trigger automatic regeneration
• Build Mode: Seamless integration with Vite's build process for production builds
• Intelligent Synchronization: Only updates changed files to minimize build times
• Foundry Middleware: Local development server with mock Foundry API support
• Comprehensive Error Handling: Detailed logging and debug information preservation on failures

Installation

pnpm add @osdk/vite-plugin-oac

Usage

Add the plugin to your vite.config.ts:

import oacVitePlugin from "@osdk/vite-plugin-oac";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    oacVitePlugin(),
    // ... other plugins
  ],
});

Generated Assets Pipeline

The plugin orchestrates a three-stage generation process:

.ontology/ontology.mjs  →  .ontology.ir.json  →  .ontology.json  →  .osdk/src/*
     (Source)               (IR Format)        (Full Metadata)      (OSDK Files)

Stage 1: JavaScript/TypeScript → IR

• Uses @osdk/maker to convert ontology source code to Intermediate Representation (IR)
• Input: .ontology/ontology.mjs
• Output: .ontology.ir.json

Stage 2: IR → Full Metadata

• Converts IR format to complete ontology metadata
• Input: .ontology.ir.json
• Output: .ontology.json

Stage 3: Full Metadata → OSDK

• Generates TypeScript SDK files using @osdk/cli
• Input: .ontology.json
• Output: .osdk/src/* directory structure

Development vs Build Mode

Development Mode

• File Watching: Monitors .ontology/ directory for changes
• Hot Reload: Automatically regenerates assets when files change
• Foundry Middleware: Provides mock Foundry API for local development
• Event Emitters: Notifies other systems when regeneration completes

Build Mode

• One-time Generation: Runs during Vite's buildStart hook
• Build Integration: Ensures assets are ready before the main build process
• Error Propagation: Build fails if ontology generation fails

File Structure

.@osdk/vite-plugin-oac/
├── index.ts                      # Main plugin entry point
├── generateOntologyAssets.ts     # Core generation logic (shared by dev/build)
├── watchOntologyAsCode.ts        # Development mode file watching
├── syncDirectories.ts            # Intelligent file synchronization
├── FoundryMiddlewareController.ts # Mock Foundry API middleware
├── package.json                  # Plugin dependencies and metadata
└── tsconfig.json                 # TypeScript configuration

Key Files

• index.ts: Main Vite plugin that coordinates between development and build modes
• generateOntologyAssets.ts: Contains the core three-stage generation pipeline
• watchOntologyAsCode.ts: Handles file watching and change detection in development
• syncDirectories.ts: Efficiently synchronizes generated files using SHA-256 hashing
• FoundryMiddlewareController.ts: Provides local Foundry API simulation for development

Error Handling

The plugin includes comprehensive error handling:

• Detailed Logging: All operations are logged with timestamps
• Debug Preservation: Failed generations leave temporary files for inspection
• Graceful Cleanup: Successful operations clean up temporary files
• Build Failure: Build process stops if ontology generation fails

Configuration

The plugin currently uses sensible defaults:

• Ontology Directory: .ontology/
• IR Output: .ontology.ir.json
• Metadata Output: .ontology.json
• OSDK Output: .osdk/src/

Best Practices

1. Ontology Structure: Keep your ontology definitions in .ontology/ontology.mjs
2. Version Control: Include generated .ontology.json in version control for reproducible builds
3. OSDK Files: Consider .osdk/src/ as generated code - don't edit manually
4. Error Debugging: Check temporary directories mentioned in error logs for debugging failed generations

Troubleshooting

Generation Failures

• Check the Vite dev server logs for detailed error messages
• Look for temporary directories mentioned in error logs
• Ensure all required dependencies are installed

File Synchronization Issues

• The plugin uses SHA-256 hashing to detect changes
• Only modified files are updated to minimize build times
• Empty directories are automatically cleaned up

Development Server Issues

• The Foundry middleware provides mock API responses
• Check browser developer tools for API-related errors
• Ensure ontology definitions are valid before testing

License

Part of the larger OAC (Ontology as Code) development ecosystem.