create-holoscript-plugin

Scaffold HoloScript domain plugins following the multi-repo architecture pattern.

Quick Start

# Create a new plugin (interactive prompts)
npx create-holoscript-plugin

# Create with name
npx create-holoscript-plugin my-plugin

# Create scoped plugin
npx create-holoscript-plugin @holoscript/robotics-plugin

What Gets Created

holoscript-my-plugin/
├── src/
│   ├── index.ts           # Main exports
│   └── types.ts           # TypeScript types
├── python/                # Python bridge (optional)
│   └── bridge.py          # JSON-RPC server
├── tests/                 # Integration tests (optional)
│   └── integration.test.ts
├── docs/
│   └── api-reference.md   # API documentation template
├── package.json           # npm package config
├── tsconfig.json          # TypeScript config
├── jest.config.js         # Jest test config
├── .gitignore
├── LICENSE                # MIT license
└── README.md              # Usage guide

Features

✅ Multi-Repo Pattern: Follows validated HoloScript plugin architecture ✅ TypeScript First: Full type safety with holoscript@^3.1.0 peer dependency ✅ Python Bridge: Optional JSON-RPC bridge for external SDKs ✅ Unity Target: Optional Unity C# code generation (coming soon) ✅ Test Ready: Jest integration tests with 80%+ coverage target ✅ Domain Templates: Pre-configured for scientific, robotics, medical, AI/ML, game engines ✅ npm Ready: Package.json configured for publishing to npm

Plugin Domains

Choose from pre-configured domain templates:

| Domain | Use Cases | Example Plugins | |--------|-----------|-----------------| | Scientific Computing | Drug discovery, molecular dynamics, quantum chemistry | @holoscript/narupa-plugin | | Robotics | ROS2, Gazebo, URDF, digital twins | @holoscript/robotics-plugin | | Medical | DICOM, surgical sims, vitals monitoring | @holoscript/medical-plugin | | Game Engine | Unreal, advanced Unity features | @holoscript/unreal-plugin | | AI/ML | AlphaFold, diffusion models, neural nets | @holoscript/alphafold-plugin | | Custom | Your own domain | @yourcompany/custom-plugin |

Interactive Prompts

The CLI will guide you through:

1. Plugin name: @holoscript/my-plugin (scoped recommended)
2. Description: Short summary of plugin functionality
3. Domain: Pre-configured templates (scientific, robotics, medical, etc.)
4. Author: Your name or organization
5. Python bridge: Include JSON-RPC server for external SDKs? (recommended)
6. Unity target: Include Unity C# code generation? (recommended for VR/AR)
7. Tests: Include integration tests? (recommended, 80%+ coverage)

Architecture Pattern

All generated plugins follow the Core + Plugins + Tooling pattern:

HoloScript Core (canonical trait definitions)
  │
  ├─> @holoscript/my-plugin (domain implementation)
  │   └─> Uses: HoloScript traits as TypeScript constants
  │   └─> Provides: Domain-specific functionality (Python bridge, Unity C#, etc.)
  │
  └─> TrainingMonkey (AI training data - optional)
      └─> Uses: HoloScript traits for synthetic data generation

Key Principles:

• Core remains lightweight: Zero domain dependencies
• Plugins version independently: v1.0.0 can evolve without changing HoloScript core
• Modularity: Users install only needed plugins
• Ecosystem growth: Community can create plugins without forking core

See Multi-Repo Plugin Architecture Pattern for full details.

Example: Creating a Robotics Plugin

npx create-holoscript-plugin @holoscript/robotics-plugin

Prompts:

• Description: ROS2 and Gazebo integration for HoloScript
• Domain: Robotics (ROS2, Gazebo, URDF)
• Author: Your Name
• Python bridge: Yes (for ROS2 integration)
• Unity target: Yes (for VR robot programming)
• Tests: Yes

Generated Plugin:

// src/index.ts (after your implementation)
import { ROS2Bridge } from './ros2-bridge';
import { GazeboTarget } from './gazebo-target';

export { ROS2Bridge, GazeboTarget };
export const VERSION = '1.0.0';

export default {
  ROS2Bridge,
  GazeboTarget,
  VERSION,
};

Usage:

import { ROS2Bridge } from '@holoscript/robotics-plugin';

const bridge = new ROS2Bridge();
await bridge.connect('ws://localhost:9090');

Development Workflow

After generating a plugin:

cd holoscript-my-plugin

# Install dependencies
npm install

# Development mode (watch)
npm run dev

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Format code
npm run format

Publishing to npm

# Build production version
npm run build

# Publish (requires npm account)
npm publish --access public

Examples

See existing HoloScript plugins for reference:

• @holoscript/narupa-plugin - VR-based drug discovery (scientific computing)

Requirements

• Node.js: 18.0.0+
• npm: 9.0.0+
• TypeScript: 5.3.3+ (installed automatically)

FAQ

Q: Do I need to fork HoloScript core to create a plugin?

A: No! Plugins are separate npm packages with holoscript@^3.1.0 as a peer dependency. This keeps the core lightweight and enables independent versioning.

Q: Can I create plugins for commercial use?

A: Yes! All generated code is MIT licensed. You own your plugin.

Q: What if HoloScript core updates?

A: Plugins use peer dependencies, so they work with compatible HoloScript versions (e.g., ^3.1.0 works with 3.1.x and 3.2.x). Update your plugin's peer dependency when breaking changes occur.

Q: Can I generate plugins without npm?

A: No, this is an npm-based tool. Use npx (comes with npm) to run without installing globally.

Contributing

Contributions welcome! To improve the generator:

1. Fork this repo
2. Create a feature branch
3. Submit a PR with:
   • New domain template (add to prompts choices)
   • Enhanced scaffolding logic
   • Better defaults

Related

• HoloScript Core - Spatial computing language
• @holoscript/narupa-plugin - Scientific computing plugin (reference implementation)
• Multi-Repo Plugin Architecture Pattern - Architecture docs
• TrainingMonkey - AI training data generator

License

MIT © HoloScript Contributors

Generated plugins inherit the same MIT license. You own your plugins!

Pattern: Multi-Repo Plugin Architecture