<div align="center"> <img src="https://github.com/user-attachments/assets/c1c06796-43b3-47a3-a748-3cdc3fe75358" width="500" /> <p><strong>Spread your delightful releases to the world!✨</strong></p>

</div>

Overview

Spread is an OTA (Over-the-Air) update server designed specifically for React Native applications. It enables developers to push JavaScript bundle updates to their React Native apps without requiring users to download new versions from app stores. A react-native-code-push compatible server.

Spread uses Cloudflare R2 bucket for storing bundles. You can learn more about Cloudflare R2 here

You can use this article to set Spread Host URL in react-native-code-push.

Key Features

Fully Self-hostable - Complete control over your update infrastructure
CodePush compatible - Drop-in replacement for Microsoft CodePush
Multi-platform support - iOS and Android bundle management
Environment management - Separate configurations for development, staging, and production
Version control - Track and manage different app versions
Rollback capabilities - Quickly revert to previous versions
Web dashboard - React-based admin interface

Quick Start

1. Clone the Repository

git clone https://github.com/SwishHQ/spread.git
cd spread

2. Environment Configuration

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env with your configuration:

ENV=local
APP_NAME=spread
PORT=4000

# MongoDB Configuration
MONGODB_URL=mongodb://localhost:27017
MONGODB_DATABASE=spread

# Cloudflare R2 Configuration (for bundle storage)
CLOUDFLARE_R2_ACCOUNT_ID=your_account_id
CLOUDFLARE_R2_BUCKET=your_bucket_name
CLOUDFLARE_R2_ACCESS_KEY_ID=your_access_key
CLOUDFLARE_R2_SECRET_ACCESS_KEY=your_secret_key

3. Install Dependencies

Install Go dependencies:

go mod download

Install frontend dependencies:

cd web
npm install
cd ..

4. Build the Application

Build the backend:

make build

Build the frontend:

cd web
npm run build
cd ..

5. Run the Server

Start the Spread server:

./spread serve

The server will be available at http://localhost:4000

Project Structure

├── cmd/                # Command-line interface (CLI) entrypoints
│   ├── root.go         # Root command configuration
│   ├── serve.go        # Server command
│   └── client.go       # Client/release commands
├── cli/                # CLI utilities
│   └── bundle_cli.go   # Bundle management CLI
├── config/             # Configuration management
├── middleware/         # HTTP middleware (auth, logging, etc.)
├── pkg/                # External package integrations
│   ├── cloudflare.go   # Cloudflare R2 integration
│   └── db.go           # Database connection
├── src/                # Main application source code
│   ├── controller/     # HTTP controllers (route handlers)
│   ├── model/          # Data models and schemas
│   ├── repository/     # Data access layer
│   └── service/        # Business logic and orchestration
├── types/              # Shared type definitions
├── utils/              # Utility/helper functions
├── logger/             # Logging configuration and utilities
├── exception/          # Centralized error handling
├── web/                # Frontend React application
│   ├── src/            # React source code
│   ├── public/         # Static assets
│   ├── dist/           # Built frontend assets
│   └── package.json    # Frontend dependencies
├── script/             # Build and deployment scripts
├── main.go             # Application entry point
├── go.mod              # Go module definition
├── go.sum              # Go dependency checksums
├── Makefile            # Build automation
├── Dockerfile          # Container configuration
├── .env.example        # Environment variable template
└── README.md           # This file (the one you’re reading)

Pro tip: Each directory is lovingly crafted to keep things decoupled and maintainable. Whether you’re a backend buff, a frontend fanatic, or just here for the scripts, you’ll find your happy place.

🔧 Development Setup

Local Development

Start MongoDB (if not already running):

# macOS with Homebrew
brew services start mongodb-community

# Ubuntu/Debian
sudo systemctl start mongod

# Windows
net start MongoDB

Run in development mode:

# Terminal 1: Run backend
go run *.go serve

# Terminal 2: Run frontend (in web directory)
cd web
npm run dev

Access the application:
- Backend API: http://localhost:4000
- Frontend: http://localhost:5173 (Vite dev server)

Environment Variables

