develop-and-deploy-web-app

Build, run, and share a simple full-stack web application with a TypeScript Express backend, React frontend, and SQLite database. Use when a user wants a working web app or explicitly asks for a LiteApp / 轻应用 scaffolded in the current workspace, started locally, and exposed through a public URL for demos, testing, or review.

Build a simple full-stack web app in the current workspace, run it locally as its own isolated process, and provide a URL that another person can open from outside the machine.

If the user says "轻应用" or "LiteApp", treat that as an explicit request to use this skill.

Operating Rules

• Create the generated web project under workspaces/web-apps/{userName}/{token}.
• Treat {token} as an 8-character random identifier made only of uppercase letters and digits.
• Ensure every new {token} is globally unique across all generated apps.
• If userName is available in the runtime context, use it directly. If it is not discoverable from the environment or user request, ask the user before scaffolding.
• Do not scaffold the app at the repository root unless the user explicitly overrides the output rule.
• Treat {token} as both the folder name and the URL segment.
• Run each web app in its own isolated Node.js process.
• Use one shared LiteApp host on public port 33333 to route /{token}/... traffic to the correct app process.
• Prefer a two-package layout: client/ for the React app and server/ for the Express API.
• Prefer TypeScript everywhere.
• Prefer Vite for the React frontend.
• Prefer better-sqlite3 for SQLite access unless the workspace already uses another SQLite library.
• Prefer one final HTTP service. In production mode, make Express serve the built frontend and the /api endpoints from the same server process.
• If the user does not specify a product idea, default to a simple todo or notes app with one SQLite-backed entity and a complete happy path.
• Extend an existing app when one already exists. Do not replace working user code without a strong reason.
• Before modifying an existing generated web app, read its .ai.md file first.
• Follow the UI direction in references/ui-style.md when designing the frontend. Capture the visual principles from Huashu Design's web examples without copying its original assets or branded content.
• Make the app work under the subpath /{token}/, not just at /.
• Expose all LiteApps through the shared public port 33333.
• Assign each app process a dedicated internal port in the inclusive range 33334-39999. Start at 33334 and increment until a free port is found.
• Treat the final external URL reported to the user as <web-app-url-prefix>:33333/{token}.
• Maintain machine-readable and human-readable records so current users and apps can be queried without scanning source files manually.
• Keep ../platform_data/web-app-registry.json synchronized relative to the .openclaw root directory. Each record must include name, token, file_path, port, created_at, modified_at, and user_name.
• Prefer the bundled Node scripts in scripts/ for app initialization, internal port allocation, shared-host startup, registry maintenance, shutdown, and doc synchronization instead of re-implementing those flows ad hoc.
• Keep deployment automation local and explicit. Do not add scripts that fetch remote code, manage secrets, alter unrelated system state, or attempt privilege escalation.
• Support restart recovery through registry-driven restore scripts, but do not silently install OS startup hooks or scheduled tasks.

Workflow

1. Inspect the workspace before changing anything.
2. Resolve the output directory as workspaces/web-apps/{userName}/{token} and create it if needed.
3. Initialize the app folder and base app documents with scripts/init-app.js.
4. Decide whether to extend an existing app in that target directory or scaffold a new one.
5. Create a minimal but complete app:
   • React frontend with a small but usable UI
   • Express backend in TypeScript
   • SQLite database with schema initialization
   • At least one CRUD flow
   • Health endpoint
6. Add root-level scripts so the app is easy to install, run, build, start, and re-run behind the shared public port.
7. Scaffold the actual project files with scripts/scaffold-app.js.
8. Sync app documentation with scripts/sync-docs.js.
9. Prefer scripts/deploy-app.js for ordered deployment. It installs dependencies, builds the app, starts it, syncs docs, and updates the registry without race conditions.
10. If deployment steps are run separately, run them in order: install-app.js -> build-app.js -> start-app.js -> sync-docs.js -> update-registry.js.
11. Use status-app.js and restart-app.js for lifecycle checks and controlled restarts.
12. Use restore-apps.js for post-reboot recovery, and bootstrap-host.js to print the command that a host-level startup mechanism should run.
13. Return the required final app summary block together with the local commands and any important caveats.

Implementation Defaults

• Use the structure and package guidance in references/stack.md.
• Use the concrete scaffold commands in references/scaffold.md when building a new app from scratch.
• Use the deployment scripts in scripts/.
• Use the minimal script contracts in references/scripts.md.
• Use the autoload compatibility rules in references/autoload.md.
• Use the frontend style guidance in references/ui-style.md.
• Default local ports:
  • frontend dev server: 5173
  • backend dev server: 3000 or 3001
  • shared public LiteApp host: 33333
  • production app server internal port: one free port in 33334-39999
• In development, use a Vite proxy for /api.
• In production, serve client/dist from Express under the base path and keep API routes under /{token}/api.
• Store the SQLite database in a project-local path such as server/data/app.db.

Platform URL Rules

• Do not stop after scaffolding files. The task is incomplete until the app is actually runnable from the generated folder and a final URL has been produced or a concrete blocker has been confirmed.
• Prefer exposing the production build, not the Vite dev server, so the final URL reflects the real integrated app.
• Compute the final access URL for user-facing output as <web-app-url-prefix>:33333/{token}.
• Keep the external port fixed at 33333.
• Select the internal app port by scanning from 33334 upward and using the first free port up to 39999.
• Ensure frontend asset URLs, router behavior, and API calls all work when mounted beneath that subpath.
• Keep each app isolated in its own process and directory. Do not multiplex multiple apps through one long-running server.
• If a dev-time preview URL is needed, treat it as secondary. The primary deliverable is the final app URL plus its recorded metadata.

Queryability Rules

• Make it easy to answer "which users exist?" and "which apps exist?" without launching app code.
• Maintain a root registry and per-user indices with scripts/update-registry.js.
• Keep one machine-readable app metadata file and one human-readable app notes file in every app directory, managed through scripts/init-app.js and scripts/sync-docs.js.
• Keep .ai.md in every app directory to record user requirements and AI design notes.
• Do not keep config.json inside generated app directories.
• Whenever the app is changed, update the corresponding metadata and notes in the same turn.
• When the user asks to inspect existing apps, answer from the registry files first and only inspect app directories when details are missing or stale.

Delivery Requirements

Always finish with:

• a fixed, explicit final app info block with all four fields present and non-empty: Id: {token} Name: {appName} Description: {appSummary} Url template: <web-app-url-prefix>:33333/{token}

• do not omit any of the four fields above, even if other delivery details are also included

• keep the field names exactly as written above

• if additional sections are included, place this four-field block at the end of the response

• the generated project path

• the app summary

• the main files or folders created or updated

• install and run commands

• the final URL in the form <web-app-url-prefix>:33333/{token}

• the assigned public port 33333 and the internal app port

• the registry and app-doc files that were created or updated

• any limitations, such as the URL depending on the local process remaining alive

Example Requests

• "Build me a simple task tracker and give me a public URL."
• "Create a small React + Express + SQLite app for note taking and run it."
• "Set up a demo web app in this folder, start it, and share an external link."
• "Create a 轻应用 for internal data entry."
• "Build a LiteApp for this workflow and run it locally."