perf(api-reference): cold start remains network-bound with read-only configuration
What happens?
A read-only API reference has a substantial cold-start cost even with a small public OpenAPI document and the interactive features disabled.
This is distinct from the large-document rendering work tracked in #6910/#3929: the reproduction below uses Swagger Petstore, and most of the wait is downloading and evaluating the base API Reference bundle before the first operation becomes visible.
With @scalar/[email protected], the standalone script transfers about 1.06 MB compressed from jsDelivr in this reproduction. On a fresh Chrome profile with cache disabled, 1 Mbps download throughput, 40 ms latency, and 4x CPU throttling, Find pet by ID. became visible after 12.6–13.1 seconds in two runs. The Scalar script alone took 9.6–9.8 seconds to transfer.
This matters for documentation sites whose API references are mostly read-only. Disabling the client, agent, models, test requests, developer tools, telemetry, and default fonts does not materially reduce the downloaded JavaScript.
How can we reproduce the issue?
Save this as index.html, serve it from any local HTTP server, then load it in a fresh browser profile with the network and CPU throttling above:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Scalar cold-start reproduction</title>
</head>
<body>
<div id="app"></div>
<script src="https://cdn.jsdelivr.net/npm/@scalar/[email protected]"></script>
<script>
Scalar.createApiReference('#app', {
agent: { disabled: true },
hideClientButton: true,
hideDarkModeToggle: true,
hideModels: true,
hideTestRequestButton: true,
showDeveloperTools: 'never',
telemetry: false,
url: 'https://petstore3.swagger.io/api/v3/openapi.json',
withDefaultFonts: false,
})
</script>
</body>
</html>The same base cost is observable in a Docusaurus integration, but the standalone reproduction is included to remove the host framework and any private specification from the test.
What did you expect to happen?
A read-only configuration should have a supported delivery path with a materially smaller initial payload and faster first-operation visibility.
Possible solutions could include:
- a documented read-only/lite entry point;
- code splitting or lazy loading for API client, agent/AI, editor, and other optional features;
- build-time feature entry points that allow bundlers to exclude disabled features;
- a compressed-bundle/cold-start performance budget for a small public specification.
A loading shell can avoid a blank page, but it does not reduce time to usable content, so it is not a substitute for reducing the initial JavaScript cost.
OpenAPI Document
Source: scalar/scalar