darshana

Crawl any web app and generate a labeled PDF, HTML viewer, or image set for design review.

Darśana — Sanskrit for "the act of seeing clearly."

Try it now

npx @opendatalabs/darshana --url https://vana.org --public --max-pages 10

Output lands in ./darshana-output/ — a PDF and a self-contained HTML viewer with sidebar nav, filters, and keyboard navigation.

For a private app, darshana opens a browser so you can log in, then saves the session:

npx @opendatalabs/darshana --url https://app.vana.org
# A browser opens → log in → press Enter → capture begins

Install

npm install -g @opendatalabs/darshana

Chromium is installed automatically. Or skip the install entirely and use npx @opendatalabs/darshana.

Linux only: if Chromium fails to launch, you may be missing system libraries. Fix with:

sudo npx playwright install chromium --with-deps

CLI reference

darshana --url <url> [options]         # zero-config
darshana --config <path> [options]     # file-based (CLI args override config)

--url <url>              Base URL to crawl
--config <path>          Path to a JSON config file
--title <string>         Review title (default: hostname)
--start <path>           Starting path (default: /)
--public                 Skip auth — use for public sites
--auth-storage <path>    Where to save/load the session (default: ./darshana-output/auth.json)
--auth-script <path>     Headless login script (see Auth below)
--themes <list>          Comma-separated: system,dark,light (default: system)
--viewports <list>       Comma-separated: desktop,mobile (default: desktop)
--max-depth <n>          BFS depth limit (default: 5)
--max-pages <n>          Page cap (default: 100)
--delay <ms>             Wait after page load before capture (default: 400)
--outputs <list>         Comma-separated: pdf,html,images (default: pdf,html)
--output-dir <path>      Output directory (default: ./darshana-output)
--include <regex>        Crawl only paths matching this pattern (repeatable)
--exclude <regex>        Skip paths matching this pattern (repeatable)
--dry-run                Discover URLs without capturing
--route <path>           Capture a single route only
--auth-only              Save auth session and exit

Config file

For complex projects, a JSON config gives you per-route sampling rules and capture overrides. CLI args always override config file values.

{
  "title": "My App",
  "url": "https://myapp.example.com",
  "start": "/dashboard",
  "public": false,
  "authStorage": "./auth.json",
  "authScript": "./auth.mjs",
  "crawl": {
    "include": ["^/dashboard"],
    "exclude": ["logout", "delete"],
    "maxDepth": 3,
    "maxPages": 50,
    "routes": [
      { "pattern": "/dashboard/records/:id", "sample": 1, "follow": false },
      { "pattern": "/dashboard/runs/:id",    "sample": 2, "follow": false },
      { "pattern": "/dashboard/**",          "follow": true }
    ]
  },
  "capture": {
    "themes": ["dark", "light"],
    "viewports": ["desktop", "mobile"],
    "delay": 400,
    "overrides": [
      { "route": "/dashboard/records/", "delay": 1000 }
    ]
  },
  "outputs": ["pdf", "html"],
  "outputDir": "./output"
}

Routes DSL

Without routes, darshana visits every discovered URL. For apps with millions of records or runs, use routes to sample:

| Field | Type | Default | Description | |---|---|---|---| | pattern | string | required | Express-style path using :param and /** | | sample | number | unlimited | Max pages to capture matching this pattern | | follow | boolean | true | Whether to BFS-follow links on matching pages |

First match wins.

Config reference

Top-level

| Field | Type | Default | Description | |---|---|---|---| | title | string | hostname | Cover page and HTML header title | | url | string | required | Base URL | | start | string | / | Path to start crawling from | | public | boolean | false | Skip auth | | authStorage | string | ./auth.json | Saved session path | | authScript | string | — | Headless login script | | outputs | string[] | ["pdf","html"] | Any of "pdf", "html", "images" | | outputDir | string | ./darshana-output | Output directory |

crawl

| Field | Type | Default | Description | |---|---|---|---| | include | string[] | [] | Regex patterns — pathname must match all | | exclude | string[] | [] | Regex patterns — pathname must not match any | | maxDepth | number | 5 | Max BFS depth | | maxPages | number | 100 | Hard page cap | | extraRoutes | string[] | [] | Extra paths to capture (not crawled for links) | | routes | Route[] | [] | Per-pattern sampling rules |

capture

| Field | Type | Default | Description | |---|---|---|---| | themes | string[] | ["system"] | "system" (no injection), "dark", "light" | | viewports | string[] | ["desktop"] | "desktop" (1440×900) or "mobile" (390×844) | | fullPage | boolean | true | Capture full scrollable height | | delay | number | 400 | ms to wait before capture | | waitFor | string | — | CSS selector (prefix $) or JS expression to await | | overrides | Override[] | [] | Per-route overrides for any capture field | | contextOptions | object | {} | Passed to browser.newContext() | | launchOptions | object | {} | Passed to chromium.launch() | | playwrightOptions | object | {} | Passed to page.screenshot() | | routeOptions | object | — | { blockPatterns: string[] } — abort matching requests |

Auth

Headed handover (default): darshana opens a Chromium window, you log in, press Enter. The session is saved to authStorage and reused for 12 hours.

Headless auth script: export a default function that receives a Browser and returns the path to a saved storageState:

// auth.mjs
export default async function login(browser) {
  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto(process.env.APP_URL + '/login');
  await page.fill('#password', process.env.APP_PASSWORD);
  await page.click('button[type="submit"]');
  await page.waitForURL(/\/dashboard/);
  await context.storageState({ path: './auth.json' });
  await context.close();
  return './auth.json';
}

See examples/auth-example.mjs for a full example.

Outputs

• pdf — one page per capture, labeled header, cover page
• html — self-contained file with sidebar nav, theme/viewport filters, keyboard navigation (↑↓), viewport-correct image sizing
• images — <outputDir>/images/<viewport>/NNN-slug-theme.png

License

MIT