@playcademy/vite-plugin 0.1.25 → 0.1.26-alpha.2

package/README.md

@@ -78,11 +78,8 @@ export default defineConfig({
     plugins: [
         playcademy({
             export: {
-                bootMode: 'iframe', // 'iframe' | 'module'
-                entryPoint: 'index.html', // Main HTML file
-                platform: 'web', // 'web' | 'godot' | 'unity'
+                platform: 'web', // Platform identifier (auto-detected)
                 autoZip: false, // Create deployment zip
-                styles: [], // Additional CSS files
             },
             sandbox: {
                 autoStart: true, // Start sandbox automatically
@@ -134,13 +131,10 @@ export default defineConfig({
 
 Configuration for manifest generation and build output:
 
-| Option       | Type                          | Default        | Description                     |
-| ------------ | ----------------------------- | -------------- | ------------------------------- |
-| `bootMode`   | `'iframe' \| 'module'`        | `'iframe'`     | How the game should be launched |
-| `entryPoint` | `string`                      | `'index.html'` | Main HTML file for your game    |
-| `platform`   | `'web' \| 'godot' \| 'unity'` | `'web'`        | Game engine/platform type       |
-| `autoZip`    | `boolean`                     | `false`        | Create deployment zip archive   |
-| `styles`     | `string[]`                    | `[]`           | Additional CSS files to load    |
+| Option     | Type      | Default | Description                                    |
+| ---------- | --------- | ------- | ---------------------------------------------- |
+| `platform` | `string`  | `'web'` | Platform identifier (e.g., 'web', 'godot@4.3') |
+| `autoZip`  | `boolean` | `false` | Create deployment zip archive                  |
 
 ### Sandbox Options (`sandbox`)
 
@@ -178,15 +172,47 @@ PLAYCADEMY v1.2.3
 ➜  Sandbox:  http://localhost:4321/api
 ```
 
-**How it works**: When you visit `http://localhost:5173/` in your browser, you'll see your game wrapped in the Playcademy development shell (which mimics the production platform environment). Inside the iframe, your game is served at the root path `/`, so client-side routers (React Router, etc.) work naturally without any special configuration.
+**How it works**: When you visit `http://localhost:5173/` in your browser, you'll see your game wrapped in the Playcademy development shell (which mimics the production platform environment). Inside the iframe, your game is served at the root path `/`, so client-side routers (React Router, wouter, etc.) work naturally without any special configuration.
 
 The plugin uses the `Sec-Fetch-Dest` header to intelligently detect whether a request is from the shell's iframe or top-level browser navigation, automatically serving the appropriate content.
 
+**Client-side routing**: Both in development and production, your routers will see clean paths like `/` and `/game`. In production, the platform uses a game runner that loads your game from the CDN while presenting clean routing paths. You don't need to configure anything - just write your routes normally:
+
+```tsx
+<Router>
+    <Route path="/" component={Home} />
+    <Route path="/game" component={Game} />
+    <Route path="/settings" component={Settings} />
+</Router>
+```
+
+**Runtime asset loading**: If your game loads assets dynamically at runtime (files that Vite can't analyze at build time), use the SDK's CDN helpers:
+
+```typescript
+import { PlaycademyClient } from '@playcademy/sdk'
+
+const client = await PlaycademyClient.init()
+
+// Load dynamic JSON data (e.g., level selected by user)
+const levelData = await client.runtime.cdn.json`levels/level-${levelId}.json`
+
+// Load images dynamically using tagged template literals
+img.src = client.runtime.cdn.url`badges/${badgeType}.png`
+audio.src = client.runtime.cdn.url`sfx/${soundEffect}.wav`
+
+// Or use regular function calls
+const data = await client.runtime.cdn.fetch('data/config.json')
+const blob = await client.runtime.cdn.blob('images/hero.png')
+```
+
+These helpers automatically resolve to the correct CDN path in production and relative paths in local development.
+
 ### Production Build
 
 During `bun run build`, the plugin:
 
 - Generates `playcademy.manifest.json` in `dist/`
+- Generates `.vite/manifest.json` for optimal asset loading
 - Creates deployment zip (if `autoZip: true`)
 - Optimizes build for platform deployment
 
@@ -209,15 +235,9 @@ The plugin generates `dist/playcademy.manifest.json`:
 
 ```json
 {
-    "version": 1,
-    "slug": "my-game",
-    "displayName": "My Game",
-    "description": "An awesome Playcademy game",
-    "entryPoint": "index.html",
-    "bootMode": "iframe",
+    "version": "1",
     "platform": "web",
-    "styles": [],
-    "gameVersion": "1.0.0"
+    "createdAt": "2024-01-01T12:00:00.000Z"
 }
 ```
 

package/dist/config/proxy.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Proxy configuration for backend API
+ */
+import type { ProxyOptions } from 'vite';
+export interface ProxyConfig {
+    '/api'?: string | ProxyOptions;
+}
+/**
+ * Create proxy configuration for backend API
+ * Auto-configures /api proxy to route requests to the backend server
+ */
+export declare function createProxyConfig(existingProxy: Record<string, string | ProxyOptions>, backendPort: number): Record<string, string | ProxyOptions>;

package/dist/config/vite-config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Vite configuration modifications
+ */
+import type { UserConfig } from 'vite';
+/**
+ * Create Vite configuration with Playcademy-specific settings
+ */
+export declare function createViteConfig(userConfig: UserConfig, backendPort: number): UserConfig;

package/dist/hooks/close-bundle.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Vite closeBundle() hook
+ * Runs after all bundles are closed
+ */
+import type { PluginContext } from '../types/internal';
+/**
+ * Handle closeBundle hook - performs final logging
+ */
+export declare function closeBundleHook(context: PluginContext): void;

package/dist/hooks/config-resolved.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Vite configResolved() hook
+ * Runs after Vite config is resolved
+ */
+import type { ResolvedConfig } from 'vite';
+import type { PluginContext } from '../types/internal';
+/**
+ * Handle configResolved hook - stores resolved config
+ */
+export declare function configResolvedHook(resolvedConfig: ResolvedConfig, context: PluginContext): void;

package/dist/hooks/config.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Vite config() hook
+ * Runs before Vite resolves the config
+ */
+import type { UserConfig } from 'vite';
+import type { PluginContext } from '../types';
+/**
+ * Handle config hook - modifies Vite configuration
+ */
+export declare function configHook(userConfig: UserConfig, context: PluginContext): Promise<UserConfig>;

package/dist/hooks/configure-server.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Vite configureServer() hook
+ * Runs when the dev server is created
+ */
+import type { ViteDevServer } from 'vite';
+import type { PluginContext } from '../types/internal';
+/**
+ * Handle configureServer hook - sets up dev servers
+ */
+export declare function configureServerHook(server: ViteDevServer, context: PluginContext): Promise<void>;

package/dist/hooks/write-bundle.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Vite writeBundle() hook
+ * Runs after bundle is written to disk
+ */
+import type { PluginContext } from '../types/internal';
+/**
+ * Handle writeBundle hook - generates manifest and optional zip
+ */
+export declare function writeBundleHook(context: PluginContext): Promise<void>;

package/dist/index.d.ts

@@ -1,11 +1,7 @@
 /**
  * Playcademy Vite Plugin
  *
- * Provides:
- * - Auto-starting sandbox server during development
- * - Hijacking dev server to serve Playcademy loader environment
- * - Build-time manifest generation and optional zip packaging
+ * Entry point - exports plugin and types
  */
-import type { Plugin } from 'vite';
-import type { PlaycademyPluginOptions } from './types';
-export declare function playcademy(options?: PlaycademyPluginOptions): Plugin;
+export { playcademy } from './plugin';
+export type * from './types';