Localhost Captures

Overview#

Rollberry fully supports capturing pages served from localhost and other local addresses. This makes it easy to capture your application during development without deploying to a staging server first.

rollberry capture http://localhost:3000

How localhost capture works#

When Rollberry detects a localhost or 127.0.0.1 URL, it enables automatic retry logic. Local development servers may take a moment to become available, especially if you start the server and the capture command at the same time. Rollberry will retry the connection several times before giving up, giving your server time to start.

The retry behavior works as follows:

1. Rollberry attempts to connect to the local URL.
2. If the connection is refused, it waits briefly and retries.
3. This continues for up to the configured timeout (default: 30,000ms / 30 seconds).
4. Once the server responds, capture proceeds normally.

This means you can start your dev server and Rollberry at the same time without worrying about race conditions.

Common framework configurations#

Here are typical commands for capturing pages from popular development frameworks:

Next.js:

# Start the dev server
npm run dev
 
# Capture — Next.js defaults to port 3000
rollberry capture http://localhost:3000 --wait-for ms:2000

Vite (React, Vue, Svelte):

# Start Vite dev server
npm run dev
 
# Capture — Vite defaults to port 5173
rollberry capture http://localhost:5173

Astro:

# Start Astro dev server
npm run dev
 
# Capture — Astro defaults to port 4321
rollberry capture http://localhost:4321

Starting server and capture together#

You can use shell scripting to start your development server and capture in a single command:

#!/bin/bash
# dev-capture.sh
 
# Start the dev server in the background
npm run dev &
DEV_PID=$!
 
# Run the capture (Rollberry will wait up to 30s for the server)
rollberry capture http://localhost:3000 \
  --wait-for ms:2000 \
  --duration 8 \
  --out ./dev-capture.mp4
 
# Stop the dev server
kill $DEV_PID

Custom ports and addresses#

If your server runs on a non-default port, simply specify the full URL:

# Custom port
rollberry capture http://localhost:8080
 
# Explicit IPv4 loopback
rollberry capture http://127.0.0.1:3000
 
# IPv6 loopback
rollberry capture http://[::1]:3000

Handling slow-starting servers#

Some servers take longer to start, especially in development mode with hot module replacement (HMR) initialization. If Rollberry times out before your server is ready, increase the timeout:

# Extend timeout to 60 seconds
rollberry capture http://localhost:3000 --timeout 60000

You can also add an explicit wait time after the page loads to ensure all client-side hydration and data fetching is complete:

# Wait 5 seconds after page load before capturing
rollberry capture http://localhost:3000 --wait-for ms:5000

Waiting for specific content#

If your local app loads data asynchronously, use --wait-for selector:<css> to ensure the content is visible before the scroll capture begins:

# Wait for the main content area to render
rollberry capture http://localhost:3000 \
  --wait-for "selector:.main-content"
 
# Wait for a data table to populate
rollberry capture http://localhost:3000/dashboard \
  --wait-for "selector:table tbody tr"

This is more reliable than a fixed wait time because it adapts to however long the data actually takes to load.