@axonpack/preview 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @axonpack/preview
+
+## 0.1.0
+
+### Minor Changes
+
+- 8005dc8: - **New package**: publish a JS bundle per branch or pull request, and switch to it in the installed app with no native rebuild
+  - **Preview list**: `PreviewProvider` and a ready-made list to download, switch, update and delete previews. `usePreview` and `useRunning` let you build your own screen
+  - **Crash fallback**: if a preview crashes before it starts, the next launch goes back to the built-in bundle
+  - **Only previews that fit**: matched by app version or native fingerprint with the config plugin's `compatibility` option. Downloads for another build show under Incompatible, with Delete all
+  - **`preview` CLI**: `publish`, `unpublish` and `prune` work with any S3-compatible bucket, public or private with a read-only key. `--environment` builds with an EAS environment's variables
+  - **Local Metro servers**: `preview start` runs Metro on a free port, and debug builds can switch between local servers from the list
+  - **expo-updates**: works alongside it

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Md Asadujjaman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="https://raw.githubusercontent.com/axonpack/axonpack/main/packages/@axonpack/expo-devtools/docs/logo.png" width="88" alt="Axonpack" />
+
+# @axonpack/preview
+
+**Hand QA the JS of every pull request, inside the build they already have.**
+
+Publish one JS bundle per branch to your own S3-compatible bucket. QA opens a list in the app,
+picks a preview, and the app restarts into it. No native rebuild, no new install, and the base
+build comes back with one tap. Like EAS Update or CodePush, but only for previews.
+
+**[Documentation](https://axonpack.dev/docs/preview)** · [Quick start](https://axonpack.dev/docs/preview/quick-start) · [CLI](https://axonpack.dev/docs/preview/cli) · [Changelog](https://axonpack.dev/docs/preview/changelog)
+
+[![npm version](https://img.shields.io/npm/v/@axonpack/preview.svg)](https://www.npmjs.com/package/@axonpack/preview)
+[![npm downloads](https://img.shields.io/npm/dm/@axonpack/preview.svg)](https://www.npmjs.com/package/@axonpack/preview)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/axonpack/axonpack/blob/main/LICENSE)
+
+</div>
+
+## Installation
+
+```sh
+npx expo install @axonpack/preview expo-file-system
+```
+
+It needs React Native's New Architecture, which means Expo SDK 53 or later. Under the old
+architecture the package logs one warning and always loads the base bundle, so the app still
+starts. It has native code, so it runs in a development or release build, not in Expo Go.
+
+## Setup
+
+Add the config plugin to `app.json`, then run a prebuild or a new native build:
+
+```json
+{
+  "expo": {
+    "plugins": [["@axonpack/preview", { "compatibility": "appVersion" }]]
+  }
+}
+```
+
+The plugin bakes a key into the build. The app lists only previews published under that key.
+`appVersion` (the default) keys on the app version; `fingerprint` keys on the native fingerprint.
+
+Wrap the app in the provider and put the list on a screen QA can reach:
+
+```tsx
+import { PreviewList, PreviewProvider } from "@axonpack/preview";
+
+export default function App() {
+  return (
+    <PreviewProvider
+      config={{
+        enabled: true,
+        url: process.env.EXPO_PUBLIC_PREVIEW_S3_URL ?? "",
+      }}
+    >
+      <PreviewList style={{ flex: 1 }} />
+    </PreviewProvider>
+  );
+}
+```
+
+Publish the current branch from the app's root. The bucket and the write key come from the
+environment, or from a gitignored `.env.local`:
+
+```sh
+PREVIEW_S3_URL=https://<account>.r2.cloudflarestorage.com/previews \
+PREVIEW_S3_ACCESS_KEY_ID=... PREVIEW_S3_SECRET_ACCESS_KEY=... \
+npx preview publish
+```
+
+The write key is for publishing only. Never put it in the app: the app gets the bucket's public
+address, or a read-only key for a private bucket.
+
+## Documentation
+
+Everything else is on the docs site.
+
+| Page                                                                         | What is on it                                                           |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [Quick start](https://axonpack.dev/docs/preview/quick-start)                 | From an empty bucket to switching previews in the app                   |
+| [Storage](https://axonpack.dev/docs/preview/storage)                         | Public or private bucket, and the write and read keys                   |
+| [AWS S3](https://axonpack.dev/docs/preview/aws-s3)                           | A bucket, a policy and both keys on AWS                                 |
+| [Cloudflare R2](https://axonpack.dev/docs/preview/cloudflare-r2)             | A bucket, a public address and both keys on R2                          |
+| [MinIO](https://axonpack.dev/docs/preview/minio)                             | Your own server on a VPS, or the local one for trying it out            |
+| [Settings and env files](https://axonpack.dev/docs/preview/environment)      | Where the publish settings and the app's settings come from, and EAS    |
+| [Publishing](https://axonpack.dev/docs/preview/publishing)                   | Publish, replace, unpublish and prune                                   |
+| [CI](https://axonpack.dev/docs/preview/ci)                                   | Publish every pull request with GitHub Actions                          |
+| [Compatibility](https://axonpack.dev/docs/preview/compatibility)             | The config plugin, and app version or fingerprint                       |
+| [App setup](https://axonpack.dev/docs/preview/app-setup)                     | The provider, the list, your own screen and a "what runs" banner        |
+| [Dev preview servers](https://axonpack.dev/docs/preview/dev-preview-servers) | Several Metro servers, one per worktree, switched live in a debug build |
+| [expo-updates](https://axonpack.dev/docs/preview/expo-updates)               | How previews sit on top of a build that expo-updates manages            |
+| [Troubleshooting](https://axonpack.dev/docs/preview/troubleshooting)         | An empty list, a failed download, and what to check                     |
+| [CLI](https://axonpack.dev/docs/preview/cli)                                 | Every command and option                                                |
+| [Reference](https://axonpack.dev/docs/preview/reference)                     | Every export, config field, label and theme token                       |
+| [Changelog](https://axonpack.dev/docs/preview/changelog)                     | Every published release, also in [`CHANGELOG.md`](./CHANGELOG.md)       |
+
+## Example app
+
+`example/` is the default `create-expo-app` template with the list on a Previews tab and a banner
+on every tab that says what runs. It publishes to a local MinIO, so it needs no cloud account:
+
+```sh
+bun run storage:local                       # MinIO in Docker or Podman
+cp example/.env.example example/.env
+cp example/.env.local.example example/.env.local
+cd example && npx expo run:ios              # or: npx expo run:android
+bun run publish:preview --id task-1-login-fix
+```
+
+The whole run, with the device setup for each platform, is in
+[the testing note](https://github.com/axonpack/axonpack/blob/main/packages/@axonpack/preview/notes/testing.md).
+
+## What's built, and what isn't
+
+See [the feature list](https://github.com/axonpack/axonpack/blob/main/packages/@axonpack/preview/notes/README.md) for what's built, what the platform genuinely can't do (and why this
+doesn't fake it), and what's still on the table.

package/android/build.gradle

@@ -0,0 +1,21 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'expo.modules.axonpackpreview'
+version = '0.0.0'
+
+android {
+  namespace "expo.modules.axonpackpreview"
+  defaultConfig {
+    versionCode 1
+    versionName '0.0.0'
+    consumerProguardFiles 'consumer-rules.pro'
+  }
+}
+
+dependencies {
+  // ReactApplication and ReactHost, to restart into a newly chosen bundle.
+  implementation 'com.facebook.react:react-android'
+}

package/android/consumer-rules.pro

@@ -0,0 +1,3 @@
+# @axonpack/preview reaches these by name to put a preview ahead of expo-updates (BundleLoaderOverride.kt).
+-keepclassmembers class com.facebook.react.runtime.ReactHostImpl { *** reactHostDelegate; }
+-keepclassmembers class expo.modules.ExpoReactHostFactory$ExpoReactHostDelegate { *** _jsBundleLoader; }

package/android/src/main/java/expo/modules/axonpackpreview/AxonpackPreviewModule.kt

@@ -0,0 +1,72 @@
+package expo.modules.axonpackpreview
+
+import android.content.pm.PackageManager
+import android.util.Log
+import com.facebook.react.ReactApplication
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class AxonpackPreviewModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("AxonpackPreview")
+
+    Constants(
+      "compatibility" to metaData("COMPATIBILITY"),
+      "key" to metaData("KEY"),
+      "slug" to metaData("SLUG"),
+    )
+
+    Function("select") { bundle: String?, key: String? ->
+      val context = appContext.reactContext ?: return@Function
+      PreviewState.select(context, bundle, key)
+    }
+
+    Function("selectLocalServer") { url: String?, hostPort: String? ->
+      val context = appContext.reactContext ?: return@Function
+      PreviewState.selectLocalServer(context, url, hostPort)
+    }
+
+    Function("state") {
+      appContext.reactContext?.let { PreviewState.read(it) } ?: emptyMap<String, Any?>()
+    }
+
+    Function("markLaunched") {
+      appContext.reactContext?.let { PreviewState.confirmStart(it) }
+    }
+
+    Function("reload") { reload() }
+  }
+
+  private fun reload() {
+    val app = appContext.reactContext?.applicationContext as? ReactApplication
+    if (app == null) {
+      Log.w(TAG, "The application is not a ReactApplication, so there is nothing to reload")
+      return
+    }
+    val host = app.reactHost
+    if (host == null || !PreviewState.newArchitecture()) {
+      PreviewState.warnOldArchitecture()
+      return
+    }
+    PreviewState.nextStart()
+    appContext.reactContext?.let {
+      PreviewState.pointDevSupport(it, host)
+      BundleLoaderOverride.apply(it, host)
+    }
+    host.reload("preview: switch bundle")
+  }
+
+  /** What the config plugin wrote at prebuild; null when the plugin is not in the app config. */
+  private fun metaData(name: String): String? {
+    val context = appContext.reactContext ?: return null
+    return try {
+      context.packageManager
+        .getApplicationInfo(context.packageName, PackageManager.GET_META_DATA)
+        .metaData
+        ?.getString("dev.axonpack.preview.$name")
+    } catch (e: Exception) {
+      null
+    }
+  }
+
+}

package/android/src/main/java/expo/modules/axonpackpreview/BundleLoaderOverride.kt

@@ -0,0 +1,41 @@
+package expo.modules.axonpackpreview
+
+import android.content.Context
+import android.util.Log
+import com.facebook.react.ReactHost
+import com.facebook.react.bridge.JSBundleLoader
+
+/**
+ * expo-updates is asked for the bundle before this package, and once it has applied a downloaded
+ * update it always answers. So with expo-updates installed, the selected preview is also put
+ * straight into the host, in the same private field expo-dev-launcher replaces. Clearing it hands the
+ * start back to expo-updates. If the field is not there (another SDK, a minified build without the
+ * keep rule), the base bundle loads and a warning says why. It never throws.
+ */
+internal object BundleLoaderOverride {
+  private val expoUpdatesInstalled: Boolean by lazy {
+    try {
+      Class.forName("expo.modules.updates.UpdatesPackage")
+      true
+    } catch (e: ClassNotFoundException) {
+      false
+    }
+  }
+
+  fun apply(context: Context, host: ReactHost?) {
+    if (!expoUpdatesInstalled || host == null) return
+    val bundle = PreviewState.bundleToLoad(context)
+    try {
+      val delegate = host.javaClass.getDeclaredField("reactHostDelegate")
+        .apply { isAccessible = true }
+        .get(host) ?: return
+      delegate.javaClass.getDeclaredField("_jsBundleLoader")
+        .apply { isAccessible = true }
+        .set(delegate, bundle?.let { JSBundleLoader.createFileLoader(it.absolutePath) })
+    } catch (e: Exception) {
+      if (bundle != null) {
+        Log.w(TAG, "Could not put the preview ahead of expo-updates, so the base bundle loads", e)
+      }
+    }
+  }
+}

package/android/src/main/java/expo/modules/axonpackpreview/HermesHeader.kt

@@ -0,0 +1,24 @@
+package expo.modules.axonpackpreview
+
+import java.io.InputStream
+
+/** Hermes bytecode starts with an 8-byte magic number, then its format version as a 32-bit int. */
+internal object HermesHeader {
+  private val MAGIC = byteArrayOf(0xc6.toByte(), 0x1f, 0xbc.toByte(), 0x03, 0xc1.toByte(), 0x03, 0x19, 0x1f)
+
+  /** Null for anything that is not Hermes bytecode, such as a plain JS bundle. */
+  fun version(input: InputStream): Int? {
+    val header = ByteArray(12)
+    var read = 0
+    while (read < header.size) {
+      val n = input.read(header, read, header.size - read)
+      if (n < 0) return null
+      read += n
+    }
+    if (!header.copyOfRange(0, 8).contentEquals(MAGIC)) return null
+    return (header[8].toInt() and 0xff) or
+      ((header[9].toInt() and 0xff) shl 8) or
+      ((header[10].toInt() and 0xff) shl 16) or
+      ((header[11].toInt() and 0xff) shl 24)
+  }
+}

package/android/src/main/java/expo/modules/axonpackpreview/PreviewPackage.kt

@@ -0,0 +1,76 @@
+package expo.modules.axonpackpreview
+
+import android.app.Application
+import android.content.Context
+import android.content.Intent
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import com.facebook.react.ReactApplication
+import expo.modules.core.interfaces.ApplicationLifecycleListener
+import expo.modules.core.interfaces.Package
+import expo.modules.core.interfaces.ReactNativeHostHandler
+
+class PreviewPackage : Package {
+  override fun createReactNativeHostHandlers(context: Context): List<ReactNativeHostHandler> {
+    val appContext = context.applicationContext
+    return listOf(
+      object : ReactNativeHostHandler {
+        // Asked each time the React instance is created, so a reload picks up a new choice. Null
+        // leaves the start to expo-updates or the embedded bundle, exactly as without this package.
+        override fun getJSBundleFile(useDeveloperSupport: Boolean): String? {
+          // A local Metro server is loaded by dev support, not from a file.
+          if (PreviewState.localServerHostPort(appContext) != null) return null
+          return PreviewState.bundleToLoad(appContext)?.absolutePath
+        }
+
+        // Expo hands JS errors to the host handlers and only throws itself when there are none, so
+        // this handler decides. A preview that failed while starting goes back to the base bundle
+        // right away; anything else is thrown again, so the app fails exactly as it would without
+        // this package.
+        override fun onReactInstanceException(useDeveloperSupport: Boolean, exception: Exception) {
+          if (!PreviewState.failStart(appContext)) throw exception
+          val host = (appContext as? ReactApplication)?.reactHost
+          // React tears the host and its screens down after reporting the error, so a reload would
+          // leave nothing on screen. Starting the app's own activity again brings up a fresh one,
+          // and with the preview cleared that start is the base bundle.
+          Handler(Looper.getMainLooper()).post {
+            PreviewState.nextStart()
+            PreviewState.pointDevSupport(appContext, host)
+            BundleLoaderOverride.apply(appContext, host)
+            val launch = appContext.packageManager.getLaunchIntentForPackage(appContext.packageName)
+            if (launch != null) {
+              launch.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK)
+              appContext.startActivity(launch)
+            } else {
+              host?.reload("preview: the preview failed while starting")
+            }
+          }
+        }
+      }
+    )
+  }
+
+  override fun createApplicationLifecycleListeners(context: Context): List<ApplicationLifecycleListener> =
+    listOf(
+      object : ApplicationLifecycleListener {
+        // Runs before any activity starts React, so the first start already gets the preview. Only
+        // touches the host when a preview is selected, so an app without one starts as it always did.
+        override fun onCreate(application: Application) {
+          if (
+            PreviewState.localServerHostPort(application) == null &&
+            PreviewState.bundleToLoad(application) == null
+          ) {
+            return
+          }
+          try {
+            val host = (application as? ReactApplication)?.reactHost
+            PreviewState.pointDevSupport(application, host)
+            BundleLoaderOverride.apply(application, host)
+          } catch (e: Exception) {
+            Log.w(TAG, "Could not point the start at the selected preview, the base bundle loads", e)
+          }
+        }
+      }
+    )
+}