Start commands by app type

Choose the stack you already have

First complete host preparation. Each recipe describes a browser preview, using your project’s installed tools. Commands below are examples for the named standard script; inspect your package.json and README before using them. Keep the existing framework version.

The JSON snippets belong in paseo.json at the selected project root. Merge the relevant entries into an existing file. The fixed ports shown allow one local instance per port; see multiple workspaces when running several copies.

Vite: React, Vue, Svelte and similar frontends

1. Open the folder with package.json. Install dependencies with its existing lockfile.
2. Check that dev runs Vite. Save this preview service:

{
  "scripts": {
    "preview": {
      "type": "service",
      "command": "npm run dev -- --host 127.0.0.1 --port 5173 --strictPort",
      "port": 5173
    }
  }
}

3. If you use pnpm, the equivalent command is pnpm run dev --host 127.0.0.1 --port 5173 --strictPort. Keep the package manager already used by the project.
4. Add a backend service and a frontend API proxy if needed.
5. Start preview, open it on your paired device, and test a click and a saved source edit.

--strictPort stops Vite from silently switching away from the configured port. These commands also apply to SvelteKit projects whose dev script runs Vite. Vite server options.

Next.js or Astro: one web server

1. Prepare the project’s dependencies, environment and development database using its README.
2. For a Next.js dev script that runs next dev, save:

{
  "scripts": {
    "preview": {
      "type": "service",
      "command": "npm run dev -- --hostname 127.0.0.1 --port 3000",
      "port": 3000
    }
  }
}

3. For Astro, use npm run dev -- --host 127.0.0.1 --port 4321 with port: 4321 instead.
4. Start preview and test a page plus a server/API action. Routes served by this same process need no second backend service. Add one only if you actually have a separate API.
5. For a production-mode check, run the project’s build step first, then configure its documented production start command and port. A development preview does not publish a production deployment.

Keep existing routing and adapters. A pure static export can use the next recipe. References: Next.js CLI and Astro CLI.

A separate Node or Python backend

1. Follow the complete frontend/backend example. Keep its preview service.
2. Name your separate HTTP service backend. For Node, use the existing start script and make its listener read process.env.PASEO_PORT.
3. For an existing FastAPI/ASGI app at backend/main.py exporting app, a backend entry is:

{
  "scripts": {
    "backend": {
      "type": "service",
      "command": "python -m uvicorn main:app --app-dir backend --host 127.0.0.1 --port 8000",
      "port": 8000
    }
  }
}

4. Use your environment’s Python executable if python does not select it. Install requirements in that environment first. Change main:app and the directory to your real module and application.
5. Configure relative browser API requests and the frontend’s server-side proxy. Test a real API action after starting preview.

The JSON above is the backend entry to merge alongside your frontend; it is not a complete preview by itself. Django, Flask, Rails, Laravel and other HTTP backends follow the same service pattern using their own documented start commands and matching ports. Lyre does not infer their database, migration or authentication setup. Uvicorn settings.

Plain HTML or an exported static site

1. Identify the folder that actually contains index.html and the browser assets. If your project generates them, run its existing build/export first.
2. Open that folder as a project, or keep your source root and point a manual command to the output folder.
3. In an empty script draft, review Lyre’s static preview proposal, choose Add to draft and Save. It uses the bundled static server; no frontend package installation is required for already-built files.
4. Start preview, open the app and follow its links on the paired device.
5. Rebuild when source changes affect generated output, then Refresh. Static serving does not provide state-preserving hot reload.

For manual setup, use your installed Lyre host CLI’s preview serve <output-folder> --port 5173 as a preview service with port: 5173. Replace the CLI path using your build’s CLI instructions. The static helper serves supported web assets, excludes private metadata and has no SPA route fallback. Use your framework’s server if refreshing a nested route requires rewriting it to index.html.

Expo or Capacitor: preview the web target

1. For Expo, use a project with web support and its compatible web dependencies installed. Confirm its start script runs expo start.
2. Save this service:

{
  "scripts": {
    "preview": {
      "type": "service",
      "command": "npm run start -- --web --localhost --port 8081",
      "port": 8081
    }
  }
}

3. For Capacitor, use the underlying web app’s command instead: a Vite frontend follows the Vite recipe; already-built web assets follow the static recipe.
4. Start preview in Lyre and open that app on the paired phone. The preview is the web interface inside Lyre.
5. Test the app’s native-specific capabilities separately using its normal native build/device workflow.

A native module without a web implementation will not start working because it is viewed on a phone. Expo Go, a development client, Capacitor native plugins and App Store builds are separate delivery paths. Expo web setup.

Flutter with a web target

1. Install the project’s compatible Flutter SDK, run flutter pub get, and confirm it has a web target. Standard detection expects pubspec.yaml, web/index.html and lib/main.dart.
2. Save this service, adding your actual --target argument if the Dart entry point is different:

{
  "scripts": {
    "preview": {
      "type": "service",
      "command": "flutter run -d web-server --web-hostname 127.0.0.1 --web-port 5173",
      "port": 5173
    }
  }
}

3. Start preview and wait for the terminal’s “is being served at” message. If the viewer opened early, refresh after that message.
4. Use one preview client for this debug session and test an interaction. Paired Flutter viewing and multiple simultaneous debug clients need testing with your build.
5. For a built web version, run flutter build web and serve build/web with the static recipe. Rebuild it after source changes.

A Flutter web preview does not qualify native plugins or promise native hot reload. Flutter web builds.

Docker, databases and larger stacks

Keep your existing Compose or task-runner setup if it already owns several processes. Lyre’s automatic app start selects one frontend and one named backend; it is not a general dependency graph.

1. Prepare Docker, the project’s environment and its development data using its existing instructions.
2. For an app already served by Compose, expose its web entry point on a known host loopback port, for example 127.0.0.1:8080:80. The container’s web server must listen on its container interface.
3. Save one preview service for the existing stack:

{
  "scripts": {
    "preview": {
      "type": "service",
      "command": "docker compose up",
      "port": 8080
    }
  }
}

4. Keep Compose attached: do not add -d to this managed command. Configure dependency order and health checks in Compose, and have the frontend route browser API requests to the backend inside the stack.
5. Start preview and check a real API/database action. After stopping, use docker compose ps to verify the stack’s state; use its normal stop procedure if containers remain. Do not remove volumes to stop the preview.

Alternatively, start your existing database/queue separately and use Lyre’s two services for frontend/API. Do not register a database or worker as the app’s HTTP preview. Container lifecycle, image builds and data management follow your existing tool; verify them for your project. Compose up reference.

Multiple workspaces and operating systems

Fixed ports are simple for one checkout. For several copies, omit port and make the process consume Lyre’s PASEO_PORT. A Node backend can read it directly; a Vite config can use server.port = Number(process.env.PASEO_PORT || 5173) with strictPort: true. The frontend’s server-side proxy can read PASEO_SERVICE_BACKEND_PORT to follow its companion.

Use the syntax of the shell Lyre actually launches. Reading the variable in application code avoids shell-specific expansion. Keep commands relative to the workspace; use package-manager workspace/prefix options or a quoted directory change for nested apps. A new worktree needs the committed project configuration and its own dependencies/environment.