@axonpack/preview 0.0.0-stage → 0.1.0

package/notes/storage.md

@@ -0,0 +1,145 @@
+# Storage
+
+Where previews are kept: in the bucket they are published to, and on the device once downloaded.
+
+- [ ] Reads previews from any S3-compatible bucket (S3, R2, MinIO and others), public or private (with a read-only key)
+- [ ] Downloads a preview into the app's documents folder and checks every file
+- [ ] Keeps a download until QA deletes it; nothing expires on a timer
+- [ ] Shows downloads made for another native build apart, with one button to delete them all
+
+A half-finished download is never offered, because it only becomes a preview once every file has
+been checked.
+
+## Settings
+
+Publishing reads its settings the way Expo reads the app's: from the environment, then the same
+`.env*` files Expo loads for a release bundle. Only `EXPO_PUBLIC_*` values are built into the app,
+so the write key, which has no such prefix, never ends up inside it.
+
+| Variable                   | Read by                       | What it holds                                                                     |
+| -------------------------- | ----------------------------- | --------------------------------------------------------------------------------- |
+| `PREVIEW_S3_*`             | `preview publish` only        | The bucket URL and the **write** key                                              |
+| `EXPO_PUBLIC_PREVIEW_S3_*` | Expo, when it bundles the app | The bucket URL and, for a private bucket, a **read-only** key. Built into the app |
+
+The CLI never reads `EXPO_PUBLIC_*`. The example has `example/.env.example` (the app's settings)
+and `example/.env.local.example` (the publish settings) with the local values.
+
+### Publish settings
+
+CI has no settings file, so the environment comes first: the shell, or the CI job's secrets. For
+publishing from your own machine they can go in an env file instead. Publish loads the files
+`expo export:embed --dev false` loads (mode `production`), through the app's own `@expo/env`, so the
+order and the `${VAR}` expansion are Expo's:
+
+1. `.env.production.local`
+2. `.env.local`
+3. `.env.production`
+4. `.env`
+
+A variable set in the environment wins over every file, and the first file in the list wins over
+the ones after it. `.env.development*` and other modes are not read. `EXPO_NO_DOTENV` turns the
+files off here too.
+
+Put the write key in `.env.local` or `.env.production.local`, which Expo's project template
+gitignores (`.env*.local`), or in CI secrets. Never put it in a committed `.env`: anyone with the
+repo could then write to the bucket.
+
+| Variable                       | Needed | What it is                                                                                                                                                                               |
+| ------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PREVIEW_S3_URL`               | yes    | `<endpoint>/<bucket>`, plus a folder inside the bucket if there are more segments: `http://localhost:9000/previews-public`, `https://<account>.r2.cloudflarestorage.com/previews/my-app` |
+| `PREVIEW_S3_ACCESS_KEY_ID`     | yes    | Write key id. Never ship it in the app                                                                                                                                                   |
+| `PREVIEW_S3_SECRET_ACCESS_KEY` | yes    | Write key secret                                                                                                                                                                         |
+| `PREVIEW_S3_REGION`            | no     | Signing region. Default `us-east-1`, which MinIO and R2 accept                                                                                                                           |
+
+The names are the package's own, not `AWS_*`, so they work the same for any S3-compatible host and
+never pick up AWS keys already exported in a shell.
+
+## Set up local storage
+
+For the whole run, from starting the server to switching previews in the app, see
+[testing.md](./testing.md).
+
+A local S3 server, so you can try both bucket modes without a cloud account. It is MinIO, with one
+public-read bucket and one private bucket plus a read-only key. Every name, key and the port live in
+`local-s3/local-s3.env`, and both setups below read that file. The keys are local test values only.
+
+### With Docker (main path)
+
+Needs Docker: Docker Desktop or OrbStack on macOS, the Docker engine on Linux. Podman's Docker
+socket works too. From `packages/@axonpack/preview`:
+
+| Command                       | Does                                                                   |
+| ----------------------------- | ---------------------------------------------------------------------- |
+| `bun run storage:local`       | Starts MinIO, then creates the buckets and the read key. Safe to rerun |
+| `bun run storage:local:stop`  | Stops it. Uploaded files stay in `local-s3/data/` (gitignored)         |
+| `bun run storage:local:reset` | Stops it and deletes `local-s3/data/`, so the next start is empty      |
+
+MinIO stopped publishing its own images in 2025, so `local-s3/compose.yaml` uses Bitnami's frozen
+copies, pinned by digest.
+
+### Without Docker
+
+1. `brew install minio/stable/minio minio/stable/mc` (not tried here: MinIO's own downloads changed
+   in 2025, so this tap may be gone).
+2. In one terminal, from `packages/@axonpack/preview/local-s3`:
+   `set -a; . ./local-s3.env; set +a; minio server ./data --address ":$LOCAL_S3_PORT"`
+3. In another, from the same folder:
+   `set -a; . ./local-s3.env; set +a; LOCAL_S3_URL="http://localhost:$LOCAL_S3_PORT" sh ./init.sh`
+
+`init.sh` is the same script the Docker setup runs, so the buckets, policy and key come out the same.
+
+### What you get
+
+| Value          | Local test value                                                          |
+| -------------- | ------------------------------------------------------------------------- |
+| Endpoint       | `http://localhost:9000`, region `us-east-1`, path-style URLs              |
+| Public bucket  | `previews-public`: anyone can read, only the write key can write          |
+| Private bucket | `previews-private`: reads need the read key, signed with SigV4            |
+| Write key      | `preview-admin` / `preview-admin-secret` (MinIO's root user)              |
+| Read key       | `preview-reader` / `preview-reader-secret` (read `previews-private` only) |
+
+A file is at `<endpoint>/<bucket>/<path>`.
+
+### The example app
+
+The example reads its bucket from `example/.env` (copy `example/.env.example`):
+
+| Variable                                        | Needed | What it is                                                                                                                                                                       |
+| ----------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EXPO_PUBLIC_PREVIEW_S3_URL`                    | yes    | With a read key, the same `<endpoint>/<bucket>` the previews are published to. Without one, any address they are public under: that URL, R2's `https://pub-<id>.r2.dev` or a CDN |
+| `EXPO_PUBLIC_PREVIEW_S3_READ_ACCESS_KEY_ID`     | no     | Only for a private bucket: the read-only key (`preview-reader` locally)                                                                                                          |
+| `EXPO_PUBLIC_PREVIEW_S3_READ_SECRET_ACCESS_KEY` | no     | Its secret (`preview-reader-secret` locally)                                                                                                                                     |
+| `EXPO_PUBLIC_PREVIEW_S3_REGION`                 | no     | Signing region for a private bucket. Default `us-east-1`; `auto` on R2                                                                                                           |
+
+With a read key the app splits the URL into endpoint, bucket and folder and signs its reads. Without
+one it reads `<url>/<key>` unsigned, so the URL needs no bucket in it.
+
+Headers for a tunnel or proxy are not env values: pass `headers` in the app's config.
+
+Expo builds `EXPO_PUBLIC_*` values into the app, so only a read-only key may go there, never the
+write key. They are read when the app is bundled, so rebuild after changing them.
+
+The address `localhost:9000` works as it is on the iOS simulator. On the Android emulator, run
+`adb reverse tcp:9000 tcp:9000` once per emulator start, so the emulator's `localhost:9000` reaches
+this computer. On a phone, use the computer's LAN address instead (`http://<LAN IP>:9000/...`), in
+both the publish URL and the app's URL.
+
+A tunnel works too, for a phone on another network: forward port 9000 (a VS Code dev tunnel, for
+example) and put its HTTPS address in the app's URL, while publishing stays on `localhost:9000`. The
+tunnel must be public, or it answers every request with a redirect to a login page. Dev tunnels may
+also put a warning page in front of the first request; pass
+`headers: { "X-Tunnel-Skip-AntiPhishing-Page": "True" }` in the app's config to skip it.
+
+### Plain HTTP on a device
+
+The local server has no TLS. A release build on Android refuses plain HTTP to any host unless the
+app allows cleartext traffic, so downloads fail with a cleartext error, while a debug build works.
+The example app turns cleartext on in its own config (`expo-build-properties`,
+`android.usesCleartextTraffic`), never in the package's defaults. A real app should use HTTPS. iOS does not apply App Transport Security to IP
+addresses or `localhost`, so the simulator and a phone using the LAN IP should work as they are
+(to be checked on a device in the download phase).
+
+Android 17 also asks the user before an app may reach the local network, which includes the
+emulator's `10.0.2.2` and a LAN IP (the `ACCESS_LOCAL_NETWORK` permission). If it is denied, both
+downloads from the local server and a debug build's connection to Metro fail. On the emulator,
+`adb shell pm grant <package> android.permission.ACCESS_LOCAL_NETWORK` grants it.

package/notes/testing.md

@@ -0,0 +1,97 @@
+# Testing
+
+Running the example end to end on your own machine, with no cloud account.
+
+- [x] A local S3 server (MinIO) with a public and a private bucket, started with one command
+- [x] An example app (the default `create-expo-app` template, tabs) with the list on a Previews tab
+- [x] A banner on every tab that says what runs: a dev preview server, a preview, or the base bundle
+- [x] Links that do what the list's buttons do, so a run can be scripted from a terminal
+
+## Run the example end to end
+
+From `packages/@axonpack/preview`, after `bun install` at the repo root.
+
+1. Start Docker, or Podman with `podman machine start`.
+2. Start the local S3 server:
+   ```sh
+   bun run storage:local
+   ```
+3. Copy the two settings files. `.env` holds the app's settings. `.env.local` holds the publish
+   settings with the write key; uncomment its lines after copying. Both are gitignored.
+   ```sh
+   cp example/.env.example example/.env
+   cp example/.env.local.example example/.env.local
+   ```
+4. Build and run the example, in a debug or a release build:
+   ```sh
+   cd example
+   npx expo run:ios      # or: npx expo run:ios --configuration Release
+   npx expo run:android  # or: npx expo run:android --variant release
+   ```
+5. Make sure the device reaches the server:
+   - iOS simulator: `localhost` works as it is.
+   - Android emulator, or a phone on USB: `adb reverse tcp:9000 tcp:9000`, once each time the device
+     starts.
+   - Phone on the same Wi-Fi: put the computer's LAN IP in `EXPO_PUBLIC_PREVIEW_S3_URL`.
+   - Phone on another network: a public tunnel to port 9000 (see [storage.md](./storage.md#the-example-app)).
+
+   `EXPO_PUBLIC_*` values are built into the bundle, so after changing one run
+   `npx expo start --clear`, or rebuild for a release build.
+
+6. Publish a preview from `example/`:
+   ```sh
+   bun run publish:preview --id task-1-login-fix --changelog="- Fixes the login"
+   ```
+   That publishes for Android and iOS. In a terminal it asks for the title, prefilled from the id;
+   Enter keeps it.
+   `bunx preview publish …` works too. Use `bunx` in this repo, not `npx`: `npx` can't read
+   bun's install, so it looks for a `preview` package on npm and fails with a 404. An app
+   installed with npm uses `npx`.
+7. In the app's Previews tab: Refresh, Download, Switch, then Back to base. The banner at the top
+   names what runs. Publish the same id again with other
+   changes to see "Update available", or `bunx preview unpublish <id>` to see "Unpublished".
+8. Stop everything:
+   ```sh
+   cd .. && bun run storage:local:stop
+   podman machine stop   # if you use Podman
+   ```
+
+The example also takes links, which run the same code as its buttons:
+`previewexample://download/<id>`, `switch/<id>`, `switch/embedded`, `refresh`, `delete/<id>`,
+`deleteincompatible`, `local/<port>` and `localstop`. Each one lands on the Previews tab
+(`src/app/+native-intent.tsx`). Open them with `xcrun simctl openurl booted <link>` or
+`adb shell am start -d <link>`.
+
+## Several tasks at once (people and AI agents)
+
+One debug build of the example can run any of several Metro servers, one per task or worktree. The
+app needs `devPreviewServers: true` (the example has it).
+
+1. In each worktree, start Metro with:
+   ```sh
+   bun run start:preview                # picks a free port in 8081-8099 and announces it
+   bun run start:preview -- -- --clear  # after the second --, args go to expo start (bun eats the first)
+   ```
+   In a terminal it asks for the name the app shows, prefilled from the branch; Enter keeps it.
+   `--title <name>` skips the question, and so does a run with no terminal.
+   A plain `npx expo start --port 8085` is found as well, with less detail (no branch).
+2. Open the Previews tab in the app. "Dev preview servers" shows each server for this app within about two
+   seconds, with its branch, port and version. Switch runs that server; "Stop using dev preview server"
+   goes back.
+3. Stop a server with Ctrl+C; it leaves the list on its own.
+
+On the Android emulator nothing else is needed. A phone on USB needs `adb reverse` for each port;
+`preview start` does it when `adb` is on the PATH. See [dev-preview-servers.md](./dev-preview-servers.md).
+
+## Troubleshooting
+
+- **"Expected JSON from … but got text/html"**: something other than the bucket answered. The URL is
+  not public, or a tunnel is showing its login page. Make the tunnel public, or use `localhost` with
+  `adb reverse`.
+- **The list is empty**: nothing is published for this build's key. With the default
+  `compatibility: "appVersion"` the key is the app version, so publish again after a version bump.
+  With `"fingerprint"`, a prebuild or any native or app config change gives a new key, so publish
+  again after the build you are running.
+- **Android cannot connect**: the `adb reverse` was lost when the emulator or phone restarted, or the
+  app was refused local network access (Android 17 asks). Run `adb reverse` again, or allow the
+  permission in the app's settings.

package/package.json

@@ -1,6 +1,109 @@
 {
   "name": "@axonpack/preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Download and switch between preview JS bundles of an Expo app without a native rebuild",
+  "author": "Md Asadujjaman <abappi2019@gmail.com> (https://github.com/abappi19)",
+  "keywords": [
+    "preview",
+    "ota",
+    "bundle",
+    "qa",
+    "expo",
+    "react-native"
+  ],
+  "bugs": {
+    "url": "https://github.com/axonpack/axonpack/issues"
+  },
+  "license": "MIT",
+  "homepage": "https://axonpack.dev/docs/preview/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axonpack/axonpack.git",
+    "directory": "packages/@axonpack/preview"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "android",
+    "ios",
+    "bin",
+    "build",
+    "app.plugin.js",
+    "expo-module.config.json",
+    "CHANGELOG.md",
+    "notes"
+  ],
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "bin": {
+    "preview": "bin/preview.js"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": {
+        "expo-source": "./src/index.ts",
+        "default": "./build/index.d.ts"
+      },
+      "expo-source": "./src/index.ts",
+      "default": "./build/index.js"
+    },
+    "./app.plugin.js": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf build && tsc && bun build src/cli.ts --target=node --format=cjs --outfile=build/cli.cjs",
+    "prepare": "bun run build",
+    "clean": "rm -rf build",
+    "lint": "oxlint src",
+    "format": "oxlint src --fix",
+    "test": "jest",
+    "check-types": "tsc --noEmit -p tsconfig.check.json",
+    "storage:local": "./local-s3/run.sh start",
+    "storage:local:stop": "./local-s3/run.sh stop",
+    "storage:local:reset": "./local-s3/run.sh reset"
+  },
+  "devDependencies": {
+    "@babel/runtime": "^7.28.4",
+    "@types/jest": "^29.2.1",
+    "@types/node": "^24.0.0",
+    "@types/react": "~19.3.0",
+    "@types/react-test-renderer": "^19.1.0",
+    "expo": "^57.0.7",
+    "expo-file-system": "~58.0.11",
+    "jest": "^29.7.0",
+    "jest-expo": "~57.0.2",
+    "linter": "*",
+    "oxlint": "^1.80.0",
+    "react": "19.3.0",
+    "react-native": "0.86.0",
+    "react-test-renderer": "19.3.0",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "expo": ">=53",
+    "react": ">=18",
+    "react-native": ">=0.79",
+    "expo-file-system": "*"
+  },
+  "jest": {
+    "preset": "jest-expo",
+    "roots": [
+      "<rootDir>/src"
+    ],
+    "testMatch": [
+      "**/*.test.ts",
+      "**/*.test.tsx"
+    ],
+    "transformIgnorePatterns": [
+      "node_modules/(?!.*(react-native|expo|@noble))"
+    ],
+    "moduleNameMapper": {
+      "^@babel/runtime/(.*)$": "<rootDir>/node_modules/@babel/runtime/$1"
+    }
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.4.0"
+  }
+}