| Variable | Description | Default | Required | |----------|-------------|---------|----------| | ENV | Environment (local, development, production) | local | Yes | | APP_NAME | Application name | spread | No | | PORT | Server port | 4000 | No | | MONGODB_URL | MongoDB connection string | - | Yes | | MONGODB_DATABASE | MongoDB database name | spread | Yes | | CLOUDFLARE_R2_ACCOUNT_ID | Cloudflare R2 account ID | - | Yes | | CLOUDFLARE_R2_BUCKET | Cloudflare R2 bucket name | - | Yes | | CLOUDFLARE_R2_ACCESS_KEY_ID | Cloudflare R2 access key | - | Yes | | CLOUDFLARE_R2_SECRET_ACCESS_KEY | Cloudflare R2 secret key | - | Yes |

🛠️ Building and Deployment

Building from Source

# Build the entire application
make build

# Build with specific GOOS and GOARCH
GOOS=linux GOARCH=amd64 go build -o spread-linux-amd64
GOOS=darwin GOARCH=amd64 go build -o spread-darwin-amd64
GOOS=windows GOARCH=amd64 go build -o spread-windows-amd64.exe

Docker Deployment

# Build Docker image
docker build -t spread .

# Run with Docker
docker run -p 4000:4000 --env-file .env spread

Production Deployment

Set up a production MongoDB instance
Configure Cloudflare R2 storage
Set environment variables for production
Build and deploy the application

Example production deployment with Docker Compose:

version: '3.8'
services:
  spread:
    build: .
    ports:
      - "4000:4000"
    environment:
      - ENV=production
      - MONGODB_URL=mongodb://mongo:27017
      - MONGODB_DATABASE=spread
      - CLOUDFLARE_R2_ACCOUNT_ID=${CLOUDFLARE_R2_ACCOUNT_ID}
      - CLOUDFLARE_R2_BUCKET=${CLOUDFLARE_R2_BUCKET}
      - CLOUDFLARE_R2_ACCESS_KEY_ID=${CLOUDFLARE_R2_ACCESS_KEY_ID}
      - CLOUDFLARE_R2_SECRET_ACCESS_KEY=${CLOUDFLARE_R2_SECRET_ACCESS_KEY}
    depends_on:
      - mongo
    restart: unless-stopped

  mongo:
    image: mongo:6.0
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db
    restart: unless-stopped

volumes:
  mongo_data:

Using the CLI

Installation

Install the Spread CLI globally:

# From source
go install github.com/SwishHQ/spread/cmd/spread@latest

# Or build locally
make build
sudo cp spread /usr/local/bin/

# Or use the install script
curl -fsSL https://cdn-swish.justswish.in/spread-install.sh | sh

Creating a Release

spread release \
  --remote https://your-spread-server.com \
  --auth-key YOUR_AUTH_KEY \
  --app-name my-react-native-app \
  --environment production \
  --target-version 1.2.0 \
  --os-name ios \
  --project-dir /path/to/react-native/project \
  --is-typescript true \
  --description "Bug fixes and performance improvements"

CLI Options

| Flag | Description | Required | Default | |------|-------------|----------|---------| | --remote | Spread server URL | Yes | - | | --auth-key | Authentication key | Yes | - | | --app-name | Application name | Yes | - | | --environment | Environment (development, staging, production) | Yes | - | | --target-version | Target app version | Yes | - | | --os-name | Operating system (ios, android) | Yes | - | | --project-dir | React Native project directory | No | Current directory | | --is-typescript | Is TypeScript project | No | false | | --description | Release description | No | - | | --disable-minify | Disable bundle minification | No | false | | --hermes | Enable Hermes engine | No | false |

Contributing

We welcome contributions from the community! Here's how you can help:

Development Workflow

Fork the repository

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes
Run tests:
```
go test ./...
```

Commit your changes:

git commit -m "feat: add your feature description"

Push to your fork:

git push origin feature/your-feature-name

Create a Pull Request

Code Style Guidelines

Follow Go conventions and use gofmt for formatting
Write meaningful commit messages following conventional commits
Add tests for new functionality
Update documentation for API changes
Ensure all tests pass before submitting PR

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific test
go test ./src/service -v

<div align="center"> <p>Made with 💚 by the Swish Engineering</p> </div>

Spread

Install / Use

README