@workadventure/map-starter-kit-core 1.1.3 → 1.1.4

package/README.md

@@ -16,7 +16,83 @@ Core app, HTML pages and static assets for the **WorkAdventure Map Starter Kit**
 npm install @workadventure/map-starter-kit-core
 ```
 
-**Peer / consumer:** The built server expects `express` to be available at runtime. For TypeScript consumers, `@types/express` is used for the exported `Application` type.
+**Peer / consumer:** The built server expects `express` to be available at runtime. For TypeScript consumers, install `@types/express` so the exported `Application` type resolves.
+
+---
+
+## Package exports and usage from another package
+
+This package is built and published as a **single server bundle**. Consumers must use the built output, not the source, to avoid module resolution errors.
+
+### How exports are managed
+
+| Field | Role |
+|--------|------|
+| **`main`** | Entry when a tool doesn’t use `exports`. Should point to `dist/server.js` so the bundle is used, not `src/server.ts`. |
+| **`types`** | Tells TypeScript which declaration file to use for the package entry (`dist/server.d.ts`). |
+| **`exports`** | Modern entry map: `"."` and `"./dist/server.js"` resolve to `dist/server.js` with types `dist/server.d.ts`. |
+| **`files`** | What gets published: `dist`, `public`, `README.md`. Source (`src/`) is not published so consumers never resolve to `.ts` files. |
+
+Recommended in **package.json** for correct consumption:
+
+```json
+{
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.js"
+    },
+    "./dist/server.js": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.js"
+    }
+  },
+  "files": ["dist", "public", "README.md"]
+}
+```
+
+### Using the package in another project
+
+**1. Install the package**
+
+```bash
+npm install @workadventure/map-starter-kit-core
+```
+
+**2. Import the Express app (ESM)**
+
+```ts
+import core from "@workadventure/map-starter-kit-core";
+
+const app = core.default;  // or core.viteNodeApp (same Express Application)
+
+app.listen(3000, () => console.log("Listening on 3000"));
+```
+
+**3. Or use the explicit entry (same result)**
+
+```ts
+import core from "@workadventure/map-starter-kit-core/dist/server.js";
+```
+
+**4. TypeScript**
+
+Types come from `dist/server.d.ts`: the default export is typed as `{ default: Application; viteNodeApp: Application }`. Ensure the consuming project has `express` and `@types/express` so the `Application` type resolves.
+
+**5. CommonJS**
+
+```ts
+const core = require("@workadventure/map-starter-kit-core");
+const app = core.default;
+```
+
+**Important:** Do not import from `@workadventure/map-starter-kit-core/src/server` or rely on `src/` in the package. Only the built `dist/server.js` and its types are the supported contract.
+
+---
 
 ## Usage
 
@@ -25,7 +101,7 @@ npm install @workadventure/map-starter-kit-core
 Use the built Express app in your own server:
 
 ```ts
-import core from "@workadventure/map-starter-kit-core/dist/server.js";
+import core from "@workadventure/map-starter-kit-core";
 
 const app = core.default;  // or core.viteNodeApp
 
@@ -33,7 +109,7 @@ const app = core.default;  // or core.viteNodeApp
 app.listen(3000, () => console.log("Listening on 3000"));
 ```
 
-Types are provided: `core` is typed as `{ default: Application; viteNodeApp: Application }` (see `types/server.d.ts`).
+Types are provided via `dist/server.d.ts`: `core` is typed as `{ default: Application; viteNodeApp: Application }`.
 
 ### Development server (standalone)
 
@@ -61,23 +137,30 @@ npm run build
 map-starter-kit-core/
 ├── src/
 │   ├── server.ts              # Express app entry (CORS, static, routes)
-│   ├── getCoreRoot.ts         # Resolve core package root (cwd vs package dir)
-│   ├── controllers/
-│   │   ├── FrontController.ts # HTML pages (Mustache): /, step1-git, step2-hosting, step3-*, step4-*
-│   │   ├── MapController.ts   # /maps/list – list .tmj maps with properties
-│   │   └── UploaderController.ts  # /uploader/* – configure, status, maps-storage-list, upload
-│   └── views/                 # Mustache HTML templates
-│       ├── index.html
-│       ├── step1-git.html … step4-validated-selfhosted.html
-├── public/                    # Static assets (images, styles, etc.)
+│   ├── utils/
+│   │   └── getCoreRoot.ts     # Resolve core package root (cwd vs package dir)
+│   └── controllers/
+│       ├── FrontController.ts # HTML pages (Mustache): /, step1-git, step2-hosting, step3-*, step4-*
+│       ├── MapController.ts   # /maps/list – list .tmj maps with properties
+│       └── UploaderController.ts  # /uploader/* – configure, status, maps-storage-list, upload
+├── public/                    # Static assets
+│   ├── assets/
+│   │   ├── js/                # Client scripts (e.g. index.js – maps list, Mustache)
+│   │   └── views/            # HTML views (index.html, step1-git.html, …)
+│   ├── images/
+│   └── styles/
 ├── types/
 │   └── server.d.ts            # Module declaration for dist/server.js (copied to dist on build)
-├── dist/                      # Build output (server.js, server.d.ts, assets)
+├── dist/                      # Build output (published)
+│   ├── server.js              # Bundled server entry
+│   └── server.d.ts            # Types for consumers
 ├── vite.config.ts
 ├── tsconfig.json
 └── package.json
 ```
 
