|
| 1 | +# Express API Refactoring Plan |
| 2 | + |
| 3 | +## Motivation |
| 4 | + |
| 5 | +The Vue-Skuilder Express server serves as the **primary backend infrastructure** for the full Vue-Skuilder platform. However, the CLI's studio mode needs to reuse the same API endpoints for course editing functionality. |
| 6 | + |
| 7 | +Currently, the CLI embeds the Express server by copying built files and assets, but this approach fails at runtime because the embedded Express server cannot resolve its Node.js dependencies (like `cookie-parser`, `cors`, etc.) through normal module resolution. |
| 8 | + |
| 9 | +The CLI's `yarn studio` command fails with: |
| 10 | +``` |
| 11 | +Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'cookie-parser' imported from .../node_modules/@vue-skuilder/cli/dist/express-assets/app.js |
| 12 | +``` |
| 13 | + |
| 14 | +This occurs because the embedded Express files expect their dependencies to be available through `node_modules` resolution, but when the CLI is installed via `npx` in an external project, those dependencies aren't available. |
| 15 | + |
| 16 | +**Key Point**: Express's primary role as platform backend infrastructure should remain unchanged. We need to add a secondary programmatic API for CLI studio reuse. |
| 17 | + |
| 18 | +## Requirements |
| 19 | + |
| 20 | +1. **Add Programmatic API**: Add an importable class/module alongside the existing standalone server |
| 21 | +2. **Dependency Resolution**: Ensure Express dependencies are properly available when CLI is used |
| 22 | +3. **Flexible Configuration**: Support both environment-based config (platform) and runtime config (studio) |
| 23 | +4. **Lifecycle Management**: Provide start/stop methods for integration with CLI studio command |
| 24 | +5. **Port Management**: Support dynamic port assignment for concurrent studio sessions |
| 25 | +6. **Primary Use Case Preservation**: Maintain existing Express standalone functionality for platform usage |
| 26 | + |
| 27 | +## Current Architecture Analysis |
| 28 | + |
| 29 | +### Entry Point (`src/app.ts`) |
| 30 | +- **Main Structure**: Classic Express app with immediate execution |
| 31 | +- **Port**: Hardcoded to 3000 |
| 32 | +- **Dependencies**: 11 runtime dependencies including `cookie-parser`, `cors`, `express`, `morgan`, `nano` |
| 33 | +- **Initialization**: Two-phase: server startup + async `init()` function |
| 34 | +- **Environment**: Relies on `src/utils/env.ts` for configuration via environment variables |
| 35 | + |
| 36 | +### Configuration (`src/utils/env.ts`) |
| 37 | +- **Environment Variables**: Requires `COUCHDB_SERVER`, `COUCHDB_PROTOCOL`, `COUCHDB_ADMIN`, `COUCHDB_PASSWORD`, `VERSION`, `NODE_ENV` |
| 38 | +- **Data Layer**: Automatically initializes `@vue-skuilder/db` with CouchDB connection |
| 39 | +- **Dotenv**: Loads from `.env.development` by default |
| 40 | + |
| 41 | +### Key Dependencies (package.json) |
| 42 | +**Runtime (11 deps):** |
| 43 | +- `express` - Web framework |
| 44 | +- `cookie-parser` - Cookie middleware |
| 45 | +- `cors` - CORS middleware |
| 46 | +- `morgan` - HTTP logging |
| 47 | +- `nano` - CouchDB client |
| 48 | +- `@vue-skuilder/common` - Shared types |
| 49 | +- `@vue-skuilder/db` - Database layer |
| 50 | +- `axios`, `ffmpeg-static`, `fs-extra`, `winston`, etc. |
| 51 | + |
| 52 | +## Proposed Solution |
| 53 | + |
| 54 | +### 1. Add Programmatic API Class |
| 55 | + |
| 56 | +**Keep existing `src/app.ts` as-is** for platform usage, and **add** an exportable `SkuilderExpressServer` class: |
| 57 | + |
| 58 | +```typescript |
| 59 | +export class SkuilderExpressServer { |
| 60 | + private app: Express; |
| 61 | + private server: http.Server | null = null; |
| 62 | + private port: number; |
| 63 | + |
| 64 | + constructor(config: ExpressServerConfig) { ... } |
| 65 | + |
| 66 | + async start(): Promise<{ port: number; url: string }> { ... } |
| 67 | + |
| 68 | + async stop(): Promise<void> { ... } |
| 69 | + |
| 70 | + isRunning(): boolean { ... } |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +### 2. Dual Configuration Support |
| 75 | + |
| 76 | +**Add** programmatic configuration interface **alongside** existing environment-based config: |
| 77 | + |
| 78 | +```typescript |
| 79 | +export interface ExpressServerConfig { |
| 80 | + port?: number; // Auto-assign if not provided |
| 81 | + couchdb: { |
| 82 | + protocol: string; |
| 83 | + server: string; |
| 84 | + username: string; |
| 85 | + password: string; |
| 86 | + }; |
| 87 | + version: string; |
| 88 | + nodeEnv?: string; |
| 89 | + cors?: { |
| 90 | + credentials: boolean; |
| 91 | + origin: boolean | string | string[]; |
| 92 | + }; |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +### 3. CLI Integration |
| 97 | + |
| 98 | +Update CLI's studio command to use the new API: |
| 99 | + |
| 100 | +```typescript |
| 101 | +import { SkuilderExpressServer } from '@vue-skuilder/express'; |
| 102 | + |
| 103 | +// In studio command |
| 104 | +const expressServer = new SkuilderExpressServer({ |
| 105 | + couchdb: { |
| 106 | + protocol: 'http', |
| 107 | + server: `localhost:${couchdbPort}`, |
| 108 | + username: 'admin', |
| 109 | + password: 'password' |
| 110 | + }, |
| 111 | + version: VERSION, |
| 112 | + nodeEnv: 'studio' |
| 113 | +}); |
| 114 | + |
| 115 | +const { port, url } = await expressServer.start(); |
| 116 | +console.log(`Express API running at ${url}`); |
| 117 | +``` |
| 118 | + |
| 119 | +### 4. Dependency Management |
| 120 | + |
| 121 | +Add Express as a direct dependency in CLI's `package.json`: |
| 122 | + |
| 123 | +```json |
| 124 | +{ |
| 125 | + "dependencies": { |
| 126 | + "@vue-skuilder/express": "workspace:*", |
| 127 | + // ... other deps |
| 128 | + } |
| 129 | +} |
| 130 | +``` |
| 131 | + |
| 132 | +This ensures all Express dependencies are properly resolved through normal npm dependency tree. |
| 133 | + |
| 134 | +## Entry/Exposure Points |
| 135 | + |
| 136 | +### New Public API (src/index.ts) |
| 137 | +```typescript |
| 138 | +export { SkuilderExpressServer } from './server.js'; |
| 139 | +export type { ExpressServerConfig } from './types.js'; |
| 140 | +export { createExpressApp } from './app.js'; // For advanced users |
| 141 | +``` |
| 142 | + |
| 143 | +### New Files Added |
| 144 | +1. **src/server.ts** - New programmatic server class |
| 145 | +2. **src/types.ts** - Configuration interfaces |
| 146 | +3. **src/index.ts** - Main export file for programmatic usage |
| 147 | + |
| 148 | +### Existing Files (Unchanged) |
| 149 | +- **src/app.ts** - Primary standalone server (platform usage) |
| 150 | +- **src/utils/env.ts** - Environment-based configuration (platform usage) |
| 151 | +- All other existing files maintain current functionality |
| 152 | + |
| 153 | +### Dual Usage Support |
| 154 | +- **Platform usage**: `yarn dev` or `node dist/app.js` (unchanged) |
| 155 | +- **Studio usage**: `import { SkuilderExpressServer } from '@vue-skuilder/express'` |
| 156 | + |
| 157 | +## Build Script Modifications |
| 158 | + |
| 159 | +### Express Package Changes |
| 160 | +```json |
| 161 | +{ |
| 162 | + "main": "dist/index.js", |
| 163 | + "types": "dist/index.d.ts", |
| 164 | + "exports": { |
| 165 | + ".": { |
| 166 | + "types": "./dist/index.d.ts", |
| 167 | + "import": "./dist/index.js" |
| 168 | + }, |
| 169 | + "./app": { |
| 170 | + "types": "./dist/app.d.ts", |
| 171 | + "import": "./dist/app.js" |
| 172 | + } |
| 173 | + } |
| 174 | +} |
| 175 | +``` |
| 176 | + |
| 177 | +### CLI Package Changes |
| 178 | +Remove embedding scripts: |
| 179 | +```json |
| 180 | +{ |
| 181 | + "scripts": { |
| 182 | + "build": "rm -rf dist && tsc && npm run embed:studio-ui-src && npm run embed:templates && npm run embed:standalone-ui" |
| 183 | + } |
| 184 | +} |
| 185 | +``` |
| 186 | + |
| 187 | +Remove these lines: |
| 188 | +- `"build:express": "cd ../express && npm run build"` |
| 189 | +- `"embed:express": "mkdir -p dist/express-assets && cp -r ../express/dist/* dist/express-assets/ && cp -r ../express/assets dist/express-assets/"` |
| 190 | + |
| 191 | +### Dependencies Update |
| 192 | +CLI package.json additions: |
| 193 | +```json |
| 194 | +{ |
| 195 | + "dependencies": { |
| 196 | + "@vue-skuilder/express": "workspace:*" |
| 197 | + } |
| 198 | +} |
| 199 | +``` |
| 200 | + |
| 201 | +## Implementation Steps |
| 202 | + |
| 203 | +1. **Create programmatic API** - Refactor app.ts into class-based architecture |
| 204 | +2. **Add configuration interface** - Replace env vars with config object |
| 205 | +3. **Update CLI integration** - Replace ExpressManager with direct API usage |
| 206 | +4. **Test in monorepo** - Ensure backwards compatibility |
| 207 | +5. **Update build scripts** - Remove embedding, add dependency |
| 208 | +6. **Test with npx** - Verify external project usage works |
| 209 | +7. **Update documentation** - Document new API and migration path |
| 210 | + |
| 211 | +## Benefits |
| 212 | + |
| 213 | +- **Cleaner Architecture**: Express becomes a proper Node.js module |
| 214 | +- **Better Dependency Resolution**: Standard npm dependency tree |
| 215 | +- **Reduced Bundle Size**: No more embedded assets in CLI |
| 216 | +- **Easier Maintenance**: Single source of truth for Express server |
| 217 | +- **Better Testability**: Programmatic API easier to test |
| 218 | +- **Flexible Configuration**: Runtime config vs environment vars |
0 commit comments