Skip to content

feat(mobile): add APP_VARIANT to make it easier to install multiple variants #2422

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
xuatz wants to merge 3 commits into
base: main
Choose a base branch
from
+109 −15
Open

feat(mobile): add APP_VARIANT to make it easier to install multiple variants #2422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
44589fb
feat(mobile): add APP_VARIANT to make it easier to install multiple v…
xuatz Jan 22, 2026
79d2cf5
add new gotcha to docs
xuatz Mar 6, 2026
183df6c
apply pr comments
xuatz Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 17 additions & 4 deletions apps/mobile/app.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,17 @@
const IS_DEV = process.env.APP_VARIANT === "development";
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Fail fast on unsupported APP_VARIANT values.

Line 1 silently maps anything except "development" to the production identifiers. A typo like dev or developement would prebuild app.hoarder.hoardermobile and can overwrite the installed prod app, which is the opposite of the side-by-side install goal here.

Proposed fix 
-const IS_DEV = process.env.APP_VARIANT === "development";
+const APP_VARIANT = process.env.APP_VARIANT ?? "production";
+
+if (!["production", "development"].includes(APP_VARIANT)) {
+  throw new Error(
+    `Unsupported APP_VARIANT "${APP_VARIANT}". Expected "production" or "development".`,
+  );
+}
+
+const IS_DEV = APP_VARIANT === "development";
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
const IS_DEV = process.env.APP_VARIANT === "development";
const APP_VARIANT = process.env.APP_VARIANT ?? "production";
if (!["production", "development"].includes(APP_VARIANT)) {
throw new Error(
`Unsupported APP_VARIANT "${APP_VARIANT}". Expected "production" or "development".`,
);
}
const IS_DEV = APP_VARIANT === "development";
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@apps/mobile/app.config.js` at line 1, The code currently sets IS_DEV by
checking process.env.APP_VARIANT === "development", which silently treats any
other value (including typos) as production and risks overwriting the prod app;
add explicit validation of process.env.APP_VARIANT (allowed values:
"development" and "production") and throw an error or exit early on unsupported
values so builds fail fast; update any logic that uses IS_DEV (the IS_DEV flag
and any app identifier selection that produces app.hoarder.hoardermobile) to
rely on the validated variable rather than implicit truthiness.


export default {
expo: {
name: "Karakeep",
...(IS_DEV
? {
name: "Karakeep Dev",
scheme: "karakeep-dev",
}
: {
name: "Karakeep",
schema: "karakeep",
}),
slug: "hoarder",
scheme: "karakeep",
version: "1.9.1",
orientation: "portrait",
icon: {
Expand All @@ -16,7 +25,9 @@ export default {
assetBundlePatterns: ["**/*"],
ios: {
supportsTablet: true,
bundleIdentifier: "app.hoarder.hoardermobile",
bundleIdentifier: IS_DEV
? "app.hoarder.hoardermobile.dev"
: "app.hoarder.hoardermobile",
splash: {
image: "./assets/splash.png",
resizeMode: "contain",
Expand Down Expand Up @@ -53,7 +64,9 @@ export default {
backgroundColor: "#000000",
},
},
package: "app.hoarder.hoardermobile",
package: IS_DEV
? "app.hoarder.hoardermobile.dev"
: "app.hoarder.hoardermobile",
versionCode: 36,
},
plugins: [
Expand Down
5 changes: 4 additions & 1 deletion apps/mobile/eas.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,10 @@
"build": {
"development": {
"developmentClient": true,
"distribution": "internal"
"distribution": "internal",
"env": {
"APP_VARIANT": "development"
}
},
"preview": {
"distribution": "internal"
Expand Down
5 changes: 5 additions & 0 deletions apps/mobile/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,14 @@
"main": "index.ts",
"scripts": {
"clean": "git clean -xdf .expo .turbo node_modules",
"clean:prebuild": "expo prebuild --no-install --clean",
"clean:prebuild:dev": "APP_VARIANT=development pnpm run clean:prebuild",
"expo": "expo",
"start": "expo start",
"android": "expo run:android",
"android:dev:release": "APP_VARIANT=development pnpm run android --variant release",
Comment on lines +8 to +12
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# First, let's check the full package.json to see dependencies and all scripts
cat apps/mobile/package.json

Repository: karakeep-app/karakeep

Length of output: 3232

🏁 Script executed:

# Search for other environment variable assignments in scripts across the codebase
rg "APP_VARIANT|cross-env" --type json -A 2 -B 2

Repository: karakeep-app/karakeep

Length of output: 974

🏁 Script executed:

# Check if there's documentation about Windows/platform support
fd -t f -e md | xargs grep -l "Windows\|platform\|cmd\.exe\|PowerShell" | head -20

Repository: karakeep-app/karakeep

Length of output: 731

🏁 Script executed:

# Look for similar cross-platform script patterns in other package.json files
fd -name "package.json" -type f | xargs grep -l "cross-env\|env\s" | head -10

Repository: karakeep-app/karakeep

Length of output: 295

🏁 Script executed:

# Check the development setup documentation
fd -name "setup.md" -o -name "*development*" -type f | grep -E "(docs|markdown)" | head -10

Repository: karakeep-app/karakeep

Length of output: 295

🏁 Script executed:

# Read environment variables documentation
cat docs/docs/03-configuration/01-environment-variables.md

Repository: karakeep-app/karakeep

Length of output: 49842

🏁 Script executed:

# Search for Windows or platform-related content in development docs
find docs -name "*.md" -type f | xargs grep -l "Windows\|windows\|cmd\.exe\|PowerShell\|platform" 2>/dev/null | head -5

Repository: karakeep-app/karakeep

Length of output: 293

🏁 Script executed:

# Check if there are other npm scripts that handle environment variables or shell commands
rg "pnpm run|npm run" apps/mobile/package.json -A 1 -B 1

Repository: karakeep-app/karakeep

Length of output: 375

🏁 Script executed:

# Check if other workspaces use cross-env or similar patterns
find . -name "package.json" -type f | xargs grep -l "cross-env" 2>/dev/null

Repository: karakeep-app/karakeep

Length of output: 49

Add cross-env to handle Windows shells in dev-variant scripts.

APP_VARIANT=development pnpm run ... uses POSIX shell syntax and will fail in cmd.exe/PowerShell. To support Windows developers, add cross-env as a devDependency and use it in clean:prebuild:dev and android:dev:release:

Suggested approach
  1. Add cross-env to apps/mobile/package.json devDependencies
  2. Update scripts: 
    -    "clean:prebuild:dev": "APP_VARIANT=development pnpm run clean:prebuild",
+    "clean:prebuild:dev": "cross-env APP_VARIANT=development pnpm run clean:prebuild",
-    "android:dev:release": "APP_VARIANT=development pnpm run android --variant release",
+    "android:dev:release": "cross-env APP_VARIANT=development pnpm run android --variant release",

Alternatively, if Windows support is not required for mobile development, document this constraint explicitly.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@apps/mobile/package.json` around lines 8 - 12, The package.json scripts
clean:prebuild:dev and android:dev:release use POSIX env assignment
(APP_VARIANT=development) which breaks on Windows; add cross-env to
devDependencies in apps/mobile package.json and update those scripts to prefix
with cross-env (i.e., use cross-env APP_VARIANT=development ...) so the
environment variable works across shells, or alternatively add a note in README
that Windows shells are unsupported if you opt not to add cross-env.

