@playcademy/vite-plugin 0.1.26-alpha.6 → 0.1.27

package/dist/lib/logging/utils.d.ts

@@ -20,4 +20,6 @@ export declare const log: {
 export declare function printBanner(viteConfig: ResolvedConfig, servers: {
     sandbox: number;
     backend?: number;
+    realtime?: number;
+    vite?: number;
 }, projectInfo: ProjectInfo, pluginVersion: string): void;

package/dist/lib/sandbox/server.d.ts

@@ -5,5 +5,10 @@ export declare function startSandbox(viteConfig: ResolvedConfig, autoStart?: boo
     customUrl?: string;
     quiet?: boolean;
     recreateDb?: boolean;
+    seed?: boolean;
+    memoryOnly?: boolean;
+    databasePath?: string;
+    realtimeEnabled?: boolean;
+    realtimePort?: number;
     logLevel?: 'debug' | 'info' | 'warn' | 'error';
 }): Promise<SandboxManager>;

package/dist/server/platform-mode.d.ts

@@ -9,6 +9,11 @@ export interface PlatformModeOptions {
     logLevel: 'debug' | 'info' | 'warn' | 'error';
     sandboxUrl: string;
     recreateDb: boolean;
+    seed: boolean;
+    memoryOnly: boolean;
+    databasePath?: string;
+    realtimeEnabled: boolean;
+    realtimePort?: number;
     showBadge: boolean;
     preferredBackendPort: number;
 }

package/dist/types/internal.d.ts