+Only `dist`, `public`, and `README.md` are included in the published package (`files`). Source (`src/`) is not published so consumers always get the built bundle.
+
 ## API / Routes
 
 | Method | Path | Description |

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@workadventure/map-starter-kit-core",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Core app, HTML pages and static assets for the WorkAdventure Map Starter Kit. Update this package to get new UI and server features without touching your maps or config.",
-  "main": "src/server.ts",
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build && node -e \"require('fs').copyFileSync('types/server.d.ts','dist/server.d.ts')\""
@@ -46,7 +47,7 @@
       "require": "./dist/server.js"
     }
   },
-  "devDependencies": {
+  "dependencies": {
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/mustache": "^4.2.6",

package/src/server.ts

@@ -1,124 +0,0 @@
-import express from 'express';
-import * as path from "node:path";
-import * as fs from "node:fs";
-import cors from 'cors';
-import { getCoreRoot } from './utils/getCoreRoot.ts';
-import { FrontController } from './controllers/FrontController.ts';
-import { MapController } from './controllers/MapController.ts';
-import { UploaderController } from './controllers/UploaderController.ts';
-
-const app = express();
-
-const corsOptions = {
-    credentials: true, // Allow sending cookies
-    methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
-    allowedHeaders: [
-        'Content-Type',
-        'Authorization',
-        'X-Requested-With',
-        'Accept',
-        'Origin',
-        'Access-Control-Request-Method',
-        'Access-Control-Request-Headers'
-    ],
-    exposedHeaders: ['Content-Length', 'Content-Type'],
-    maxAge: 86400, // Cache the OPTIONS requests for 24 hours
-};
-
-// Apply the CORS middleware
-// The CORS middleware automatically handles the OPTIONS requests (preflight)
-app.use(cors(corsOptions));
-
-// Parse JSON bodies
-app.use(express.json());
-
-// Configure the static assets for Express
-const staticOptions = {
-    maxAge: '1d', // Cache the files for 1 day
-    etag: true, // Enable ETag for cache validation
-    lastModified: true, // Enable Last-Modified header
-};
-
-// Serve dist/assets FIRST with explicit MIME type configuration
-// This ensures compiled JavaScript files from getMapsScripts are served correctly
-// This route must be before express.static('.') to take precedence
-app.use('/assets', express.static(path.join(process.cwd(), 'dist', 'assets'), staticOptions));
-// Serve the public folder from core (project root or package root for easy updates)
-app.use('/public', express.static(path.join(getCoreRoot(), 'public'), staticOptions));
-// Serve the tilesets folder with a longer cache (rarely modified)
-app.use('/tilesets', express.static(path.join(process.cwd(), 'tilesets'), {
-    maxAge: '7d',
-    etag: true,
-    lastModified: true,
-}));
-
-// Middleware to exclude /src from express.static - let Vite handle TypeScript transformation
-// VitePluginNode will automatically add Vite middleware that transforms TypeScript files
-const staticMiddleware = express.static('.', staticOptions);
-
-// Middleware to transform and serve TypeScript files as JavaScript
-// This bundles the file with its dependencies to resolve npm imports
-app.use('/src', async (req, res, next) => {
-    // Only handle .ts and .tsx files - transform them to JavaScript
-    if (req.path.endsWith('.ts') || req.path.endsWith('.tsx')) {
-        try {
-            // req.path includes /src/, so we need to join it correctly
-            const filePath = path.join(process.cwd(), 'src', req.path.startsWith('/') ? req.path.slice(1) : req.path);
-            
-            // Check if file exists
-            if (!fs.existsSync(filePath)) {
-                return res.status(404).send('File not found');
-            }
-            
-            // Use dynamic import to get esbuild (available via Vite)
-            const esbuild = await import('esbuild');
-            
-            // Bundle the TypeScript file with its dependencies
-            // This resolves npm imports like @workadventure/scripting-api-extra
-            const result = await esbuild.build({
-                entryPoints: [filePath],
-                bundle: true,
-                format: 'esm',
-                target: 'esnext',
-                write: false,
-                platform: 'browser',
-                sourcemap: false,
-                // Externalize WorkAdventure global API (available in the browser)
-                external: ['WA'],
-            });
-            
-            res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
-            return res.send(result.outputFiles[0].text);
-        } catch (error) {
-            console.error('Error transforming TypeScript file:', error);
-            return next(error);
-        }
-    }
-    // For non-TypeScript files in /src, pass to next middleware
-    next();
-});
-
-// Serve static files, but skip /src (handled above)
-app.use((req, res, next) => {
-    // Skip /src requests - they are handled by the transformation middleware above
-    if (req.path.startsWith('/src/')) {
-        return next(); // Let the transformation middleware handle it or pass to Vite
-    }
-    // For other files, use express.static
-    staticMiddleware(req, res, next);
-});
-
-const controllers = [
-    new MapController(app),
-    new FrontController(app),
-    new UploaderController(app),
-];
-
-// Verify and log all controllers created
-controllers.forEach(controller => {
-    console.info(`Controller started: ${controller.constructor.name}`);
-});
-
-export default app;
-// Export for VitePluginNode compatibility
-export const viteNodeApp = app;