Safe{Wallet} monorepo

🌐 Safe{Wallet} web app ・ 📱 Safe{Wallet} mobile app

Overview

Welcome to the Safe{Wallet} monorepo! Safe (formerly Gnosis Safe) is a multi-signature smart contract wallet for Ethereum and other EVM chains, requiring multiple signatures to execute transactions.

This repository houses both web and mobile applications along with shared packages, managed under a unified structure using Yarn Workspaces. The monorepo setup simplifies dependency management and ensures consistent development practices across projects.

Key components

• apps/web - Next.js web application (detailed documentation)
• apps/mobile - Expo/React Native mobile application (detailed documentation)
• packages/store - Shared Redux store used by both platforms
• packages/utils - Shared utilities and TypeScript types
• config/ - Shared configuration files

[!IMPORTANT]

For detailed setup instructions and platform-specific development guides, please refer to the dedicated README files:

• Web App Documentation - Complete guide for the Next.js web application
• Mobile App Documentation - Complete guide for the mobile application, including iOS/Android setup

Getting started

To get started, ensure you have the required tools installed and follow these steps:

Prerequisites

• Node.js: Install the latest stable version from Node.js.
• Yarn: Use Yarn version 4.5.3 or later

to install it with the latest node version you can simply do

corepack enable

and then just run

yarn

This will install the required version of yarn and resolve all dependencies.

[!NOTE]

Corepack is a tool to help with managing versions of your package managers. It exposes binary proxies for each supported package manager that, when called, will identify whatever package manager is configured for the current project, download it if needed, and finally run it.

Initial setup

1. Clone the repository:

git clone <repo-url>
cd monorepo

2. Install dependencies:

yarn install

Quick start commands

# Run web app in development mode
yarn workspace @safe-global/web dev

# Run mobile app in development mode
yarn workspace @safe-global/mobile start

# Run tests for web
yarn workspace @safe-global/web test

# Run Storybook for web
yarn workspace @safe-global/web storybook

[!TIP]

For comprehensive setup instructions, environment variables, testing, and platform-specific workflows, see:

• Web App README - Environment setup, Cypress E2E tests, Storybook, and more
• Mobile App README - iOS/Android setup, Maestro E2E tests, Expo configuration, and more

Monorepo commands

Here are some essential commands to help you navigate the monorepo:

Workspace management

• Run a script in a specific workspace:

yarn workspace <workspace-name> <script>

Example:

yarn workspace @safe-global/web dev

• Add a dependency to a specific workspace:

yarn workspace <workspace-name> add <package-name>

• Remove a dependency from a specific workspace:

yarn workspace <workspace-name> remove <package-name>

[!Note]

Yarn treats commands that contain a colon as global commands. For example if you have a command in a workspace that has a colon and there isn't another workspace that has the same command, you can run the command without specifying the workspace name. For example:

yarn cypress:open

is equivalent to:

yarn workspace @safe-global/web cypress:open

Linting, formatting, and type-checking

• Run ESLint across all workspaces:

yarn lint

• Run Prettier to check formatting:

yarn prettier

• Run type-check for a workspace:

yarn workspace @safe-global/web type-check
yarn workspace @safe-global/mobile type-check

Testing

• Run unit tests across all workspaces:

yarn test

• Run E2E tests (web only):

yarn workspace @safe-global/web cypress:open  # Interactive mode
yarn workspace @safe-global/web cypress:run   # Headless mode

Contributing

Adding a new workspace

1. Create a new directory under apps/ or packages/.
2. Add a package.json file with the appropriate configuration.
3. Run:

yarn install

Best practices

• Use Yarn Workspaces commands for managing dependencies.
• Ensure type-check, lint, prettier, and tests pass before pushing changes.
• Follow the semantic commit message guidelines.
• For AI contributors, see AGENTS.md for detailed guidelines.

Tools & configurations

• Husky: Pre-commit hooks for linting, formatting, and type-checking.
• ESLint & Prettier: Enforce coding standards and formatting.
• Jest: Unit testing framework.
• Cypress: E2E testing for the web app.
• Storybook: Component documentation and development for the web app.
• Expo: Mobile app framework for the mobile workspace.
• Next.js: React framework for the web workspace.
• Tamagui: UI component library for the mobile app.

Release process

For information on releasing the web app, see the Automated Release Procedure.

Useful links

• Yarn Workspaces Documentation
• Expo Documentation
• Next.js Documentation
• Storybook Documentation
• Jest Documentation
• ESLint Documentation
• Prettier Documentation
• Safe Developer Docs

Ode to the repo

In ages past when Gnosis laid the founding stone,
A vault was wrought that no single key could own.
Where signatures must gather ere the gate will yield,
M-of-N doth guard the treasure, sworn and sealed.

Now Yarn doth wind its threads through hall and bower,
Binding web and mobile in a single tower.
Redux keeps the ledger, RTK Query rides afar,
Returning with the fetched gold beneath the evening star.

Chain by chain the watchers set their vigil wide,
Across th' EVM kingdoms, ever at the Safe's own side.
Storybook doth chronicle each component's tale,
And Cypress walks the paths where lesser tests would fail.

No `any` types shall darken these well-guarded lands —
That ancient law doth hold by Prettier's own hands.
Feature flags like waypoints mark what lies ahead,
And lazy loads awaken only where the road doth tread.

Long the name hath wandered — Gnosis once, now Safe it stands,
Yet still the vow endureth, written into typed commands:
That what you hold stays guarded, deep beyond all theft or flame,
For this the codebase liveth — and security its name.

---

If you have any questions or run into issues, feel free to open a discussion or contact the maintainers. Happy coding! 🚀