@workadventure/map-starter-kit-core 1.1.0 → 1.1.2

package/README.md

@@ -0,0 +1,165 @@
+# @workadventure/map-starter-kit-core
+
+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.
+
+## Features
+
+- **Web UI** – Step-by-step wizard (Git, hosting, steps, validation) for setting up and validating your map project
+- **Map listing** – Discovers `.tmj` maps on disk with properties (name, description, image, copyright, size, last modified)
+- **Uploader** – Configure and run map uploads to [map-storage](https://github.com/workadventure/map-storage); list maps from map-storage for self-hosted flows
+- **Static assets** – Serves public assets, tilesets, and compiled JS; transforms and serves TypeScript under `/src` (esbuild) for browser scripts
+- **Express app** – CORS, JSON body parsing, cache headers; can be mounted in another app or run standalone via Vite
+
+## Installation
+
+```bash
+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.
+
+## Usage
+
+### As a dependency (programmatic)
+
+Use the built Express app in your own server:
+
+```ts
+import core from "@workadventure/map-starter-kit-core/dist/server.js";
+
+const app = core.default;  // or core.viteNodeApp
+
+// Mount or start your server
+app.listen(3000, () => console.log("Listening on 3000"));
+```
+
+Types are provided: `core` is typed as `{ default: Application; viteNodeApp: Application }` (see `types/server.d.ts`).
+
+### Development server (standalone)
+
+From the **map-starter-kit** repo (or a project that uses this package as the core):
+
+```bash
+npm run dev
+```
+
+Runs the Vite dev server with vite-plugin-node (Express). Opens the app at the configured host (e.g. `http://localhost:5173/`).
+
+### Build for production
+
+```bash
+npm run build
+```
+
+- Runs `tsc` (type-check only; `noEmit: true` in tsconfig)
+- Builds the server bundle with Vite into `dist/server.js`
+- Copies `types/server.d.ts` to `dist/server.d.ts` for published types
+
+## Project structure
+
+```
+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.)
+├── types/
+│   └── server.d.ts            # Module declaration for dist/server.js (copied to dist on build)
+├── dist/                      # Build output (server.js, server.d.ts, assets)
+├── vite.config.ts
+├── tsconfig.json
+└── package.json
+```
+
+## API / Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| **Front (HTML)** | | |
+| GET | `/` | Home (index) |
+| GET | `/step1-git` | Step 1 – Git |
+| GET | `/step2-hosting` | Step 2 – Hosting |
+| GET | `/step3-steps` | Step 3 – Steps |
+| GET | `/step3-steps-selfhosted` | Step 3 – Self-hosted |
+| GET | `/step4-validated` | Step 4 – Validated |
+| GET | `/step4-validated-selfhosted` | Step 4 – Validated (self-hosted) |
+| **Maps** | | |
+| GET | `/maps/list` | List `.tmj` maps with properties (path, mapName, mapImage, size, lastModified, etc.) |
+| **Uploader** | | |
+| POST | `/uploader/configure` | Configure MAP_STORAGE (body: `mapStorageUrl`, `mapStorageApiKey`, `uploadDirectory`) |
+| GET | `/uploader/status` | Current config status (e.g. presence of `.env.secret`) |
+| GET | `/uploader/maps-storage-list` | List maps from map-storage (for self-hosted step 4) |
+| POST | `/uploader/upload` | Run the upload (uses config from `.env.secret`) |
+
+Static and special paths:
+
+- `/public/*` – Static files from core’s `public/`
+- `/assets/*` – From project’s `dist/assets/`
+- `/tilesets/*` – From project’s `tilesets/`
+- `/src/*.ts` – Served as compiled JS (esbuild), e.g. for browser scripts using WorkAdventure APIs
+
+## Configuration
+
+### Uploader (MAP_STORAGE)
+
+Configure via **POST `/uploader/configure`** with:
+
+- `mapStorageUrl` – map-storage base URL
+- `mapStorageApiKey` – API key for map-storage
+- `uploadDirectory` – Local directory to upload from
+
+This writes (or updates) a secret file (e.g. `.env.secret` or `src/.env.secret` depending on route) used by the upload and maps-storage-list endpoints. Do not commit this file.
+
+### Core root
+
+`getCoreRoot()` resolves the root of the core package:
+
+- When run from the **project root** (e.g. map-starter-kit): `process.cwd()`
+- When run from **packages/map-starter-kit-core** or **node_modules**: the package directory
+
+So templates and `public` are always loaded from the core package, while maps, `.env`, and `tilesets` stay in the project root.
+
+## Scripts
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `dev` | `vite` | Start dev server (Express via vite-plugin-node) |
+| `build` | `tsc && vite build && node -e "…"` | Type-check, build server to `dist/`, copy `server.d.ts` |
+
+## Releasing
+
+Releases are automated with **semantic-release** and **GitHub Actions**:
+
+- **Workflow:** `.github/workflows/release.yml`
+- **Trigger:** Push to `main` or `master`
+- **Conventions:** [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `BREAKING CHANGE:`) determine the next version; a release is published only when there are relevant commits.
+- **Artifacts:** GitHub Release + **npm** publish of `@workadventure/map-starter-kit-core`.
+
+**npm auth (after classic token deprecation):**
+
+- **Recommended:** [Trusted Publishing (OIDC)](https://docs.npmjs.com/trusted-publishers) for this repo and workflow (no long-lived token).
+- **Alternative:** Create a **granular access token** on [npm](https://www.npmjs.com/settings/~/tokens), then set the **NPM_TOKEN** secret in the repo.
+
+## Tech stack
+
+- **Runtime:** Node.js, Express 5
+- **Build:** TypeScript 5, Vite 7, vite-plugin-node
+- **Templates:** Mustache
+- **Release:** semantic-release
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- **Repository:** [github.com/workadventure/map-starter-kit-core](https://github.com/workadventure/map-starter-kit-core)
+- **Issues:** [github.com/workadventure/map-starter-kit-core/issues](https://github.com/workadventure/map-starter-kit-core/issues)
+- **npm:** [@workadventure/map-starter-kit-core](https://www.npmjs.com/package/@workadventure/map-starter-kit-core)

package/dist/assets/js/index.js

@@ -0,0 +1,164 @@
+// Function to retrieve the list of maps from the API
+async function getMapsList() {
+    try {
+        const response = await fetch('/maps/list');
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        const maps = await response.json();
+        return maps;
+    } catch (error) {
+        console.error('Error fetching maps list:', error);
+        return [];
+    }
+}
+
+// Function to get the list
+async function getImagesList() {
+    try {
+        const response = await fetch('/images/list');
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        const images = await response.json();
+        return images;
+    } catch (error) {
+        console.error('Error fetching images list:', error);
+        return [];
+    }
+}
+
+// Function to create a background image fade for "bg" element
+async function createBackgroundImageFade(images = null) {
+    // Get the list of images
+    if (images === null) {
+        const maps = await getMapsList();
+        images = maps.map(map => {
+            if (map.mapImage) {
+                return map.mapImage.startsWith('http') ? map.mapImage : `/${map.mapImage}`;
+            }
+            return null;
+        }).filter(img => img !== null);
+        if (images.length === 0) {
+            return;
+        }
+    }
+
+    // Get the "bg" element
+    const bgElement = document.querySelector('.bg');
+    if (!bgElement || images.length === 0) return;
+
+    // Create divs for each image with fade animation
+    bgElement.innerHTML = '';
+    images.forEach((imageUrl, index) => {
+        const imgDiv = document.createElement('div');
+        imgDiv.className = 'bg-image' + (index === 0 ? ' active' : '');
+        imgDiv.style.backgroundImage = `url('${imageUrl}')`;
+        bgElement.appendChild(imgDiv);
+    });
+
+    // Automatic fade between images
+    let currentIndex = 0;
+    setInterval(() => {
+        const imageElements = bgElement.querySelectorAll('.bg-image');
+        if (imageElements.length === 0) return;
+
+        // Remove the active class from the current image
+        imageElements[currentIndex].classList.remove('active');
+
+        // Move to the next image
+        currentIndex = (currentIndex + 1) % imageElements.length;
+
+        // Add the active class to the new image
+        imageElements[currentIndex].classList.add('active');
+    }, 5000); // Change image every 5 seconds
+}
+
+// Mustache template for a map card (rendered in loadTMJ)
+const CARD_TEMPLATE = `
+    <div class="map-cover" style="background-image: url('{{mapImageUrl}}');"></div>
+    <div class="map-date">
+        Last edit: {{lastModifiedFormatted}}
+    </div>
+    <div class="map-name">
+        {{mapName}}
+    </div>
+    <div class="map-detail">
+        <div class="map-file">
+            <strong>{{filename}}</strong>.tmj
+        </div>
+        <div class="map-weight">
+            <strong>{{size}}</strong>
+            <span style="opacity: .5">Mo</span>
+        </div>
+    </div>
+    <div class="map-desc">
+        {{mapDescription}}
+    </div>
+    <div class="map-testurl">
+        <a href="#" class="btn" data-map-path="{{path}}">Test my map</a>
+    </div>
+`;
+
+// Load maps from API and render map cards with Mustache
+async function loadTMJ() {
+    try {
+        const Mustache = (await import('https://cdn.jsdelivr.net/npm/mustache@4.2.0/+esm')).default;
+        const maps = await getMapsList();
+
+        const mapImages = maps
+            .map((map) => {
+                if (map.mapImage) {
+                    return map.mapImage.startsWith('http') ? map.mapImage : `/${map.mapImage}`;
+                }
+                return null;
+            })
+            .filter((img) => img !== null);
+
+        if (mapImages.length > 0) {
+            await createBackgroundImageFade(mapImages);
+        }
+
+        const defaultPlaceholder = 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="1620" height="1024"><rect fill="%231b2a41" width="100%" height="100%"/></svg>';
+        const mapsData = maps.map((map) => {
+            const mapImageUrl = map.mapImage
+                ? (map.mapImage.startsWith('http') ? map.mapImage : `/${map.mapImage}`)
+                : (mapImages.length > 0 ? mapImages[0] : defaultPlaceholder);
+            return {
+                ...map,
+                mapImageUrl,
+                mapDescription: map.mapDescription || 'No description available',
+            };
+        });
+
+        const mainElement = document.querySelector('main');
+        if (!mainElement) return;
+
+        mainElement.innerHTML = '';
+        mapsData.forEach((map) => {
+            const section = document.createElement('section');
+            section.className = 'card-map';
+            section.innerHTML = Mustache.render(CARD_TEMPLATE, map);
+
+            const testBtn = section.querySelector('.map-testurl a');
+            if (testBtn) {
+                testBtn.addEventListener('click', (e) => {
+                    e.preventDefault();
+                    const host = window.location.host;
+                    let path = window.location.pathname;
+                    if (path.endsWith('index.html')) {
+                        path = path.slice(0, -'index.html'.length);
+                    }
+                    const instanceId = Math.random().toString(36).substring(2, 15);
+                    const url = `https://play.workadventu.re/_/${instanceId}/${host}${path}${map.path}`;
+                    window.open(url, '_blank');
+                });
+            }
+            mainElement.appendChild(section);
+        });
+    } catch (error) {
+        console.error('Error loading maps:', error);
+    }
+}
+
+export { getMapsList, getImagesList, createBackgroundImageFade, loadTMJ };

package/dist/assets/views/index.html

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="robots" content="noindex">
+    <meta name="title" content="WorkAdventure Starter Kit">
+
+    <link href="public/styles/styles.css" rel="stylesheet">
+
+    <title>WorkAdventure build your map</title>
+    <link rel="icon" href="public/images/favicon.svg" type="image/svg+xml">
+    <script type="module">
+        document.addEventListener("DOMContentLoaded", () => {
+            import('/public/assets/js/index.js').then((module) => {
+                module.loadTMJ();
+            });
+        });
+    </script>
+</head>
+
+<body>
+<div class="content">
+    <header>
+        <div class="logo">
+            <a href="https://workadventu.re/" target="_blank" title="Workadventure">
+                <img src="public/images/logo.svg" alt="Workadventure logo" height="36" />
+            </a>
+        </div>
+        <div style="flex-grow: 1;"></div>
+        <div class="socials">
+            <a href="https://discord.gg/G6Xh9ZM9aR" target="_blank" title="discord">
+                <img src="/public/images/brand-discord.svg" alt="discord">
+            </a>
+            <a href="https://github.com/thecodingmachine/workadventure" target="_blank" title="github">
+                <img src="/public/images/brand-github.svg" alt="github">
+            </a>
+            <a href="https://www.youtube.com/channel/UCXJ9igV-kb9gw1ftR33y5tA" target="_blank" title="youtube">
+                <img src="/public/images/brand-youtube.svg" alt="youtube">
+            </a>
+            <a href="https://twitter.com/Workadventure_" target="_blank" title="twitter">
+                <img src="/public/images/brand-x.svg" alt="X">
+            </a>
+            <a href="https://www.linkedin.com/company/workadventu-re" target="_blank" title="linkedin">
+                <img src="/public/images/brand-linkedin.svg" alt="linkedin">
+            </a>
+        </div>
+        <div class="btn-header-wrapper">
+            <a href="https://discord.gg/G6Xh9ZM9aR" target="_blank" class="btn btn-light">Talk to the community</a>
+            <a href="https://docs.workadventu.re/map-building/" target="_blank" class="btn">Documentation</a>
+        </div>
+    </header>
+    <main>
+        <!-- Map cards are injected here by index.js -->
+    </main>
+    <div class="button-wrapper">
+        <div style="flex-grow: 1;">
+        </div>
+        <div>
+            <a href="step1-git">
+                Publish
+            </a>
+        </div>
+    </div>
+</div>
+<div class="bg"></div>
+</body>
+
+</html>

package/dist/assets/views/step1-git.html

@@ -0,0 +1,154 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="robots" content="noindex">
+    <meta name="title" content="WorkAdventure Starter Kit">
+
+    <link href="public/styles/styles.css" rel="stylesheet">
+
+    <title>WorkAdventure build your map</title>
+    <link rel="icon" href="public/images/favicon.svg" type="image/svg+xml">
+    <script type="module">
+        document.addEventListener("DOMContentLoaded", (event) => {
+            // Load index.js to have access to getMapsList
+            import('/public/assets/js/index.js').then((module) => {
+                module.createBackgroundImageFade();
+            });
+        });
+    </script>
+</head>
+
+<body>
+<div class="content">
+    <header>
+        <div class="logo">
+            <a href="https://workadventu.re/" target="_blank" title="Workadventure">
+                <img src="public/images/logo.svg" alt="Workadventure logo" height="36" />
+            </a>
+        </div>
+        <div style="flex-grow: 1;"></div>
+        <div class="socials">
+            <a href="https://discord.gg/G6Xh9ZM9aR" target="_blank" title="discord">
+                <img src="/public/images/brand-discord.svg" alt="discord">
+            </a>
+            <a href="https://github.com/thecodingmachine/workadventure" target="_blank" title="github">
+                <img src="/public/images/brand-github.svg" alt="github">
+            </a>
+            <a href="https://www.youtube.com/channel/UCXJ9igV-kb9gw1ftR33y5tA" target="_blank" title="youtube">
+                <img src="/public/images/brand-youtube.svg" alt="youtube">
+            </a>
+            <a href="https://twitter.com/Workadventure_" target="_blank" title="twitter">
+                <img src="/public/images/brand-x.svg" alt="X">
+            </a>
+            <a href="https://www.linkedin.com/company/workadventu-re" target="_blank" title="linkedin">
+                <img src="/public/images/brand-linkedin.svg" alt="linkedin">
+            </a>
+        </div>
+        <div class="btn-header-wrapper">
+            <a href="https://discord.gg/G6Xh9ZM9aR" target="_blank" class="btn btn-light">Talk to the community</a>
+            <a href="https://docs.workadventu.re/map-building/" target="_blank" class="btn">Documentation</a>
+        </div>
+    </header>
+    <main>
+        <section class="form-center">
+            <h1>
+                How do you want to publish your map?
+            </h1>
+            <div class="sub-heading">
+                Choose the workflow that best fits your team and your way of working.
+            </div>
+            <div class="radio-wrapper">
+                <label class="radio-card">
+                    <input name="advanced" class="radio" type="radio">
+                    <div class="card-details">
+                        <svg width="39" height="39" viewBox="0 0 39 39" fill="none" xmlns="http://www.w3.org/2000/svg">
+                            <path d="M8.125 19.5L16.25 27.625L32.5 11.375" stroke="#4156F6" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+                        </svg>
+
+                        <h2>
+                            Advanced publishing
+                        </h2>
+                        <div>
+                            <strong>Designed for teams using Git and file versioning.</strong>
+                            Full control over your files and collaboration workflow.
+                        </div>
+                    </div>
+                </label>
+                <label class="radio-card">
+                    <input name="advanced" class="radio" type="radio" checked>
+                    <div class="card-details">
+                        <svg width="39" height="39" viewBox="0 0 39 39" fill="none" xmlns="http://www.w3.org/2000/svg">
+                            <path d="M8.125 19.5L16.25 27.625L32.5 11.375" stroke="#4156F6" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+                        </svg>
+
+                        <h2>
+                            Recommended publishing
+                        </h2>
+                        <div>
+                            <strong>The easiest and fastest way to publish your map.</strong>
+                            No technical setup required. Ideal for getting started quickly.
+                        </div>
+                    </div>
+                </label>
+            </div>
+
+        </section>
+    </main>
+    <div class="button-wrapper">
+        <div>
+            <a href="/" class="btn btn-ghost">
+                Previous
+            </a>
+        </div>
+        <div style="flex-grow: 1;">
+        </div>
+        <div>
+            <a href="step2-hosting" class="btn btn-secondary">
+                Start configuration
+            </a>
+        </div>
+    </div>
+</div>
+<div class="bg"></div>
+<script>
+    // Get radio buttons by finding the label containing "Advanced publishing"
+    const radioButtons = document.querySelectorAll('input[name="advanced"]');
+    const startConfigButton = document.querySelector('a[href="step2-hosting"]');
+    const docUrl = "https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted";
+
+    // Find Advanced publishing radio button by checking parent label text
+    let advancedPublishingRadio = null;
+    radioButtons.forEach(radio => {
+        const label = radio.closest('label');
+        if (label && label.textContent.includes('Advanced publishing')) {
+            advancedPublishingRadio = radio;
+        }
+    });
+
+    // Function to update button href based on selection
+    function updateButtonHref() {
+        // Check if Advanced publishing is selected
+        if (advancedPublishingRadio && advancedPublishingRadio.checked) {
+            startConfigButton.href = docUrl;
+            startConfigButton.target = "_blank";
+        } else {
+            startConfigButton.href = "step2-hosting";
+            startConfigButton.removeAttribute("target");
+        }
+    }
+
+    // Add event listeners to all radio buttons
+    radioButtons.forEach(radio => {
+        radio.addEventListener('change', updateButtonHref);
+    });
+
+    // Initialize on page load
+    updateButtonHref();
+</script>
+</body>
+
+</html>