metabuilder/old/PACKAGE_IMPORT_EXPORT.md

Package Import/Export Guide

Overview

The MetaBuilder Package Import/Export system allows you to package and share complete applications, features, or database snapshots as ZIP files. This enables modular development and easy distribution of pre-built functionality.

Features

Export Capabilities

1. Custom Package Export

   • Create reusable packages with selected components
   • Include or exclude specific data types
   • Add metadata (name, version, author, description, tags)
   • Automatic README generation

2. Database Snapshot Export

   • Complete backup of entire database
   • One-click export with timestamp
   • Includes all schemas, pages, workflows, scripts, and configurations

3. Selective Export Options

   • ✅ Data schemas
   • ✅ Page configurations
   • ✅ Workflows
   • ✅ Lua scripts
   • ✅ Component hierarchies
   • ✅ Component configurations
   • ✅ CSS classes
   • ✅ Dropdown configurations
   • ✅ Seed data
   • ✅ Assets (images, videos, audio, documents)

Import Capabilities

1. Package Installation

   • Import packages from ZIP files
   • Automatic validation of package structure
   • Merge with existing data
   • Asset restoration

2. Safety Features

   • Package validation before import
   • Non-destructive merging (adds to existing data)
   • Import warnings and confirmations

ZIP Package Structure

package-name-1.0.0.zip
├── manifest.json          # Package metadata
├── content.json           # Database content
├── README.md              # Auto-generated documentation
└── assets/                # Asset files
    ├── asset-manifest.json
    ├── images/
    │   └── *.png, *.jpg, *.svg
    ├── videos/
    │   └── *.mp4, *.webm
    ├── audios/
    │   └── *.mp3, *.wav
    └── documents/
        └── *.pdf, *.txt

manifest.json

{
  "id": "pkg_1234567890",
  "name": "My Package",
  "version": "1.0.0",
  "description": "Package description",
  "author": "Your Name",
  "category": "social",
  "icon": "📦",
  "screenshots": [],
  "tags": ["tag1", "tag2"],
  "dependencies": [],
  "createdAt": 1234567890,
  "updatedAt": 1234567890,
  "downloadCount": 0,
  "rating": 0,
  "installed": false
}

content.json

{
  "schemas": [...],
  "pages": [...],
  "workflows": [...],
  "luaScripts": [...],
  "componentHierarchy": {...},
  "componentConfigs": {...},
  "cssClasses": [...],
  "dropdownConfigs": [...],
  "seedData": {...}
}

Usage

Exporting a Package

1. Navigate to Level 4 (God Panel) or Level 5 (Super God Panel)
2. Open Package Manager
3. Click Export button
4. Choose export type:
   • Custom Package: Configure metadata and select what to include
   • Full Snapshot: Export everything instantly
5. For custom packages:
   • Fill in package name (required)
   • Add version, author, description
   • Add tags for searchability
   • Select export options (checkboxes)
6. Click Export Package
7. ZIP file will download automatically

Importing a Package

1. Navigate to Level 4 (God Panel) or Level 5 (Super God Panel)
2. Open Package Manager
3. Click Import button
4. Click the upload area or drag a ZIP file
5. Package will be validated and imported
6. Success message shows what was imported
7. Refresh the page if needed to see new content

Pre-Built Packages

The system comes with several pre-built packages in the Package Catalog:

1. Classic Forum 💬

• Discussion threads and categories
• User profiles and moderation
• Schema: ForumCategory, ForumThread, ForumPost

2. Retro Guestbook 📖

• 90s-style visitor messages
• Custom backgrounds and GIFs
• Schema: GuestbookEntry

3. Video Platform 🎥

• Video upload and streaming
• Comments, likes, subscriptions
• Schema: Video, VideoComment, Subscription, Playlist

4. Music Streaming Platform 🎵

• Artists, albums, tracks
• Playlists and playback
• Schema: Artist, Album, Track, MusicPlaylist

5. Retro Games Arcade 🕹️

• Game collection with high scores
• Leaderboards and achievements
• Schema: Game, HighScore, Achievement, UserAchievement

6. E-Commerce Store 🛒

• Product catalog and inventory
• Shopping cart and orders
• Schema: Product, Cart, Order

Best Practices

For Package Authors

1. Descriptive Naming: Use clear, descriptive package names
2. Versioning: Follow semantic versioning (major.minor.patch)
3. Documentation: Add comprehensive descriptions and tags
4. Dependencies: List any required packages
5. Testing: Test your package before distribution
6. Assets: Include all necessary assets in the package

For Package Users

1. Backup First: Export a database snapshot before importing new packages
2. Review Contents: Check package contents in Package Manager before installing
3. Test in Development: Test new packages in a development environment first
4. Check Conflicts: Be aware of potential schema or page ID conflicts
5. Documentation: Read the package README for setup instructions

API Reference

Export Functions

import { exportPackageAsZip, downloadZip } from '@/lib/package-export'

// Export a custom package
const blob = await exportPackageAsZip(manifest, content, assets, options)
downloadZip(blob, 'package-name.zip')

// Export database snapshot
const blob = await exportDatabaseSnapshot(
  schemas,
  pages,
  workflows,
  luaScripts,
  componentHierarchy,
  componentConfigs,
  cssClasses,
  dropdownConfigs,
  assets
)

Import Functions

import { importPackageFromZip } from '@/lib/package-export'

// Import from ZIP file
const { manifest, content, assets } = await importPackageFromZip(zipFile)

Troubleshooting

Import Fails

• Invalid ZIP: Ensure the ZIP file has the correct structure
• Missing manifest.json: Package must include a manifest file
• Missing content.json: Package must include content data
• Corrupted File: Try re-downloading or re-exporting the package

Export Fails

• No Package Name: Package name is required for custom exports
• No Data: Ensure your database has data to export
• Browser Memory: Large exports may fail on low-memory devices

Assets Not Working

• Path Issues: Asset paths are preserved from the original location
• Missing Files: Ensure all assets were included during export
• Format Support: Only specific formats are supported (see structure above)

Future Enhancements

Planned features for future versions:

• 🔄 Package versioning and updates
• 🔍 Package marketplace/registry
• 🔐 Package signing and verification
• 📦 Dependency resolution
• 🎨 Custom package icons
• 📸 Package screenshots
• 💬 Package reviews and ratings
• 🔗 Remote package installation via URL
• 📊 Package analytics

Support

For issues or questions:

• Check the console for error messages
• Verify ZIP file structure
• Ensure you have the latest version of MetaBuilder
• Review this documentation for proper usage

---

Note: The import/export system is designed to be non-destructive. Imported data is merged with existing data rather than replacing it. Always backup your database before major imports.