Installing

Let's setup social.dev in less than 5 minutes.

Prerequisites

Before you begin, ensure you have the following installed on your development machine. These tools are essential for running social.dev and managing its dependencies efficiently.

Node.js (v20 or higher) - The JavaScript runtime that powers both the server and build tools
pnpm (v10 or higher) - Our preferred package manager for its speed and efficiency - Installation guide
Docker (optional, for local development) - Simplifies running PostgreSQL and S3-compatible storage locally
Git (for cloning repositories) - Version control system for accessing the source code

Quickstart

We're working on this

We are developing a CLI tool to bootstrap your project, to make it even easier to get going. In the mean time, you can follow the manual steps below. The CLI will automatically handle configuration, dependencies, and provide interactive setup options.

The steps below will allow you to start building locally with minimal configuration. Once you're ready to deploy your application to production, please navigate to our comprehensive deployment guides for platform-specific instructions.

React Native Apps

Building a social experience for mobile? social.dev provides a complete React Native SDK with pre-built UI components and hooks that integrate seamlessly with your existing app or can be used to create a new one from scratch.

1. Create your project (optional)

If you're starting fresh, we recommend using Expo for the smoothest development experience. Expo provides excellent tooling, over-the-air updates, and simplified deployment.

Skip this step if you already have a React Native app set up

npx create-expo-app@latest MySocialApp --template blank-typescript
cd MySocialApp

This creates a new TypeScript-based React Native project with Expo configured and ready to go.

2. Install dependencies

Add the social.dev React Native SDK to your project. This SDK includes all the components, hooks, and utilities you need to build a full-featured social application.

pnpm i --save @social.dev/rn-sdk

The SDK includes:

Pre-built screens for authentication, feeds, profiles, and messaging
Customizable UI components that follow platform design guidelines
Hooks for accessing user data, posts, and real-time updates
Automatic handling of authentication tokens and API communication

3. Add to your app

Open your main App.tsx file and integrate social.dev. The provider component handles all the configuration and makes the SDK features available throughout your app.

Replace the contents with the following code, making sure to update the apiBaseUrl to point to your social.dev server instance:

import { SocialDevApp, SocialDevProvider } from '@social.dev/rn-sdk';

export default function App() {
  return (
    <SocialDevProvider apiBaseUrl="https://demo.social.dev/api">
      <SocialDevApp />
    </SocialDevProvider>
  );
}

The SocialDevProvider component:

Manages authentication state and token refresh
Provides context for all child components
Handles WebSocket connections for real-time features
Configures theming and localization

The SocialDevApp component provides a complete social app UI out of the box, including navigation, screens, and all standard social features.

4. Run your app

Start the development server to see your app in action. Expo provides multiple ways to test your application:

# Standard development server
pnpm start

# Use tunnel for easier device testing (bypasses network restrictions)
pnpm start --tunnel

Testing options:

Expo Go App (Recommended): Download from the App Store or Google Play, then scan the QR code shown in your terminal
iOS Simulator: Press i in the terminal (macOS only, requires Xcode)
Android Emulator: Press a in the terminal (requires Android Studio)
Physical Device: Use the tunnel option for easier connectivity across networks

We strongly recommend using the Expo Go app for the fastest development experience. It provides instant reloading and doesn't require native build tools.

Server

The social.dev server powers your backend, handling authentication, data storage, real-time communications, and API endpoints. It's built on Node.js and designed to be highly scalable and customizable.

Our Server SDK has been designed to integrate seamlessly into an existing Express.js server or run standalone. The modular architecture allows you to use only the features you need.

Required Dependencies

You will need the following services running (either locally or using managed cloud services):

PostgreSQL - Primary database for user data, posts, and relationships
S3-Compatible Storage - For media uploads, profile pictures, and attachments

For local development, we provide a Docker Compose configuration that sets up everything you need. For production, you can use managed services like AWS RDS and S3, or any compatible alternatives.

1. Docker Compose Setup

First, create a .env file in your project root with your configuration. This file contains sensitive information and should never be committed to version control:

# Database Configuration
POSTGRES_USER=postgres
POSTGRES_PASSWORD=example  # Change this in production!
POSTGRES_DB=socialdev

# Server Configuration
SOCIAL_DEV_SERVER_PORT=3000

# Optional: S3 Configuration for MinIO
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin  # Change this in production!

Now create a docker-compose.yml file that defines all the services needed for local development:

networks:
  internal:
    external: false

services:
  # Reverse proxy for handling HTTPS and routing
  web:
    image: caddy:2-alpine
    restart: always
    ports:
      - '80:80'
      - '443:443'
    environment:
      - SOCIALDEV_HOST=localhost
      - SOCIALDEV_WEBAPP_URL=http://host.docker.internal:8081
      - SOCIALDEV_SERVER_URL=http://host.docker.internal:3000
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    networks:
      - internal
    depends_on:
      - postgres
      - kafka

  # PostgreSQL Database
  postgres:
    image: postgres:15-alpine
    restart: always
    env_file: ./.env
    environment:
      PGUSER: $POSTGRES_USER
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - '5432:5432'
    networks:
      - internal
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready']
      interval: 1s
      timeout: 5s
      retries: 10

  # S3-compatible object storage
  file-storage:
    command: ['server', '/data', '--console-address', ':38853']
    image: quay.io/minio/minio
    restart: always
    env_file: ./.env
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    volumes:
      - ./.storage:/data
    ports:
      - '9000:9000' # S3 API
      - '38853:38853' # Web Console

  kafka:
    image: apache/kafka:latest
    container_name: broker
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT_HOST://localhost:9092,PLAINTEXT://kafka:19092'
      KAFKA_PROCESS_ROLES: 'broker,controller'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka:29093'
      KAFKA_LISTENERS: 'CONTROLLER://:29093,PLAINTEXT_HOST://:9092,PLAINTEXT://:19092'
      KAFKA_INTER_BROKER_LISTENER_NAME: 'PLAINTEXT'
      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
    networks:
      - internal
    volumes:
      - kafka-data:/var/lib/kafka/data
    ports:
      - 9092:9092

  kafka-ui:
    container_name: kafka-ui
    image: provectuslabs/kafka-ui:latest
    networks:
      - internal
    ports:
      - 9093:8080
    environment:
      DYNAMIC_CONFIG_ENABLED: 'true'
      KAFKA_CLUSTERS_0_NAME: kafka
      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:19092
    depends_on:
      - kafka

