IO — The Italian public services app

---

IO App — Monorepo

This repository hosts the source code of the IO mobile app and the shared packages that power it.

IO is the official app that enables Italian citizens to interact with public administration services: messages, payments, documents, and more, all in one place. It is developed and maintained by PagoPA S.p.A..

The mobile app lives in apps/main-app. The root of this repository is the Nx monorepo that groups the app together with its companion shared libraries.

---

Table of contents

• Repository structure
• Prerequisites
• Getting started
• Daily development commands
• Architecture
• Contributing
• License

---

Repository structure

io-app/
├── apps/
│   └── main-app/         # IO mobile app (React Native)
├── libs/
│   └── design-system/    # @pagopa/io-app-design-system component library
├── .github/              # CI workflows, templates, and automation
├── docs/                 # Architecture notes and additional documentation
├── patches/              # pnpm package patches
├── scripts/              # Shared tooling scripts
├── nx.json               # Nx workspace configuration
└── pnpm-workspace.yaml   # pnpm workspace definition

Each project contains its own README.md with project-specific instructions:

• apps/main-app/README.md — IO mobile app
• libs/design-system/README.md — Design system library

---

Prerequisites

Tool	Notes
Node.js	Version pinned in .node-version; use nodenv or nvm
pnpm	Managed via Corepack; version pinned in package.json
Ruby	Version pinned in apps/main-app/.ruby-version; use rbenv
Xcode	Required for iOS builds (macOS only)
Android Studio	Required for Android builds

Follow the React Native environment setup guide for your OS before proceeding.

---

Getting started

# 1. Clone the repository
git clone https://github.com/pagopa/io-app.git
cd io-app

# 2. Enable Corepack and activate pnpm
corepack enable
corepack prepare --activate

# 3. Install Ruby gems (from apps/main-app)
cd apps/main-app
gem install bundler
bundle install
cd ../..

# 4. Full project bootstrap (installs JS deps, pods, and generates code)
pnpm nx run main-app:sync

Note

main-app:sync runs pnpm install, gem setup, iOS pod install, and code generation from OpenAPI specs and localisation files. Re-run it after pulling changes that affect any of those layers.

Environment variables

Copy the appropriate .env file before running the app:

# Target the production backend
cp apps/main-app/.env.production apps/main-app/.env

# Or target the local dev API server (io-dev-api-server)
cp apps/main-app/.env.local apps/main-app/.env

---

Daily development commands

Run all commands from the repository root.

Run the app

# Start the Metro bundler
pnpm nx run main-app:start

# iOS simulator
pnpm nx run main-app:run-ios

# Android emulator (productionDebug, active architecture only)
pnpm nx run main-app:dev-run-android

Important

The Android emulator does not support hardware-backed keystore. Disable the check before running:

pnpm nx run main-app:lollipop_checks-comment

Re-enable it before committing:

pnpm nx run main-app:lollipop_checks-uncomment

Code generation

# Regenerate API models from OpenAPI specs and locale files
pnpm nx run main-app:generate

Caution

Never manually edit files under apps/main-app/definitions/. Always regenerate them with the command above.

Quality checks

# Type-check the whole workspace (no emit)
pnpm nx tsc-noemit main-app
pnpm nx tsc-noemit io-app-design-system

# Lint
pnpm nx lint main-app
pnpm nx lint io-app-design-system

# Run tests
pnpm nx run main-app:test-dev

# Run only affected projects
pnpm nx affected --target=lint,tsc-noemit

# Format code
pnpm prettify

---

Architecture

Layer	Technology
Mobile app framework	React Native + Expo modules
Language	TypeScript
State management	Redux + Redux-Saga + XState v5
UI components	@io-app/design-system (local workspace package)
Monorepo tooling	Nx + pnpm workspaces

For a deeper dive into the app architecture and feature structure, see apps/main-app/README.md.

---

Contributing

External contributions are welcome! Before you start:

1. Read CONTRIBUTING.md for the full workflow.
2. Check the open issues for known bugs and planned work.
3. Ensure all quality checks pass before opening a pull request.

---

License

MIT