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 format

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