volumes:
  postgres-data:
  caddy-data:
  caddy-config:
  kafka-data:

Start all services with a single command:

docker compose up

This will:

Start PostgreSQL on port 5432
Start MinIO (S3-compatible storage) on port 9000
Start Caddy reverse proxy on ports 80/443
Start Kafka (event streams) on port 9092
Create persistent volumes for data storage
Set up networking between containers

You can access:

MinIO Console: http://localhost:38853
PostgreSQL: localhost:5432
Kafka UI: http://localhost:9093
Your app: http://localhost (once server is running)

2. Install Dependencies

Add the social.dev server SDK to your Node.js project:

pnpm i @social.dev/server-sdk

The server SDK provides:

Complete REST API with OpenAPI documentation
WebSocket support for real-time features
Authentication and authorization middleware
Database models and migrations
File upload handling
Extensible plugin system

3. Setup your server

Create a new file called index.js with your server configuration:

// Initialise the server
import('@social.dev/server-sdk/bootstrap').then(({ bootstrap }) => {
  bootstrap({
    auth: {
      methods: [AuthMethodEnum.Password],
    },
    network: {
      domainAliasMap: {
        localhost: 1,
      },
    },
  });
});

4. Run the server

Start your server with Node.js:

node index.js

For development with auto-reload:

# Install nodemon if you haven't already
pnpm i -D nodemon

# Run with nodemon
nodemon index.js

Your server is now running! You can:

Access the API at https://localhost/api
View API documentation at https://localhost/schema
Connect your React Native app to https://localhost

The server automatically:

Creates database tables on first run
Sets up default data and admin user
Generates API documentation
Handles CORS for local development

Getting Started, for Contributors

Advanced flow

This section is for developers who want to contribute to social.dev or need to modify the core framework. Most users should follow the Quickstart guide above instead.

If you're planning to contribute to social.dev or need to customize the framework itself, follow these steps to set up the full development environment.

1. Clone this repository

Get the latest source code from GitHub:

git clone [email protected]:socialdotdev/social.dev.git && cd social.dev

The repository is organized as a monorepo with the following structure:

apps/ - Example applications and demos
packages/ - Core SDK packages
plugins/ - Optional plugin modules
docs/ - Documentation site

2. Install dependencies

PNPM is required for managing packages due to its excellent monorepo support and workspace features:

pnpm i

This will install all dependencies for all packages and set up workspace links between them.

3. Setup docker

Docker Compose is configured to provide all the infrastructure needed for development:

docker compose up

This starts:

Caddy - Reverse proxy with automatic HTTPS
PostgreSQL - Primary database
MinIO - S3-compatible object storage
Redis (optional) - Caching and pub/sub

4. Build the SDK and plugins

The SDKs need to be built in watch mode for development. Open separate terminal windows for each:

# Terminal 1: JavaScript SDK
cd packages/js-sdk && pnpm dev

# Terminal 2: React Native SDK
cd packages/rn-sdk && pnpm dev

# Terminal 3: Server SDK
cd packages/server-sdk && pnpm dev

# Terminal 4: AI Plugin (optional)
cd plugins/ai && pnpm dev

Each command runs in watch mode, automatically rebuilding when you make changes to the source code.

Run the server

In a new terminal, start the example server application:

cd apps/server && pnpm dev

The server will:

Auto-reload on code changes
Provide detailed logging
Enable debugging features
Serve API documentation

Run expo

Start the example React Native application:

cd apps/mobile && pnpm dev

You can then:

Launch an iOS/Android emulator
Use Expo Go app to scan the QR code
Access via web browser (limited functionality)

Access the web app

Once everything is running, visit https://localhost to see the web interface. The Caddy proxy handles SSL certificates automatically for local development.

Troubleshooting

If you encounter issues during installation:

Port conflicts: Ensure ports 3000, 5432, 9000 are available
Docker issues: Try docker compose down -v to reset volumes
Permission errors: Check file ownership and npm/pnpm permissions
Network issues: Use --tunnel flag for Expo on restricted networks

For more help, visit our GitHub Issues or join our Discord community.

Prerequisites​

Quickstart​

React Native Apps​

1. Create your project (optional)​

2. Install dependencies​

3. Add to your app​

4. Run your app​

Server​

Required Dependencies​

1. Docker Compose Setup​

2. Install Dependencies​

3. Setup your server​

4. Run the server​

Getting Started, for Contributors​

1. Clone this repository​

2. Install dependencies​

3. Setup docker​

4. Build the SDK and plugins​

Run the server​

Run expo​

Access the web app​

Troubleshooting​

Prerequisites

Quickstart

React Native Apps

1. Create your project (optional)

2. Install dependencies

3. Add to your app

4. Run your app

Server

Required Dependencies

1. Docker Compose Setup

2. Install Dependencies

3. Setup your server

4. Run the server

Getting Started, for Contributors

1. Clone this repository

2. Install dependencies

3. Setup docker

4. Build the SDK and plugins

Run the server

Run expo

Access the web app

Troubleshooting