feat: official support for custom remote cache providers

[thymikee]

Summary

This diff adds support for writing your own custom remote providers, which was quasi-supported previously.

Notable changes:

• Changed the remote cache interface to:

  /**
   * Interface for implementing remote build cache providers.
   * Remote cache providers allow storing and retrieving native build artifacts (e.g. APK, IPA)
   * from remote storage like S3, GitHub Artifacts etc.
   */
  export interface RemoteBuildCache {
    /** Unique identifier for this cache provider, will be displayed in logs */
    name: string;
  
    /**
     * List available artifacts matching the given name pattern
     * @param artifactName - Passed after fingerprinting the build, e.g. `rnef-android-debug-1234567890` for android in debug variant
     * @param limit - Optional maximum number of artifacts to return
     * @returns Array of matching remote artifacts, or empty array if none found
     */
    list({
      artifactName,
      limit,
    }: {
      artifactName: string | undefined;
      limit?: number;
    }): Promise<RemoteArtifact[]>;
  
    /**
     * Download a remote artifact to local storage
     * @param artifactName - Name of the artifact to download, e.g. `rnef-android-debug-1234567890` for android in debug variant
     * @returns Response object from fetch, which will be used to download the artifact
     */
    download({ artifactName }: { artifactName: string }): Promise<Response>;
  
    /**
     * Delete a remote artifact
     * @param artifact - Remote artifact to delete, as returned by `list` method
     * Throws if artifact is not found or deletion fails
     */
    delete({ artifactName }: { artifactName: string }): Promise<RemoteArtifact[]>;
  
    /**
     * Upload a local artifact stored in build cache to remote storage
     * @param artifactName - Name of the artifact to upload, e.g. `rnef-android-debug-1234567890` for android in debug variant
     * @returns Remote artifact info if upload successful, throws otherwise
     */
    upload({ artifactName }: { artifactName: string }): Promise<RemoteArtifact>;
  }

• made remoteCacheProvider to accept a function that returns a class that implements RemoteBuildCache, so that we can configure input parameters, such as auth data, or repo information

  // rnef.config.mjs
  export default {
    // ...
    remoteCacheProvider: pluginGitHubBuildCache({
      owner: 'callstack-internal',
      repository: 'rnef-remote-build-test',
      token: '<token>',
    }),
  }

• Added docs with a dummy remote cache that works (previously it would fail with wrong schema type).
• Implemented delete method for GitHub provider that deletes all matching artifacts (there can be many with the same name)
• changed query to list that returns a list of artifacts

Test plan

Added unit test for creating and using remote cache provider.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
rnef	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 17, 2025 10:22am

[satya164]

"otherwise" implies error or a different case (e.g. no support)?

maybe better to throw error instead or return an object with additional info that the CLI could display?

[thymikee]

The upload is something I haven't given too much thought yet, as GitHub API doesn't support it. I'll make it return RemoteArtifact or throw

[satya164]

why would artifact name be needed to list artifacts 🤔

[thymikee]

It's for listing matching artifacts to your local fingerprint. Could make it optional though

[szymonrybczak]

Now it's time to implement this spec for the 3rd party provider and validate it in the wild 😁