Development previews
A development preview lets you see an application running on your module's development machine. Use it to check a feature, inspect a page, and iterate with the agent before deploying.
In the module editor, these previews are organised under Pages. A Page saves a preview port and path; it does not create an application or start a server. Module Pages are separate from the project Pages used for documents and agent instructions.
Start a preview
- Start the application in a terminal or with a saved startup command.
- Make it listen on
0.0.0.0, using one of the ports published by the development machine. - Open Pages → New page in the module editor.
- Select the matching port, set the path you want to view, and give the Page a useful name.
- Open the Page to inspect it. Use Open in a new tab if the editor asks you to sign in there or cannot embed the preview.
The default preview ports are 3000, 5173, 8080, 4200, and 8000. Use the ports shown by your machine: a server on a different port will not have a preview route.
For an existing Vite application with a dev script, a development command might be:
npm run dev -- --host 0.0.0.0 --port 5173 --strictPort
The strict port option prevents the server silently moving to another port if 5173 is already in use. Configure the preview hostname in the framework's allowed-host settings where required. The editor's Blank page? help contains framework-specific guidance using the machine's preview details.
Why the network settings matter
The preview gateway reaches your server from outside the machine. A server bound only to localhost or 127.0.0.1 can work in the terminal but remain unreachable through the preview.
The browser accesses the preview over HTTPS. Frameworks using hot reload may need their browser-side WebSocket connection configured for wss on port 443, even though the server itself listens on a port such as 5173. Allow the actual preview hostname rather than disabling host checks broadly.
Preview access
Current protected previews use developer sign-in through the editor. Module application authentication can add another sign-in requirement when enabled. Open the saved Page through the editor to obtain access; copying a preview address alone does not grant somebody else permission to use it.
Older preview routes may have different access behaviour. Do not treat a hard-to-guess hostname as security, and do not expose credentials, private files, or administrative endpoints through a development server.
Use a deployment for an application other people should use independently of your development session.
Test and troubleshoot
The Page view supports reload, opening in a separate tab, and device-size previews. Ask the agent to check the application in the browser as well as running its automated tests.
If the preview is blank or unavailable, check:
- Is the development machine running, and did the server actually start? Read its terminal output.
- Is it listening on
0.0.0.0and the selected published port? - Did it move to a different port because another process was already using that one?
- Does the framework accept the preview hostname, and is hot reload configured for HTTPS?
- Is sign-in required? Open the preview from the editor and follow the sign-in flow.
Deleting a saved Page removes the bookmark, not the server or application files. Stopping the server or development machine makes the preview unavailable, even if the Page remains listed.