"ios": "expo run:ios",
"ios:dev:release": "echo 'i dont have an ios device to confirm if this works'",
Copy link
Collaborator Author

@xuatz xuatz Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

heads up, i haven't tested it on ios ^^

"web": "expo start --web",
"format": "oxfmt --check .",
"format:fix": "oxfmt .",
Expand Down
91 changes: 81 additions & 10 deletions docs/docs/08-development/01-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,27 +132,98 @@ To build and run the mobile app locally, you'll need:

For detailed setup instructions, refer to the [Expo documentation](https://docs.expo.dev/guides/local-app-development/).

#### Updating from an Older Version

If you are returning to mobile development after a significant update to the source (e.g. Expo version bump or major dependency changes), the build may fail with stale artifacts in workspace `node_modules`. Run a clean wipe before reinstalling:

```bash
pnpm run clean:workspaces
pnpm install
```

Then continue with the prebuild and run steps below.

#### TLDR??? THIS IS TOO VERBOSE!
Copy link
Collaborator Author

@xuatz xuatz Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if this language is too casual we can change this lol


```sh
# ios
pnpm --filter mobile clean:prebuild:dev && APP_VARIANT=development pnpm ios

# android
pnpm --filter mobile clean:prebuild:dev && APP_VARIANT=development pnpm android
```

More details below if you want to understand what's going on

Comment on lines +146 to +157
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Consider simplifying the TLDR heading tone

Line 135 (TLDR??? THIS IS TOO VERBOSE!) reads informal for long-term docs maintenance. A neutral heading improves clarity and consistency.

Suggested wording 
-#### TLDR??? THIS IS TOO VERBOSE!
+#### TL;DR
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
#### TLDR??? THIS IS TOO VERBOSE!
```sh
# ios
pnpm --filter mobile clean:prebuild:dev && APP_VARIANT=development pnpm ios
# android
pnpm --filter mobile clean:prebuild:dev && APP_VARIANT=development pnpm android
```
More details below if you want to understand what's going on
#### TL;DR
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/docs/08-development/01-setup.md` around lines 135 - 146, Replace the
informal heading "#### TLDR??? THIS IS TOO VERBOSE!" with a neutral, concise
heading such as "#### Quick start" or "#### TL;DR" to match docs tone; keep the
subsequent shell snippet and explanatory sentence unchanged and ensure the new
heading remains at the same level (the "####" H4) so that formatting and TOC
entries stay consistent.

#### Running the app

- `cd apps/mobile`
- `pnpm exec expo prebuild --no-install` to build the app.
There are two steps: **prebuild** (generates native project files) and **run** (builds and launches the app).

**Step 1: Prebuild**

Basic prebuild:
```bash
pnpm --filter mobile expo prebuild --no-install
```

If you need a clean rebuild (e.g. after changing the bundleIdentifier/package), add `--clean`:
```bash
pnpm --filter mobile expo prebuild --no-install --clean
```

Or use the shorthand alias:
```bash
pnpm --filter mobile clean:prebuild
```

To run a **dev variant** alongside your production Karakeep app (without uninstalling it), set `APP_VARIANT=development` during a clean prebuild. This changes the bundleIdentifier/package so both versions can coexist:
```bash
APP_VARIANT=development pnpm --filter mobile expo prebuild --no-install --clean
```

Or use the shorthand alias:
```bash
pnpm --filter mobile clean:prebuild:dev
```

> **Note:** The installed app expects the dev server to be available and accessible.

**Step 2: Run**

**For iOS:**
- `pnpm exec expo run:ios`
- The app will be installed and started in the simulator.
```bash
pnpm ios
```
The app will be installed and started in the simulator.
Comment on lines 193 to +197
Copy link

@greptile-apps greptile-apps bot Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Android section (lines 211–214) correctly notes that APP_VARIANT=development must be passed at run time after a dev prebuild. The iOS section should include the same reminder for consistency.

Add a note after the basic pnpm ios example:

Suggested change
**For iOS:**
- `pnpm exec expo run:ios`
- The app will be installed and started in the simulator.
```bash
pnpm ios
```
The app will be installed and started in the simulator.
**For iOS:**
```bash
pnpm ios

The app will be installed and started in the simulator.

If you prebuilt with APP_VARIANT=development, make sure to pass it at run time too:

APP_VARIANT=development pnpm ios

<details><summary>Prompt To Fix With AI</summary>

`````markdown
This is a comment left during a code review.
Path: docs/docs/08-development/01-setup.md
Line: 193-197

Comment:
The Android section (lines 211–214) correctly notes that `APP_VARIANT=development` must be passed at run time after a dev prebuild. The iOS section should include the same reminder for consistency.

Add a note after the basic `pnpm ios` example:

```suggestion
**For iOS:**
```bash
pnpm ios

The app will be installed and started in the simulator.

If you prebuilt with APP_VARIANT=development, make sure to pass it at run time too:

APP_VARIANT=development pnpm ios

How can I resolve this? If you propose a fix, please make it concise.


**Troubleshooting iOS Setup:**
If you encounter an error like `xcrun: error: SDK "iphoneos" cannot be located`, you may need to set the correct Xcode developer directory:
If you encounter `xcrun: error: SDK "iphoneos" cannot be located`, set the correct Xcode developer directory:
```bash
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```

**For Android:**
- Start the Android emulator or connect a physical device.
- `pnpm exec expo run:android`
- The app will be installed and started on the emulator/device.

Changing the code will hot reload the app. However, installing new packages requires restarting the expo server.
Start the Android emulator or connect a physical device, then:
```bash
pnpm android
```

If you prebuilt with `APP_VARIANT=development`, make sure to pass it at run time too:
```bash
APP_VARIANT=development pnpm android
```

Changing code will hot reload the app. However, installing new packages requires restarting the expo server.

**Installing a release build (Android only):**

> **Note:** This may also work for iOS, but has not been confirmed due to lack of an iOS test device (of this author).

To install the dev variant as a release build (no dev server required):
```bash
pnpm --filter mobile clean:prebuild:dev
pnpm --filter mobile android:dev:release
```

### Browser Extension

Expand Down
2 changes: 2 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@
"db:studio": "pnpm --filter @karakeep/db studio",
"workers": "pnpm --filter @karakeep/workers run start",
"web": "pnpm --filter @karakeep/web run dev",
"android": "pnpm --filter mobile android",
"ios": "pnpm --filter mobile ios",
"prepare": "husky",
"format": "turbo --no-daemon format --continue",
"format:fix": "turbo --no-daemon format:fix --continue",
Expand Down