@scalar/client-side-rendering 0.3.9 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @scalar/client-side-rendering
 
+## 0.4.0
+
+### Minor Changes
+
+- [#9981](https://github.com/scalar/scalar/pull/9981): Load the modern ESM build of the API Reference by default
+
+  The generated HTML now loads the code-split ESM build (`.../@scalar/api-reference/esm.js`, added in #9871) as a `<script type="module">` by default, instead of the monolithic UMD bundle. Because it is code-split, less JavaScript blocks the first render.
+
+  To keep the classic UMD bundle (loaded via `<script src>` and the `window.Scalar` global), set `cdn` to a UMD URL — for example to pin a version — or pass `bundle: false`. You can also pass `bundle: 'https://.../esm.js'` to load a specific ESM build.
+
+  When a `nonce` is set (a strict, nonce-based CSP) the UMD bundle is used automatically, because the ESM build's `import`-loaded chunks cannot be nonced. Pass `bundle: true` to force the ESM build if your CSP uses `'strict-dynamic'`.
+
+## 0.3.10
+
 ## 0.3.9
 
 ### Patch Changes

package/README.md

@@ -39,6 +39,27 @@ const html = renderApiReference({
 })
 ```
 
+### Choosing the bundle
+
+By default the generated HTML loads the modern, code-split ESM build
+(`.../@scalar/api-reference/esm.js`) as a `<script type="module">`. Because it is code-split, less
+JavaScript blocks the first render.
+
+To use the classic UMD bundle instead (loaded via `<script src>` and the `window.Scalar` global):
+
+- `cdn: 'https://.../@scalar/api-reference'` — pin a specific UMD build.
+- `bundle: false` — use the default UMD build.
+
+You can also pass `bundle: 'https://.../esm.js'` to load a specific ESM build.
+
+#### Content Security Policy
+
+Passing a `nonce` implies a strict, nonce-based CSP. The ESM build loads its chunks with native
+`import`, which cannot carry a nonce, so those requests would be blocked unless your policy also has
+`'strict-dynamic'`. For that reason, **the UMD bundle is used automatically whenever a `nonce` is
+set** — it is a single nonced `<script>` with no follow-up requests. If your CSP uses
+`'strict-dynamic'` (or allow-lists the CDN host), pass `bundle: true` to opt back into the ESM build.
+
 ## Community
 
 We are API nerds. You too? Let's chat on Discord: <https://discord.gg/scalar>

package/dist/html-rendering.d.ts

@@ -1,7 +1,19 @@
 import type { AnyApiReferenceConfiguration, HtmlRenderingConfiguration } from '@scalar/types/api-reference';
 export type { AnyApiReferenceConfiguration, HtmlRenderingConfiguration };
-/** Default CDN URL for the @scalar/api-reference standalone bundle. */
+/**
+ * Default CDN URL for the @scalar/api-reference UMD standalone bundle.
+ *
+ * This is the classic build that registers a global `window.Scalar` and is loaded through a plain
+ * `<script src="...">` tag. It is used when the UMD bundle is selected via `cdn` or `bundle: false`.
+ */
 export declare const DEFAULT_CDN = "https://cdn.jsdelivr.net/npm/@scalar/api-reference";
+/**
+ * Default CDN URL for the @scalar/api-reference ESM standalone build (added in #9871).
+ *
+ * This is the default: it is loaded as a `<script type="module">`, so the browser only downloads the
+ * lazy chunks the rendered page needs instead of the whole monolithic UMD bundle.
+ */
+export declare const DEFAULT_ESM_CDN = "https://cdn.jsdelivr.net/npm/@scalar/api-reference/esm.js";
 /**
  * Render the Scalar API Reference as a complete HTML document using the CDN.
  *
@@ -29,6 +41,17 @@ export declare function renderApiReference(options: {
      * `style="..."` attributes that a CSP nonce cannot authorize.
      */
     nonce?: string;
+    /**
+     * Which build to load. The modern, code-split ESM build is the default.
+     *
+     * Pass a URL string to load a specific ESM build, or `false` to fall back to the classic UMD
+     * bundle. When set, `bundle` takes precedence over both `cdn` and the `nonce` fallback.
+     *
+     * When a `nonce` is set (a strict, nonce-based CSP) the UMD bundle is used by default, because the
+     * ESM build's `import`-loaded chunks cannot be nonced. Pass `bundle: true` to force the ESM build
+     * if your CSP uses `'strict-dynamic'`.
+     */
+    bundle?: string | boolean;
 }, customTheme?: string): string;
 /**
  * Serialize a configuration object to a JavaScript object literal string.
@@ -43,12 +66,24 @@ export declare function renderApiReference(options: {
  */
 export declare function serializeConfigToJs(configuration: Record<string, unknown>): string;
 /**
- * The script tags to load the @scalar/api-reference package from the CDN.
+ * The script tag(s) to load the @scalar/api-reference package from the CDN and initialize it.
+ *
+ * By default this loads the modern, code-split ESM build as a `<script type="module">` that imports
+ * `createApiReference` directly (from `DEFAULT_ESM_CDN`), so the browser only downloads the lazy
+ * chunks the page needs rather than the whole monolithic UMD bundle before it can paint.
+ *
+ * The classic UMD bundle — loaded via `<script src>` and `Scalar.createApiReference`, exactly as
+ * before — is used instead when it is the safer choice or is explicitly requested: when a `nonce` is
+ * set (see below), when a `cdn` URL is given (for example to pin a version), or when `bundle: false`.
+ * Set `bundle` to `true` or a URL string to force the ESM build in those cases; `bundle` takes
+ * precedence over both `cdn` and the `nonce` fallback.
  *
- * When a `nonce` is provided it is applied to both script tags so they are allowed under a strict
- * `script-src` Content Security Policy.
+ * A `nonce` signals a strict, nonce-based `script-src` CSP. The ESM build pulls its chunks with native
+ * `import`, which cannot carry a nonce, so those requests are blocked under such a policy unless it
+ * also has `'strict-dynamic'` (or allow-lists the CDN host). The single-file UMD bundle has no such
+ * follow-up requests, so it is the safe default when a `nonce` is present.
  */
-export declare function getScriptTags(configuration: Record<string, unknown>, cdn?: string, nonce?: string): string;
+export declare function getScriptTags(configuration: Record<string, unknown>, cdn?: string, nonce?: string, bundle?: string | boolean): string;
 /**
  * The configuration to pass to the @scalar/api-reference package.
  */

package/dist/html-rendering.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html-rendering.d.ts","sourceRoot":"","sources":["../src/html-rendering.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAE3G,YAAY,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,CAAA;AAExE,uEAAuE;AACvE,eAAO,MAAM,WAAW,uDAAuD,CAAA;AAoE/E;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE;IACP,uCAAuC;IACvC,MAAM,EAAE,4BAA4B,CAAA;IACpC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,EACD,WAAW,SAAK,GACf,MAAM,CA8BR;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA+BlF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAa1G;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,oBAAoB,OAAO,CAAC,0BAA0B,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChF,MAAM,CAAC,MAAM,EAAE,OAAO,CAcxB,CAAA"}
+{"version":3,"file":"html-rendering.d.ts","sourceRoot":"","sources":["../src/html-rendering.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAE3G,YAAY,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,CAAA;AAExE;;;;;GAKG;AACH,eAAO,MAAM,WAAW,uDAAuD,CAAA;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,eAAe,8DAA8D,CAAA;AAoE1F;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE;IACP,uCAAuC;IACvC,MAAM,EAAE,4BAA4B,CAAA;IACpC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAC1B,EACD,WAAW,SAAK,GACf,MAAM,CAiCR;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA+BlF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,GAAG,CAAC,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,GACxB,MAAM,CA8BR;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC3B,oBAAoB,OAAO,CAAC,0BAA0B,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChF,MAAM,CAAC,MAAM,EAAE,OAAO,CAcxB,CAAA"}

package/dist/html-rendering.js

@@ -1,5 +1,17 @@
-/** Default CDN URL for the @scalar/api-reference standalone bundle. */
+/**
+ * Default CDN URL for the @scalar/api-reference UMD standalone bundle.
+ *
+ * This is the classic build that registers a global `window.Scalar` and is loaded through a plain
+ * `<script src="...">` tag. It is used when the UMD bundle is selected via `cdn` or `bundle: false`.
+ */
 export const DEFAULT_CDN = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference';
+/**
+ * Default CDN URL for the @scalar/api-reference ESM standalone build (added in #9871).
+ *
+ * This is the default: it is loaded as a `<script type="module">`, so the browser only downloads the
+ * lazy chunks the rendered page needs instead of the whole monolithic UMD bundle.
+ */
+export const DEFAULT_ESM_CDN = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference/esm.js';
 /**
  * Escape HTML special characters in user-provided strings.
  */
@@ -69,7 +81,10 @@ export function renderApiReference(options, customTheme = '') {
     const { config: givenConfig, pageTitle, cdn, nonce } = options;
     const title = escapeHtml(pageTitle ?? 'Scalar API Reference');
     const unwrapped = Array.isArray(givenConfig) ? givenConfig[0] : givenConfig;
-    const { customCss, theme, ...rest } = (unwrapped ?? {});
+    // `bundle` may also arrive inside the config object (integrations spread unknown options into it),
+    // so read it from there too and keep it out of the config that gets serialized to the client.
+    const { customCss, theme, bundle: configBundle, ...rest } = (unwrapped ?? {});
+    const bundle = (options.bundle ?? configBundle);
     const configuration = getConfiguration({
         ...rest,
         ...(theme ? { theme } : {}),
@@ -88,7 +103,7 @@ export function renderApiReference(options, customTheme = '') {
       content="width=device-width, initial-scale=1" />${cspNonceMeta}${getStyles(configuration, customTheme, nonce)}
   </head>
   <body>
-    <div id="app"></div>${getScriptTags(configuration, cdn, nonce)}
+    <div id="app"></div>${getScriptTags(configuration, cdn, nonce, bundle)}
   </body>
 </html>`;
 }
@@ -137,14 +152,40 @@ export function serializeConfigToJs(configuration) {
     return `${jsonWithoutClosingBrace},\n        ${functionProps.join(',\n        ')}\n      }`;
 }
 /**
- * The script tags to load the @scalar/api-reference package from the CDN.
+ * The script tag(s) to load the @scalar/api-reference package from the CDN and initialize it.
  *
- * When a `nonce` is provided it is applied to both script tags so they are allowed under a strict
- * `script-src` Content Security Policy.
+ * By default this loads the modern, code-split ESM build as a `<script type="module">` that imports
+ * `createApiReference` directly (from `DEFAULT_ESM_CDN`), so the browser only downloads the lazy
+ * chunks the page needs rather than the whole monolithic UMD bundle before it can paint.
+ *
+ * The classic UMD bundle — loaded via `<script src>` and `Scalar.createApiReference`, exactly as
+ * before — is used instead when it is the safer choice or is explicitly requested: when a `nonce` is
+ * set (see below), when a `cdn` URL is given (for example to pin a version), or when `bundle: false`.
+ * Set `bundle` to `true` or a URL string to force the ESM build in those cases; `bundle` takes
+ * precedence over both `cdn` and the `nonce` fallback.
+ *
+ * A `nonce` signals a strict, nonce-based `script-src` CSP. The ESM build pulls its chunks with native
+ * `import`, which cannot carry a nonce, so those requests are blocked under such a policy unless it
+ * also has `'strict-dynamic'` (or allow-lists the CDN host). The single-file UMD bundle has no such
+ * follow-up requests, so it is the safe default when a `nonce` is present.
  */
-export function getScriptTags(configuration, cdn, nonce) {
+export function getScriptTags(configuration, cdn, nonce, bundle) {
     const configString = serializeConfigToJs(configuration);
     const nonceAttr = nonceAttribute(nonce);
+    // The ESM build is the default, but fall back to the single-file UMD bundle when it is the safe or
+    // requested choice: a `nonce` (strict nonce-based CSP, where the ESM build's `import`-loaded chunks
+    // cannot be nonced), a `cdn` URL, or `bundle: false`. An explicit `bundle` (true/URL) always wins.
+    const useUmd = bundle === false || (bundle === undefined && (cdn !== undefined || Boolean(nonce)));
+    if (!useUmd) {
+        const esmUrl = typeof bundle === 'string' ? bundle : DEFAULT_ESM_CDN;
+        return `
+    <!-- Load the Scalar API Reference -->
+    <script type="module"${nonceAttr}>
+      import { createApiReference } from '${esmUrl}'
+
+      createApiReference('#app', ${configString})
+    </script>`;
+    }
     return `
     <!-- Load the Script -->
     <script src="${cdn ?? DEFAULT_CDN}"${nonceAttr}></script>

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { type AnyApiReferenceConfiguration, DEFAULT_CDN, type HtmlRenderingConfiguration, getConfiguration, getScriptTags, renderApiReference, serializeConfigToJs, } from './html-rendering.js';
+export { type AnyApiReferenceConfiguration, DEFAULT_CDN, DEFAULT_ESM_CDN, type HtmlRenderingConfiguration, getConfiguration, getScriptTags, renderApiReference, serializeConfigToJs, } from './html-rendering.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,4BAA4B,EACjC,WAAW,EACX,KAAK,0BAA0B,EAC/B,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,4BAA4B,EACjC,WAAW,EACX,eAAe,EACf,KAAK,0BAA0B,EAC/B,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -1 +1 @@
-export { DEFAULT_CDN, getConfiguration, getScriptTags, renderApiReference, serializeConfigToJs, } from './html-rendering.js';
+export { DEFAULT_CDN, DEFAULT_ESM_CDN, getConfiguration, getScriptTags, renderApiReference, serializeConfigToJs, } from './html-rendering.js';

package/package.json

@@ -11,7 +11,7 @@
     "directory": "packages/client-side-rendering"
   },
   "keywords": [],
-  "version": "0.3.9",
+  "version": "0.4.0",
   "engines": {
     "node": ">=22"
   },
@@ -29,8 +29,8 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@scalar/schemas": "0.8.3",
-    "@scalar/types": "0.18.2",
+    "@scalar/types": "0.19.0",
+    "@scalar/schemas": "0.9.0",
     "@scalar/validation": "0.6.3"
   },
   "devDependencies": {