Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Preview: Remote Dev Environments Portal is in preview. Features may change as the product evolves.

​
Overview

The live preview panel shows your running application in an iframe, directly alongside your terminal. See changes as you develop without switching browser tabs or managing URLs.

​
How It Works

The portal proxies HTTP requests from the preview panel to your running application inside the workspace container. This uses Qovery’s port-forward capability - no public URLs or ingress configuration needed. Your application needs to be running and listening on a port for the preview to work. Start your dev server from the terminal first, then the preview panel will automatically display your application.
The preview uses a secure proxy connection to your workspace. Traffic stays within your infrastructure and is not exposed publicly until you explicitly publish your application.
The preview panel includes browser-like navigation controls for moving through pages in your application:
ControlDescription
Back arrowNavigate to the previous page in your browsing history within the preview
Forward arrowNavigate forward after going back
Port selectorA dropdown on the left side of the URL bar showing the active port. Switch between ports if your application exposes multiple services.
Path barAn editable path field showing the current URL path. Edit the path and press Enter to navigate directly to a specific route in your application.
The navigation tracks page changes automatically, including single-page application (SPA) route transitions (pushState, replaceState, popstate, and hashchange events).
The path bar and navigation controls may be hidden for some blueprints. Admins can toggle path bar visibility in the blueprint settings.

​
Viewport Switching

Use the viewport icons in the preview panel header to test your application at different screen sizes:
ViewportDescription
DesktopFull-width preview matching the panel width
TabletTablet-width viewport for testing medium screen layouts
MobileMobile-width viewport for testing small screen layouts
Viewport switching resizes the iframe to simulate the selected device width. This is useful for testing responsive CSS breakpoints and ensuring your application looks correct across devices.
Combine viewport switching with your browser’s built-in developer tools for more detailed responsive testing. The viewport switcher gives you quick checks; your browser’s DevTools provide pixel-level control.

​
Auto-Refresh

Toggle auto-refresh in the preview toolbar to automatically reload the preview at a configurable interval. When to use auto-refresh:
  • Your dev server does not support hot module replacement (HMR)
  • You are editing static files that are served directly without a build step
  • You want periodic visual checks without manually clicking refresh
When you don’t need auto-refresh:
  • Your framework supports HMR (Next.js, Vite, Create React App, etc.) - changes appear automatically
  • You prefer to control when the preview reloads
You can adjust the refresh interval to match your workflow. A shorter interval gives more frequent updates; a longer interval reduces unnecessary reloads.

​
Manual Refresh

Click the refresh button in the preview header to reload the preview on demand. Use this when:
  • You want to see the latest state of your application after making changes
  • The preview is showing stale content
  • You need to reset application state (e.g., clear client-side state)

​
Public URL

If your admin has enabled the public URL option for the blueprint, you can toggle between the proxied preview (default) and a public Qovery URL for your application. The public URL exposes your application’s port through Qovery’s standard ingress, making it accessible outside the portal. This is useful for:
  • Sharing your work-in-progress with colleagues who don’t have portal access
  • Testing with external services that need to call back to your application (webhooks, OAuth callbacks)
  • Testing on a real mobile device
Public URLs bypass the portal’s proxy and expose your application directly. Only use this when you specifically need external access. The proxied preview (default) keeps your application private to the portal.

​
Troubleshooting

Make sure your application is running. Open the Terminal tab and check for errors. Your application must be actively listening on a port for the preview to display anything.Try starting your dev server manually:
npm run dev    # or your framework's equivalent
Your application may have crashed or encountered a runtime error. Check the terminal for error output and stack traces.Common fixes:
  • Restart your dev server
  • Check for missing dependencies (npm install)
  • Review recent code changes for syntax errors
The first load may take a few seconds as the port-forward connection is established. Subsequent loads should be faster.If the preview remains slow:
  • Check your application’s startup time in the terminal
  • Large applications or those compiling many assets may take longer on initial load
  • Ensure your workspace has sufficient resources (contact your admin if performance is consistently poor)
If your framework does not support hot module replacement (HMR), changes will not appear automatically.Solutions:
  • Enable auto-refresh in the preview toolbar
  • Click the refresh button manually after making changes
  • Switch to a framework with HMR support if real-time updates are important to your workflow
Viewport switching changes the iframe width to simulate different devices. If your application does not use responsive CSS (media queries, flexible layouts), it may look the same at all viewport sizes.This is an application issue, not a portal issue. Add responsive styles to your application to see viewport switching take effect.

​
Next Steps

Using the Editor

Terminal tabs, AI chat, and the full editor layout.

Publishing Your App

Deploy your application to a production URL.

Git History & Snapshots

Save and restore previous versions of your work.