Local Development Setup for ComuniTEA Contributors

This guide walks contributors and developers through everything needed to run ComuniTEA locally — from installing prerequisites and configuring environment variables, to launching the Expo dev server on a physical device or emulator. ComuniTEA is an Expo SDK 57 / React Native 0.86 app with a Supabase backend, so the setup covers both the mobile client and the cloud services that power its AI features.

Prerequisites

Before cloning the repository, make sure the following are available on your machine.

Node.js 18+

ComuniTEA’s toolchain (Expo CLI, Jest, generation scripts) requires Node 18 or later. npm ships with Node, so no separate install is needed.

Expo Go

Install Expo Go on a physical iOS or Android device to scan the QR code from the dev server, or use the Android emulator (Pixel 5) described below.

Android Emulator (optional)

If you prefer an emulator, create an AVD named Pixel_5 in Android Studio. The npm run emulator script launches it by name.

Supabase Account

A free-tier Supabase project is enough. You’ll need the project URL and anon key for the .env.local file.

Environment Setup

Clone the repository

git clone https://github.com/ElthonJohan/comunitea.git
cd comunitea

Install dependencies

Install all JavaScript dependencies declared in package.json:

npm install

The project uses Expo SDK 57, React Native 0.86, React 19, Zustand 5, and React Native Reanimated 4 among others. All are resolved from node_modules — no separate npx expo install step is required after a clean npm install.

Create the environment file

Create a .env.local file in the project root with your Supabase credentials:

# .env.local
EXPO_PUBLIC_SUPABASE_URL=https://<your-project-ref>.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=<your-anon-key>

The EXPO_PUBLIC_ prefix is required for Expo to expose these values to the React Native bundle at build time. Both variables are validated at startup — the app throws a [ComuniTEA] error if either is missing.

Configure AI feature secrets (optional)

ComuniTEA’s Supabase Edge Functions use OpenAI and ElevenLabs for AI-powered features. These are not client-side environment variables — they must be set as Supabase project secrets so the Edge Functions runtime can access them:

supabase secrets set OPENAI_API_KEY=sk-...
supabase secrets set ELEVENLABS_API_KEY=...

For local audio generation with the generate:pictogram-audio script, ELEVENLABS_API_KEY can also be placed in a .env file at the project root (not .env.local). The script reads it automatically.

Available npm Scripts

All day-to-day tasks are covered by the scripts defined in package.json:

"scripts": {
  "dev": "EXPO_NO_TELEMETRY=1 expo start",
  "android": "expo start --android",
  "emulator": "emulator -avd Pixel_5",
  "build:web": "expo export --platform web",
  "lint": "expo lint",
  "typecheck": "tsc --noEmit",
  "generate:pictogram-audio": "node scripts/generate-elevenlabs-pictogram-audio.mjs",
  "test": "jest --passWithNoTests",
  "test:watch": "jest --watch"
}

npm run dev

Starts the Expo development server with telemetry disabled. Scan the QR code with Expo Go or press a to open on Android.

npm run android

Starts the dev server and immediately targets the connected Android device or running emulator.

npm run emulator

Launches the Pixel_5 Android Virtual Device. Run this before npm run android if no emulator is already running.

npm run build:web

Exports the app for the web platform using expo export --platform web. Output lands in the dist/ directory.

npm run lint

Runs ESLint via expo lint, using the flat config in eslint.config.js (based on eslint-config-expo). The dist/ directory is ignored.

npm run typecheck

Runs tsc --noEmit to validate TypeScript types across the entire project without emitting any files.

npm test

Runs the full Jest test suite. The --passWithNoTests flag means the command exits cleanly even if no tests are found yet.

npm run generate:pictogram-audio

Calls the ElevenLabs generation script to produce MP3 files for all pictograms defined in constants/AudioAssets.ts.

TypeScript Path Aliases

The tsconfig.json extends Expo’s base config and defines four path aliases for clean absolute imports:

