Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Niurka77/tf-app/llms.txt

Use this file to discover all available pages before exploring further.

TF-App runs on two distinct development layers that must both be configured before you can build or run the app locally. The first is the Node.js/web layer, where Vite compiles your JavaScript source into the dist/ bundle that Capacitor packages. The second is the Android/Java layer, where Gradle and the Android SDK assemble the APK or AAB that runs on a device. Both layers must be operational before running npx cap run android.

​
Prerequisites

Install and verify all of the following tools before cloning the repository.

Node.js ≥ 18 (LTS)

Required to run Vite, Capacitor CLI, and all npm scripts. The LTS release is recommended for stability. Verify with node -v.

npm ≥ 9

Ships bundled with Node.js 18+. Used to install dependencies and run package.json scripts. Verify with npm -v.

Java JDK 17

Required by Gradle and the Android build toolchain. JDK 17 is the version expected by the compileSdkVersion 35 configuration in android/variables.gradle. Verify with java -version.

Android Studio (Hedgehog+)

Provides the Android emulator, device debugger, SDK Manager, and the Gradle daemon. Android Studio Hedgehog (2023.1.1) or newer is recommended. Download from developer.android.com/studio.

​
Android SDK

Inside Android Studio, open SDK Manager (Settings → Languages & Frameworks → Android SDK) and install:
ComponentMinimum VersionNotes
Android SDK PlatformAPI 35Matches compileSdkVersion and targetSdkVersion in android/variables.gradle
Android SDK Build-Tools35.xInstalled automatically with the platform
Android SDK Platform-ToolsLatestProvides adb for device communication
Android EmulatorLatestRequired if testing on a virtual device
TF-App sets minSdkVersion = 23 in android/variables.gradle, meaning it supports Android 6.0 (Marshmallow) and above. You do not need to install SDK Platform images below API 23.

​
Environment Variables

TF-App uses Vite’s built-in import.meta.env system for environment variables. Vite reads .env files from the project root at build time and injects any variable prefixed with VITE_ directly into the compiled bundle.

​
Creating a .env File

Create a .env file at the project root (next to package.json) for your local development overrides: 
VITE_API_BASE_URL=https://api.your-backend.com
VITE_APP_ENV=development
Never commit .env files to version control. They often contain secrets such as API keys or internal endpoint URLs. Add .env to your .gitignore immediately:
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore
Use .env.example (committed, no real values) to document which variables the project requires.

​
Accessing Variables in JavaScript

Any VITE_-prefixed variable is available at runtime via import.meta.env: 
// src/api/client.js
const BASE_URL = import.meta.env.VITE_API_BASE_URL;

export async function fetchProperties() {
  const response = await fetch(`${BASE_URL}/properties`);
  return response.json();
}
Variables without the VITE_ prefix (e.g., SECRET_KEY) are intentionally excluded from the client bundle to prevent accidental exposure.

​
Vite .env File Priority

Vite loads .env files in the following order (later files take precedence):
FileWhen loaded
.envAlways
.env.localAlways; ignored by git
.env.[mode]Only for that mode (e.g., .env.production)
.env.[mode].localOnly for that mode; ignored by git
Use VITE_API_BASE_URL to switch between your local development server and the production backend without touching any source code. Set it to http://10.0.2.2:3000 for Android emulator traffic (which routes to localhost on the host machine) in .env.local, and to your production URL in .env.production.

​
Android SDK Environment Variables

For command-line builds and CI/CD pipelines, Gradle and adb require the ANDROID_HOME environment variable to be set. Add the following to your shell profile (~/.zshrc, ~/.bashrc, or equivalent): 
# macOS / Linux
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
On Windows, set these as System Environment Variables via Control Panel → System → Advanced system settings → Environment Variables: 
ANDROID_HOME = C:\Users\<YourName>\AppData\Local\Android\Sdk
PATH         += %ANDROID_HOME%\platform-tools
PATH         += %ANDROID_HOME%\tools
After setting these, reload your shell and verify the toolchain is accessible: 
adb version
sdkmanager --version
If Android Studio is your primary IDE, it automatically sets ANDROID_HOME for processes launched from within the IDE. The manual export above is required only for terminal-based builds and CI environments.

​
Node Version Management

TF-App requires Node.js 18 or later. If you work across multiple projects with different Node versions, use a version manager to avoid conflicts.

nvm (Node Version Manager)

The most widely used option. Pin the version for this project with a .nvmrc file:
echo "18" > .nvmrc
nvm use
Install from github.com/nvm-sh/nvm.

Volta

Volta pins Node and npm versions per project in package.json automatically. Ideal for teams that want zero-friction version consistency:
volta pin node@18
volta pin npm@9
Install from volta.sh.

​
Verify Your Setup

Once all prerequisites are installed, confirm the full toolchain with: 
node -v          # Should be >= 18.x.x
npm -v           # Should be >= 9.x.x
java -version    # Should be 17.x.x
adb version      # Should print Android Debug Bridge version
npx cap doctor   # Capacitor's built-in environment check
npx cap doctor will report any missing or misconfigured dependencies specific to the Capacitor + Android stack, including SDK paths and JDK compatibility.

Build docs developers (and LLMs) love

Get started for freeTalk to us