# Browser

Open web pages in a cloud browser from your server, and get back HTML, screenshots, or data.

Hosts: Cloudflare.

```ts [server/browsers/page-html.ts]
import { defineBrowser } from 'vite-hub/browser'

// Returns the HTML of a page after it renders
export default defineBrowser(async (
  input: { url: string },
  { browser },
) => {
  return await browser.content(input.url)
})
```

```ts [server/browsers/headings.ts]
import { defineBrowser } from 'vite-hub/browser'

// Keep one page open for several steps
export default defineBrowser(async (
  input: { url: string },
  { browser },
) => {
  const session = await browser.open()
  await session.page.goto(input.url)
  await session.page.locator('main').waitFor()
  return await session.page.locator('h1').count()
})
```

```ts [server/api/page-html.post.ts]
import { defineEventHandler, readBody } from 'h3'
import { runBrowser } from 'vite-hub/browser'

// Run the page-html file by its name
export default defineEventHandler(async (event) => {
  const input = await readBody<{ url: string }>(event)
  return await runBrowser('page-html', input)
})
```

```ts [server/api/screenshot.get.ts]
import { defineEventHandler } from 'h3'
import {
  runBrowserAction,
} from 'vite-hub/browser'

// One call, no browser file needed
export default defineEventHandler(() => {
  return runBrowserAction(
    'screenshot',
    'https://example.com',
  )
})
```

::::framework{name="Nuxt"}
```ts [nuxt.config.ts]
// Adds the Cloudflare browser setting for you

export default defineNuxtConfig({
  modules: ['vite-hub/nuxt'],
  vitehub: { preset: 'cloudflare', browser: true },
})
```
::::
::::framework{name="Nitro"}
```ts [vite.config.ts]
import { defineConfig } from 'vite'
import { nitro } from 'nitro/vite'
import { vitehub } from 'vite-hub'

// Adds the Cloudflare browser setting for you
export default defineConfig({
  plugins: [
    vitehub({ preset: 'cloudflare', browser: true }),
    nitro(),
  ],
})
```
::::
::::framework{name="Vite"}
```ts [vite.config.ts]
import { defineConfig } from 'vite'
import { vitehub } from 'vite-hub'

// Adds the Cloudflare browser setting for you
export default defineConfig({
  plugins: [
    vitehub({ preset: 'cloudflare', browser: true }),
  ],
})
```
::::

### [One file per task](https://vitehub.dev/docs/browser/server-api#definition-api)

Add a file to `server/browsers`. Run it by its name with `runBrowser()`.

### [Several steps on one page](https://vitehub.dev/docs/browser/server-api#keep-a-page-session-open)

`browser.open()` keeps a page open to follow links, click, and fill in forms. ViteHub closes it.

### [Quick calls without a file](https://vitehub.dev/docs/browser/server-api#browser-actions)

Get HTML, Markdown, links, a screenshot, or a PDF with one function call.

### [No browser setup in your app](https://vitehub.dev/docs/browser/configure#configuration)

`browser: true` adds the Cloudflare binding at build time. Routes import no Cloudflare code.

### [Full control when you need it](https://vitehub.dev/docs/browser/server-api#low-level-sessions)

Use Playwright, or a local Chromium on a Node server that you trust.

### [Check the URLs you open](https://vitehub.dev/docs/browser/limits-and-errors#production-checks)

Check every URL that users send. Treat page content as untrusted.

Use Browser for provider-backed browser actions that need a remote session. Browser Definitions keep provider setup out of application code and make each run explicit.

Check [Hosts](https://vitehub.dev/raw/docs/browser/hosts.md) before choosing a provider.

Browser Definitions currently use Cloudflare Browser Run. Keep credentials and session authority in the host configuration. Do not treat a browser screenshot or page as trusted application data without validation.

Remote pages are untrusted input and may leave the allowed origin or change
between runs. Validate URLs, extracted data, and side effects in application
code.

Prove one complete run, including session cleanup and the provider binding in generated output.

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/browser.md) (this page)
- [Get started](https://vitehub.dev/raw/docs/browser/get-started.md)
- [Configure](https://vitehub.dev/raw/docs/browser/configure.md)
- [Server API](https://vitehub.dev/raw/docs/browser/server-api.md)
- [Agent capability](https://vitehub.dev/raw/docs/browser/agent-capability.md)
- [Hosts](https://vitehub.dev/raw/docs/browser/hosts.md)
- [Limits and errors](https://vitehub.dev/raw/docs/browser/limits-and-errors.md)

Next: [BROWSER_R0001](https://vitehub.dev/raw/docs/browser/diagnostics/browser_r0001.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