{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@features/*": ["features/*"],
      "@stores/*":   ["stores/*"],
      "@types/*":    ["types/*"],
      "@lib/*":      ["lib/*"]
    }
  }
}

The Jest configuration in package.json includes a moduleNameMapper entry for @/ imports, plus entries for native module mocks:

"moduleNameMapper": {
  "^@/(.*)$": "<rootDir>/$1",
  "^react-native-reanimated$": "<rootDir>/node_modules/react-native-reanimated/mock",
  "^react-native-worklets(.*)$": "<rootDir>/__mocks__/react-native-worklets.js"
}

The TypeScript path aliases (@features/*, @stores/*, @types/*, @lib/*) are resolved by the TypeScript compiler and Metro bundler at build time. The Jest moduleNameMapper maps the separate ^@/(.*)$ prefix used in test imports. Note the difference: @lib/supabase is the tsconfig/Metro alias, while @/lib/supabase (with a slash) matches the Jest mapper. Use relative paths (e.g., ../../lib/supabase) in test files to avoid ambiguity, or check the mapper prefix before using bare alias imports in tests.

Supabase Local Development

ComuniTEA’s database schema is managed through Supabase migrations. To apply all pending migrations against your project (or a local Supabase instance):

# Link to your remote Supabase project
supabase link --project-ref <your-project-ref>

# Push all migrations
supabase db push

For full local development including Edge Functions, start the local Supabase stack:

supabase start

This spins up a local Postgres instance, the Auth server, Storage, and the Edge Functions runtime — all matching the production Supabase environment. Update .env.local to point at the local URLs printed by supabase start.

Supabase Edge Functions in supabase/functions/ are excluded from the TypeScript project ("exclude": ["supabase/functions"] in tsconfig.json) because they run in the Deno runtime, not Node.js. They have their own type environment and do not participate in npm run typecheck.

Adding New Pictogram Audio

When vocabulary is expanded, the corresponding MP3 files must be generated before the app can play them. ComuniTEA ships a dedicated Node.js script:

# Generate audio for all pictograms (both voice profiles)
npm run generate:pictogram-audio

# Generate only the feminine voice profile
node scripts/generate-elevenlabs-pictogram-audio.mjs --profile femenina

# Generate only the masculine voice profile
node scripts/generate-elevenlabs-pictogram-audio.mjs --profile masculina

# Preview what would be generated without making API calls
node scripts/generate-elevenlabs-pictogram-audio.mjs --dry-run

# Regenerate a single pictogram (force-overwrites if it exists)
node scripts/generate-elevenlabs-pictogram-audio.mjs --id desayuno --profile both --force

# Add a delay between API calls (default is 400 ms)
node scripts/generate-elevenlabs-pictogram-audio.mjs --delay-ms 600

The script reads the pictogram registry from constants/AudioAssets.ts, resolves the natural-language phrase for each pictogram ID using scripts/lib/build-pictogram-phrases.mjs, then calls the ElevenLabs Text-to-Speech API. Generated MP3 files are written to:

assets/audio/femenina/<category>/<id>.mp3
assets/audio/masculina/<category>/<id>.mp3

Two voice profiles are pre-configured:

Profile	Voice	ElevenLabs Voice ID
`femenina`	Samanta	`qBvury71WUJfVeT1STkG`
`masculina`	Luis	`WEXRePkZGpmcFLvCOaB1`

The model defaults to eleven_multilingual_v2 and can be overridden with the ELEVENLABS_MODEL environment variable.

After adding new audio files, clear the Metro bundler cache so the new assets are picked up:

npx expo start -c

Metro caches asset resolution aggressively. The -c flag clears the cache and forces a full re-bundle, ensuring newly added MP3s are included in the dev build.

Data & State

Feature Modules

Development

Local Development Setup for ComuniTEA Contributors

Prerequisites

Node.js 18+

Expo Go

Android Emulator (optional)

Supabase Account

Environment Setup

Available npm Scripts

npm run dev

npm run android

npm run emulator

npm run build:web

npm run lint

npm run typecheck

npm test

npm run generate:pictogram-audio

TypeScript Path Aliases

Supabase Local Development

Adding New Pictogram Audio

Build docs developers (and LLMs) love

Data & State

Feature Modules

Development

Documentation Index

​Prerequisites

Node.js 18+

Expo Go

Android Emulator (optional)

Supabase Account

​Environment Setup

​Available npm Scripts

npm run dev

npm run android

npm run emulator

npm run build:web

npm run lint

npm run typecheck

npm test

npm run generate:pictogram-audio

​TypeScript Path Aliases

​Supabase Local Development

​Adding New Pictogram Audio

Build docs developers (and LLMs) love

Prerequisites

Environment Setup

Available npm Scripts

TypeScript Path Aliases

Supabase Local Development

Adding New Pictogram Audio