Merge pull request #104 from workadventure/new-ui

feat: integrate new ui for map starter kit

Author: moufmouf

.env

@@ -10,5 +10,5 @@ TILESET_OPTIMIZATION_QUALITY_MAX=1.0
 
 # Here you can set your upload strategy. Simply comment the option you don't want to use.
 # Learn more by reading the 'Upload your map' section in the README.
-# UPLOAD_MODE=MAP_STORAGE
-UPLOAD_MODE=GH_PAGES
+UPLOAD_MODE=MAP_STORAGE
+# UPLOAD_MODE=GH_PAGES

.github/workflows/build-and-deploy.yml

@@ -29,7 +29,7 @@ jobs:
         run: npm install
 
       - name: Build project
-        run: npm run build
+        run: npm run buildmap
 
       - name: Extract UPLOAD_MODE from .env
         run: |

README.md

@@ -20,59 +20,169 @@ Uploading a map using [GitHub Pages](https://docs.github.com/pages) will host yo
 
 Uploading a map using the [WA map storage](https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted) will host your project on WA servers. It's a bit more difficult to set up, but it comes with great advantages, like being able to have private repositories.
 
-## 🗂️ Structure
+## 🗂️ Project Structure
 
-We recommend following this file structure:
+```
+map-starter-kit/
+├── 📁 app/                    # Server entry point (loads @workadventure/map-starter-kit-core)
+│   └── app.ts                 # Re-exports the Express app from the core package
+│
+├── 📁 src/                    # Map scripts (Browser/WorkAdventure) ⚠️ REQUIRED
+│   └── main.ts                # Your map scripts go here
+│
+│
+├── 📁 tilesets/               # Map tileset images (PNG)
+│
+├── 📄 *.tmj                   # Map files (office.tmj, conference.tmj, etc.)
+├── 📄 vite.config.ts          # Vite configuration
+└── 📄 package.json            # Dependencies and scripts
+```
+
+The **server** (Express app, controllers, HTML publishing pages, static assets) is provided by the npm package **`@workadventure/map-starter-kit-core`**. Updating this dependency gives you new publishing UI and server features without changing your maps or config.
 
-- *`public/`*: Static files like PDFs or audio files
-- *`src/`*: Script files or design source files
+### Quick Reference
+
+- *`src/`*: **Map scripts** (MUST be here for compilation) ⚠️
 - *`tilesets/`*: All PNG tilesets
+- *`app/`*: **Server entry point** – loads the core package; do not add server logic here
 
 > [!TIP]
 > - If you want to use more than one map file, just add the new map file in the root folder (we recommend creating a copy of *office.tmj* and editing it to avoid any mistakes).
 > - We recommend using **512x512** images for the map thumbnails.
-> - If you are going to create custom websites to embed in the map, please reference the HTML files in the `input` option in *vite.config.js*.
+> - If you are going to create custom websites to embed in the map, please reference the HTML files in the `input` option in *buildmap.vite.config.js*.
+
+### 📁 Server entry point (`app/`)
+
+The `app/` directory contains only the **entry point** that loads the server from **`@workadventure/map-starter-kit-core`**.
+
+- *`app.ts`*: Imports and re-exports the Express app from the core package (for Vite’s server plugin).
+
+The actual server (Express, routes, HTML pages, upload, map storage) lives in the dependency. To get updates to the publishing UI and server behaviour, run `npm update @workadventure/map-starter-kit-core`.
+
+> [!IMPORTANT]
+> Do **not** add server logic or new controllers in `app/`. The server is fully provided by the core package.
+
+### 📁 Map Scripts Development (`src/`) ⚠️
+
+The `src/` directory is where you **MUST** place **all map-related scripts** that will be executed in the browser. See [src/README.md](./src/README.md) for detailed documentation and examples.
+
+- *`main.ts`*: Main map script (referenced in `.tmj` files)
+
+> [!IMPORTANT]
+> **All map scripts MUST be placed in the `src/` directory** to be properly compiled and bundled by Vite. Scripts in this directory are:
+> - Automatically transformed from TypeScript to JavaScript
+> - Bundled with their npm dependencies (like `@workadventure/scripting-api-extra`)
+> - Served with the correct MIME types
+> - Referenced in your `.tmj` map files using paths like `src/main.ts`
+
+> [!WARNING]
+> Do not place map scripts outside the `src/` directory. They will not be compiled correctly and will cause errors in the browser.
 
 ## 📜 Requirements
 
 - Node.js version >= 18
 
-## Installation and testing
-
 ## 🛠️ Installation and Testing
 
-With npm installed (which comes with [Node.js](https://nodejs.org/en/)), run the following command in the root directory of the project:
+### Prerequisites
+
+- **Node.js** version >= 18 ([Download Node.js](https://nodejs.org/en/))
+- **npm** (comes with Node.js)
+
+### 📦 Installation
+
+1. Clone or download this repository
+2. Navigate to the project root directory
+3. Install dependencies:
 
 ```bash
 npm install
 ```
 
-Then, you can test your map by running:
+This will install all required dependencies, including Vite, TypeScript, WorkAdventure packages, and **`@workadventure/map-starter-kit-core`** (server and publishing UI).
+
+### 🚀 Development
+
+#### Start Development Server
+
+Start the Vite development server with hot module replacement:
 
 ```bash
 npm run dev
 ```
 
-You can also test the optimized map as it will be in production by running:
+This will:
+- Start the Vite dev server (usually on `http://localhost:5173`)
+- Enable hot module replacement for instant updates
+- Automatically transform TypeScript files in `src/`
+- Serve your maps and assets
+
+> [!TIP]
+> The development server will automatically open your browser. If not, navigate to the URL shown in the terminal.
+
+#### Test Production Build
+
+To test how your map will behave in production:
 
 ```bash
-npm run build
-npm run prod
+# Build the optimized production version for your map
+npm run buildmap
+
 ```
 
-You can manually [upload your map to the WA Map Storage]([WA Map Storage](https://github.com/workadventure/upload-maps)) by running:
+This will:
+- Compile TypeScript to JavaScript
+- Optimize and bundle all assets
+- Create a production-ready `dist/` folder
+- Start a preview server to test the optimized build
+
+### 📤 Upload Your Map
+
+#### Upload to WA Map Storage
+
+To upload your map to the WorkAdventure Map Storage:
 
 ```bash
 npm run upload
 ```
 
-The three important variables that control the upload feature are:
+This command will:
+1. Build your map (`npm run buildmap`)
+2. Upload it to the configured WA Map Storage
+
+> [!IMPORTANT]
+> Before uploading, you need to configure your upload settings. The upload feature requires three environment variables:
+
+1. **`MAP_STORAGE_URL`** - Your WorkAdventure Map Storage URL
+   - *Local development*: Created in `.env` by the upload command
+   - *CI/CD*: Add as a GitHub secret (optional)
+
+2. **`MAP_STORAGE_API_KEY`** - Your API key for authentication
+   - *Local development*: Created in `.env.secret` by the upload command
+   - *CI/CD*: Add as a GitHub secret (required)
+
+3. **`UPLOAD_DIRECTORY`** - Directory path on the storage server
+   - *Local development*: Created in `.env` by the upload command
+   - *CI/CD*: Add as a GitHub secret (optional)
+
+#### Configure Upload Settings
+
+You can configure these settings through the web interface:
+1. Start the development server (`npm run dev`)
+2. Navigate to the upload configuration page
+3. Fill in your Map Storage credentials
+4. Save and upload your map
+
+For more details, read [the WorkAdventure upload documentation](https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted).
 
-1. `MAP_STORAGE_URL` *(local: created in .env by the upload command / CI: to be added as a Github secret optionally)*
-2. `MAP_STORAGE_API_KEY` *(local: created in .env.secret by the upload command / CI: to be added as a Github secret)*
-3. `UPLOAD_DIRECTORY` *(local: created in .env by the upload command / CI: to be added as a Github secret optionally)*
+### 📋 Available Scripts
 
-Read [the documentation](https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted) to learn more about the upload feature.
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start Vite development server with hot reload |
+| `npm run buildmap` | Build only the map files (without frontend) |
+| `npm run upload` | Build and upload map to WA Map Storage |
+| `npm run upload-only` | Upload map without rebuilding (requires existing build) |
 
 ## 📜 Licenses
 

app/app.ts

@@ -0,0 +1,3 @@
+import { viteNodeApp as theApp } from '@workadventure/map-starter-kit-core/dist/server.js';
+
+export const viteNodeApp = theApp;

vite.config.ts buildmap.vite.config.tsvite.config.ts renamed to buildmap.vite.config.ts

@@ -27,20 +27,11 @@ export default defineConfig({
         sourcemap: true,
         rollupOptions: {
             input: {
-                index: "./index.html",
                 ...getMapsScripts(maps),
             },
         },
     },
-    plugins: [...getMapsOptimizers(maps, optimizerOptions)],
-    server: {
-        host: "localhost",
-        headers: {
-            "Access-Control-Allow-Origin": "*",
-            "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
-            "Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization",
-            "Cache-Control": "no-cache, no-store, must-revalidate",
-        },
-        open: "/",
-    },
+    plugins: [
+        ...getMapsOptimizers(maps, optimizerOptions),
+    ],
 });

conference.tmj

@@ -493,10 +493,10 @@
         {
          "name":"script",
          "type":"string",
-         "value":"src\/main.ts"
+         "value":"src/main.ts"
         }],
  "renderorder":"right-down",
- "tiledversion":"1.10.2",
+ "tiledversion":"1.11.2",
  "tileheight":32,
  "tilesets":[
         {