Skip to content

Getting Started

Prerequisites#

Common#

  • JetBrains account: As a student you can create a JetBrains account and get all products for free.
  • JetBrains Toolbox
    • JetBrains WebStorm (downloaded through Toolbox, for editing code)
    • JetBrains/Google Android Studio (downloaded through Toolbox, only for setting up emulators and managing the Android SDK)
  • Git
    • SSH authentication (optional). See the GitHub docs. If you use SSH, you need to clone the project using SSH by running git clone git@github.com:ErasmusEgalitarian/educado-mobile.git so Git properly connects to GitHub using SSH.
    • Set up Git to use your GitHub login username and email with the user.name and user.email configuration settings. See the GitHub docs about setting up user.name and user.email.
  • Docker (optional)
  • A cup of coffee and patience

Linux/macOS#

Note

After installing nvm, remember to check if the snippet was added to your shell profile (.bashrc, .zshrc, etc.) and restart your terminal.

Windows#

Install Java#

macOS/Linux#

SDKMAN! reads the .sdkmanrc file in the project root to determine the Java version to install. In the project root (educado-mobile), run:

sdk env install

Windows#

In Windows Terminal (PowerShell), run:

choco install -y microsoft-openjdk17

Install Node.js#

nvm reads the .nvmrc file in the project root to determine the Node.js version to install. In the project root (educado-mobile), run:

macOS/Linux#

nvm install
nvm use
nvm current # Verify version

Windows#

$ver = Get-Content .nvmrc
nvm install $ver # This command will output a command that you have to run in the next step
nvm use [VERSION] # Run the command that was outputted by the previous command
nvm current # Verify version

Install dependencies#

Run:

npm install

Warning

You will have to run this command every time you switch branches or pull changes from the remote. Keep an eye on PRs, as a change in the package.json and/or package-lock.json files requires you to run this command again.

Environment variables#

Copy the contents of .env.local.sample into a new file called .env.local, place it in the root of the local educado-mobile project, and add the variable values to this new file. You will find the values in # mobile on Discord or use the hostname of your locally running back-end instance. Never add .env.local to VCS (it's ignored anyway). Never use .env as it's meant for shared production values that should be added to VCS, e.g., feature flags. See the Expo docs for more information.

Danger

Keep in mind that the values in the .env.local file shared on Discord are pointing to the deployed staging environment. This means that you are working with a live version of the app and potentially editing data that will affect other developers.

Emulator setup#

Upon opening Android Studio for the first time, go through the installation process and install the Android SDK and Android Virtual Device (AVD) when prompted.

Additionally, you will need to install the Android SDK Build Tools and Android SDK Platform Tools.

Follow this guide (Android emulator, development build). It is crucial that you install all the Android SDK components shown in the guide.

Windows

Steps 8 and 10 of the guide above can actually be simplified and done in Windows Terminal (PowerShell). As administrator, run:

$Sdk = "$env:LOCALAPPDATA\Android\Sdk"
setx ANDROID_HOME $Sdk
setx ANDROID_SDK_ROOT $Sdk
setx PATH "$env:PATH;$Sdk\platform-tools;$Sdk\emulator"

In Android Studio, under Settings | Languages & Frameworks | Android SDK | SDK Platforms, you also need to mark the Android 14 components matching the Android 15 components shown in the guide. In total, you should have the following components installed on top of the preinstalled components:

  • Android 15.0 ("VanillaIceCream")
    • Android SDK Platform 35
    • Sources for Android 35
    • Google APIs Intel x86_64 Atom System Image or Google APIs ARM 64 v8a System Image (depends on your architecture)
    • Google Play Intel x86_64 Atom System Image or Google Play ARM 64 v8a System Image (depends on your architecture)
    • Pre-Release 16 KB Page Size Google Play Intel x86_64 Atom System Image or Pre-Release 16 KB Page Size Google Play ARM 64 v8a System Image (depends on your architecture)
  • Android 14.0 ("UpsideDownCake")
    • Android SDK Platform 34
    • Sources for Android 34
    • Google APIs Intel x86_64 Atom System Image or Google APIs ARM 64 v8a System Image (depends on your architecture)
    • Google Play Intel x86_64 Atom System Image or Google Play ARM 64 v8a System Image (depends on your architecture)

Open the Device Manager tool window, then click on Add a new device and select Create Virtual Device.

Visually show where to click

Then select Pixel 6a and click Next. Name it Pixel 6a API 34, select API 34 "UpsideDownCake", select the Google APIs image, and click Finish.

Device configuration

The emulator should now show up in the Device Manager. Click the play button to start it to make sure it works. You can now close the emulator and exit out of Android Studio.

Expo account#

Go to expo.dev and create an account. Send the email you used to create your account to Martin Kedmenec (Discord: @kedgmenec) to be added to the Educado Expo organization. Then, in the project root, run npx expo login and log in using your credentials. Run npx expo whoami to verify that you are logged in.

Running the emulator#

Development build#

First run#

Run npx expo run:android. A window should now pop up with the emulator. The first time you run the app, it will take a while to compile the code and install it on the emulator.

When the app is ready, you should see the app running on the emulator. An android/ directory should have been created in the project root. This directory contains the Android build files.

Note

You only need to run npx expo run:android once or in the following cases:

  • package.json or package-lock.json have been changed
  • Assets and configurations like the app icons, splash screen, manifest, or permissions have changed
  • The Expo version, Android SDK, or emulator configuration have changed

Subsequent development sessions#

Run npx expo start. When the QR code appears, press a to open the default emulator or press shift + a to choose from all available emulators. Choose the emulator you have created (Pixel 6a API 34).

Windows

If you have trouble running the app, get some connection or Metro issues, open a new Windows Terminal (PowerShell) tab and run adb reverse --list. If the output is empty, or shows connection errors, run adb reverse tcp:8081 tcp:8081. The output of the latter command should now show that the port is being forwarded. Go back to the emulator and try to refresh the app.

Tip

If you have trouble getting Expo to bundle or refresh the app, try reloading the app by pressing r in the server menu.

You can also try to run the server with npx expo start -c which will clear the cache before starting the emulator.

Expo Go#

Expo Go is the legacy method of running the app on Android. It is not recommended for development. You can read more about the pros and cons of Expo Go and how it compares to development builds in the Expo docs.

IDE setup#

Android Studio#

You won't really need Android Studio for development because this is a TypeScript-first project, but you will need it for managing the Android SDK.

WebStorm#

WebStorm will automatically read the shared project configuration from the .idea/ directory and a couple of other configuration files like e.g., .editorconfig. But there are some additional settings that you need to configure. You can configure the settings as shown on the images below.

WebStorm settings Node.js

WebStorm settings TypeScript

WebStorm settings Prettier

WebStorm settings ESLint

Visual Studio Code#

WebStorm is the recommended IDE for this project due to the additional refactoring features that it offers. If you, for any reason, can't use WebStorm, you can use Visual Studio Code as a fallback. However, this setup won't be as supported as WebStorm, as managing two or three additional local development setups on top of WebStorm is unfeasible.

Having said that, if you use Visual Studio Code, it will read the project configuration from the .vscode/ directory. The editor will ask you to install the recommended extensions, which you can do by clicking on the Install all button in the bottom right corner.