@@ -14,6 +14,11 @@ export interface ResolvedPluginOptions {
     verbose: boolean;
     logLevel: 'debug' | 'info' | 'warn' | 'error';
     recreateDb: boolean;
+    seed: boolean;
+    memoryOnly: boolean;
+    databasePath?: string;
+    realtimeEnabled: boolean;
+    realtimePort?: number;
     showBadge: boolean;
 }
 /**
@@ -50,6 +55,7 @@ export interface SandboxManager {
     baseUrl: string;
     realtimeUrl: string;
     port: number;
+    realtimePort?: number;
     project: ProjectInfo | null;
     cleanup: () => void;
 }

package/dist/types/options.d.ts

@@ -3,58 +3,319 @@
  */
 /**
  * Plugin operation mode
- * - 'platform': Full Playcademy platform with sandbox + backend + shell wrapper (default)
- * - 'standalone': Backend only, no sandbox or shell (for testing integrations)
+ *
+ * Controls how the Vite plugin operates during development:
+ * - `'platform'`: Full Playcademy platform experience with sandbox server, backend bundling, and shell wrapper (default)
+ * - `'standalone'`: Backend only, no sandbox or shell
+ *
+ * @default 'platform'
  */
 export type PlaycademyMode = 'platform' | 'standalone';
 /**
- * Configuration options for exporting Playcademy games
+ * Configuration options for exporting/building Playcademy games
+ *
+ * Controls how your game is packaged for deployment.
  */
 export interface PlaycademyExportOptions {
     /**
-     * Automatically create a deployment zip archive at .playcademy/{project-name}.zip
+     * Automatically create a deployment zip archive after build.
+     *
+     * The zip file is created at `.playcademy/{project-name}.zip` and contains
+     * all files needed for deployment (frontend assets + backend bundle).
+     *
      * @default true
+     * @example
+     * ```ts
+     * export: {
+     *   autoZip: false // Disable auto-zipping
+     * }
+     * ```
      */
     autoZip?: boolean;
 }
 /**
  * Configuration options for the Playcademy sandbox server
+ *
+ * The sandbox server provides a local development environment that simulates
+ * the Playcademy platform, including API endpoints, authentication, and database.
  */
 export interface PlaycademySandboxOptions {
+    /**
+     * Automatically start the sandbox server when Vite starts.
+     *
+     * Set to `false` if you want to start the sandbox server manually.
+     *
+     * @default true
+     * @example
+     * ```ts
+     * sandbox: {
+     *   autoStart: false // Start sandbox manually
+     * }
+     * ```
+     */
     autoStart?: boolean;
+    /**
+     * Custom URL for the sandbox server.
+     *
+     * Useful if you need to run the sandbox on a specific host or port.
+     * By default, the sandbox uses `http://localhost:{port}` where port
+     * is auto-assigned.
+     *
+     * @example
+     * ```ts
+     * sandbox: {
+     *   url: 'http://localhost:8788'
+     * }
+     * ```
+     */
     url?: string;
+    /**
+     * Enable verbose logging for the sandbox server.
+     *
+     * Shows detailed information about requests, database operations, and more.
+     * Equivalent to setting `logLevel: 'debug'`.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * sandbox: {
+     *   verbose: true
+     * }
+     * ```
+     */
     verbose?: boolean;
     /**
-     * Log level for the sandbox server
+     * Log level for the sandbox server.
+     *
+     * Controls the verbosity of sandbox server logs:
+     * - `'debug'`: Very detailed logs (all operations)
+     * - `'info'`: Standard operational logs
+     * - `'warn'`: Warnings only
+     * - `'error'`: Errors only
+     *
      * @default 'info'
+     * @example
+     * ```ts
+     * sandbox: {
+     *   logLevel: 'debug' // Show all debug info
+     * }
+     * ```
      */
     logLevel?: 'debug' | 'info' | 'warn' | 'error';
     /**
-     * Recreate the sandbox database on each start
+     * Recreate the sandbox database on each server start.
+     *
+     * When `true`, the database is dropped and recreated with seed data
+     * every time the dev server starts. Useful for ensuring a clean state
+     * during development.
+     *
+     * **Warning**: All existing data will be lost on each restart.
+     *
      * @default false
+     * @example
+     * ```ts
+     * sandbox: {
+     *   recreateDb: true // Fresh database on every restart
+     * }
+     * ```
      */
     recreateDb?: boolean;
+    /**
+     * Seed the database with demo data on startup.
+     *
+     * Creates demo users, games, achievements, and other platform data
+     * for testing. Disable if you want to start with an empty database.
+     *
+     * @default true
+     * @example
+     * ```ts
+     * sandbox: {
+     *   seed: false // Start with empty database
+     * }
+     * ```
+     */
+    seed?: boolean;
+    /**
+     * Use an in-memory database instead of a file.
+     *
+     * The database only exists in RAM and is lost when the server stops.
+     * Faster but non-persistent. Useful for testing and CI environments.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * sandbox: {
+     *   memoryOnly: true // Database in RAM only
+     * }
+     * ```
+     */
+    memoryOnly?: boolean;
+    /**
+     * Custom path for the database file.
+     *
+     * Specifies where the SQLite database file should be stored.
+     * If not provided, defaults to a path based on node_modules location.
+     *
+     * Special value `':memory:'` creates an in-memory database
+     * (equivalent to `memoryOnly: true`).
+     *
+     * @example
+     * ```ts
+     * sandbox: {
+     *   databasePath: './my-game-sandbox.db'
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * sandbox: {
+     *   databasePath: ':memory:' // In-memory database
+     * }
+     * ```
+     */
+    databasePath?: string;
+    /**
+     * Real-time/WebSocket server configuration.
+     *
+     * The real-time server provides WebSocket support for live updates,
+     * multiplayer features, and other real-time functionality.
+     *
+     * @default { enabled: false }
+     * @example
+     * ```ts
+     * sandbox: {
+     *   realtime: {
+     *     enabled: true,
+     *     port: 4322 // Custom WebSocket port
+     *   }
+     * }
+     * ```
+     */
+    realtime?: {
+        /**
+         * Enable the real-time/WebSocket server.
+         *
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Port for the WebSocket server.
+         *
+         * By default, uses the HTTP port + 1 (e.g., if HTTP is 4321,
+         * WebSocket will be 4322).
+         */
+        port?: number;
+    };
 }
 /**
  * Configuration options for the development shell wrapper
+ *
+ * The shell provides the platform UI during development, including the
+ * Playcademy badge, game selection, and other platform features.
  */
 export interface PlaycademyShellOptions {
     /**
-     * Show the Playcademy badge in the corner during development
+     * Show the Playcademy badge in the corner during development.
+     *
      * @default true
+     * @example
+     * ```ts
+     * shell: {
+     *   showBadge: false // Hide the badge
+     * }
+     * ```
      */
     showBadge?: boolean;
 }
 /**
- * Main plugin configuration options
+ * Main configuration options for the Playcademy Vite plugin
+ *
+ * Configure how your game integrates with the Playcademy platform during
+ * development and build.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { playcademy } from '@playcademy/vite-plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     playcademy({
+ *       mode: 'platform',
+ *       sandbox: {
+ *         logLevel: 'debug',
+ *         recreateDb: true
+ *       },
+ *       shell: {
+ *         showBadge: true
+ *       }
+ *     })
+ *   ]
+ * })
+ * ```
  */
 export interface PlaycademyPluginOptions {
     /**
-     * Plugin operation mode
+     * Plugin operation mode.
+     *
+     * - `'platform'`: Full development experience with sandbox server and shell (recommended)
+     * - `'standalone'`: Backend bundling only, no platform features
+     *
+     * Most games should use `'platform'` mode.
+     *
      * @default 'platform'
+     * @example
+     * ```ts
+     * {
+     *   mode: 'standalone' // For testing backend in isolation
+     * }
+     * ```
      */
     mode?: PlaycademyMode;
+    /**
+     * Export/build configuration options.
+     *
+     * Controls how your game is packaged for deployment.
+     *
+     * @example
+     * ```ts
+     * {
+     *   export: {
+     *     autoZip: true // Create deployment zip automatically
+     *   }
+     * }
+     * ```
+     */
     export?: PlaycademyExportOptions;
+    /**
+     * Sandbox server configuration options.
+     *
+     * The sandbox provides a local Playcademy platform environment for development.
+     *
+     * @example
+     * ```ts
+     * {
+     *   sandbox: {
+     *     logLevel: 'debug',
+     *     recreateDb: true
+     *   }
+     * }
+     * ```
+     */
     sandbox?: PlaycademySandboxOptions;
+    /**
+     * Development shell configuration options.
+     *
+     * The shell wraps your game with platform UI during development.
+     *
+     * @example
+     * ```ts
+     * {
+     *   shell: {
+     *     showBadge: false
+     *   }
+     * }
+     * ```
+     */
     shell?: PlaycademyShellOptions;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/vite-plugin",
-    "version": "0.1.26-alpha.6",
+    "version": "0.1.27",
     "type": "module",
     "exports": {
         ".": {
@@ -21,11 +21,11 @@
     "dependencies": {
         "archiver": "^7.0.1",
         "picocolors": "^1.1.1",
-        "playcademy": "0.14.4"
+        "playcademy": "0.14.5"
     },
     "devDependencies": {
         "@inquirer/prompts": "^7.8.6",
-        "@playcademy/sandbox": "0.1.9",
+        "@playcademy/sandbox": "0.1.10",
         "@types/archiver": "^6.0.3",
         "@types/bun": "latest"
     },