From e3e16ff10b0199606ca65621c20aac10113ebcde Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mikl=C3=B3s=20Fazekas?= Date: Wed, 17 Jun 2026 09:44:35 +0200 Subject: [PATCH] chore: warn on explicit loadCdn:true on the experimental backend MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The experimental backend ignores `loadCdn` — its CommandQueue file-load API (`RiveFile.fromSource(source, worker)`) has no CDN asset resolution, so the `loadCdn` argument on `RiveFileFactory.from*` is silently a no-op there. `loadCdn` is now optional (the effective default of `true` is applied only at the native call via `?? true`), and a one-time `console.warn` is emitted only when a caller *explicitly* passes `loadCdn: true` while on the experimental backend — so the common case (not passing `loadCdn`, e.g. `useRiveFile`) is never warned. JSDoc updated to note the option is ignored on experimental. --- src/core/RiveFile.ts | 63 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 49 insertions(+), 14 deletions(-) diff --git a/src/core/RiveFile.ts b/src/core/RiveFile.ts index 8ec5524e..29933479 100644 --- a/src/core/RiveFile.ts +++ b/src/core/RiveFile.ts @@ -10,6 +10,32 @@ import type { ResolvedReferencedAssets } from './ReferencedAssets'; const RiveFileInternal = NitroModules.createHybridObject('RiveFileFactory'); +let _warnedLoadCdnUnsupported = false; + +/** + * The experimental backend ignores `loadCdn` — its CommandQueue file-load API + * has no CDN asset resolution. Warn once (per JS runtime) when a caller + * *explicitly* opts into `loadCdn: true` there, so they know CDN-referenced + * assets must be supplied via `referencedAssets` instead. Callers that don't + * pass `loadCdn` (the common case) are not warned. + */ +function warnLoadCdnUnsupportedOnExperimental( + loadCdn: boolean | undefined +): void { + if ( + loadCdn === true && + !_warnedLoadCdnUnsupported && + RiveFileInternal.backend === 'experimental' + ) { + _warnedLoadCdnUnsupported = true; + console.warn( + '[Rive] `loadCdn: true` is not supported on the experimental backend and is ignored. ' + + 'CDN-referenced assets (fonts/images) are not fetched automatically — supply them ' + + 'via the `referencedAssets` option instead.' + ); + } +} + /** * Factory namespace for creating RiveFile instances from different sources. * Provides static methods to load Rive files from URLs, resources, or raw bytes. @@ -23,17 +49,19 @@ export namespace RiveFileFactory { /** * Creates a RiveFile instance from a URL. * @param url - The URL of the Rive (.riv) file - * @param loadCdn - Whether to load from CDN (default: true) + * @param loadCdn - Whether to fetch CDN-referenced assets (default: true). + * Ignored on the experimental backend — supply assets via `referencedAssets` instead. * @returns Promise that resolves to a RiveFile instance */ export async function fromURL( url: string, referencedAssets: ResolvedReferencedAssets | undefined, - loadCdn: boolean = true + loadCdn?: boolean ): Promise { + warnLoadCdnUnsupportedOnExperimental(loadCdn); return RiveFileInternal.fromURL( url, - loadCdn, + loadCdn ?? true, referencedAssets ? { data: referencedAssets } : undefined ); } @@ -41,17 +69,19 @@ export namespace RiveFileFactory { /** * Creates a RiveFile instance from a local file path URL. * @param pathURL - The local file path of the Rive (.riv) file - * @param loadCdn - Whether to load from CDN (default: true) + * @param loadCdn - Whether to fetch CDN-referenced assets (default: true). + * Ignored on the experimental backend — supply assets via `referencedAssets` instead. * @returns Promise that resolves to a RiveFile instance */ export async function fromFileURL( fileURL: string, referencedAssets: ResolvedReferencedAssets | undefined = undefined, - loadCdn: boolean = true + loadCdn?: boolean ): Promise { + warnLoadCdnUnsupportedOnExperimental(loadCdn); return RiveFileInternal.fromFileURL( fileURL, - loadCdn, + loadCdn ?? true, referencedAssets ? { data: referencedAssets } : undefined ); } @@ -59,17 +89,19 @@ export namespace RiveFileFactory { /** * Creates a RiveFile instance from a local resource. * @param resource - The name of the local resource - * @param loadCdn - Whether to load from CDN (default: true) + * @param loadCdn - Whether to fetch CDN-referenced assets (default: true). + * Ignored on the experimental backend — supply assets via `referencedAssets` instead. * @returns Promise that resolves to a RiveFile instance */ export async function fromResource( resource: string, referencedAssets: ResolvedReferencedAssets | undefined, - loadCdn: boolean = true + loadCdn?: boolean ): Promise { + warnLoadCdnUnsupportedOnExperimental(loadCdn); return RiveFileInternal.fromResource( resource, - loadCdn, + loadCdn ?? true, referencedAssets ? { data: referencedAssets } : undefined ); } @@ -77,17 +109,19 @@ export namespace RiveFileFactory { /** * Creates a RiveFile instance from raw bytes. * @param bytes - The raw bytes of the Rive (.riv) file - * @param loadCdn - Whether to load from CDN (default: true) + * @param loadCdn - Whether to fetch CDN-referenced assets (default: true). + * Ignored on the experimental backend — supply assets via `referencedAssets` instead. * @returns Promise that resolves to a RiveFile instance */ export async function fromBytes( bytes: ArrayBuffer, referencedAssets: ResolvedReferencedAssets | undefined, - loadCdn: boolean = true + loadCdn?: boolean ): Promise { + warnLoadCdnUnsupportedOnExperimental(loadCdn); return RiveFileInternal.fromBytes( bytes, - loadCdn, + loadCdn ?? true, referencedAssets ? { data: referencedAssets } : undefined ); } @@ -95,7 +129,8 @@ export namespace RiveFileFactory { /** * Creates a RiveFile instance from a source that can be either a resource ID or a URI object. * @param source - Either a number representing a resource ID or an object with a uri property - * @param loadCdn - Whether to load from CDN (default: true) + * @param loadCdn - Whether to fetch CDN-referenced assets (default: true). + * Ignored on the experimental backend — supply assets via `referencedAssets` instead. * @returns Promise that resolves to a RiveFile instance * @throws Error if the source is invalid or cannot be resolved * @example @@ -117,7 +152,7 @@ export namespace RiveFileFactory { export async function fromSource( source: number | { uri: string }, referencedAssets: ResolvedReferencedAssets | undefined, - loadCdn: boolean = true + loadCdn?: boolean ): Promise { const assetID = typeof source === 'number' ? source : null; const sourceURI = typeof source === 'object' ? source.uri : null;