Next.js + NestJS + Expo Monorepo Template

A modern full-stack, type-safe monorepo template with real-time capabilities and cross-platform support.

Demo · Report Bug · Request Feature

✨ Features

• 📦 Monorepo Setup: Turborepo with pnpm for efficient workspace management
• 🔄 Full Type Safety: End-to-end type safety from backend to frontend with tRPC and typed WebSockets
• 🚀 Modern Stack: Next.js, NestJS, and Expo with TypeScript
• 🔌 Real-time Communication: Type-safe WebSockets integration with Socket.IO
• 👤 Authentication: Clerk integration for secure user management
• 📊 Analytics: PostHog integration for tracking user behavior
• 🎨 UI Components: TailwindCSS with ShadCN UI for web and Tamagui for mobile
• 🧩 Modular Architecture: Well-organized packages for code sharing

🚀 Quick Start

Prerequisites

• Node.js (v18+)
• PostgreSQL
• pnpm (npm install -g pnpm)

One-click Setup

# Clone the repository
git clone https://github.com/barisgit/nextjs-nestjs-expo-template.git
cd nextjs-nestjs-expo-template

# Install dependencies
pnpm i # or pnpm install

# Run the development setup script 
# This command handles:
#  - Copying .env files
#  - Setting up database (Docker or manual)
#  - Setting up Redis (Docker)
#  - Running database migrations
#  - Seeding the database
pnpm dev:setup

# NOTE: Ensure Docker is running if you rely on the default Docker setup for PostgreSQL and Redis.
# The script will prompt you for necessary details or use .env files if they exist.

# Start all development servers (Backend, Web, Mobile)
pnpm dev

# Or run individual servers:
# pnpm dev:backend # NestJS
# pnpm dev:web     # Next.js
# pnpm dev:mobile  # Expo

📂 Project Structure

nextjs-nestjs-expo-template/
├── apps/
│   ├── backend/     # NestJS API server
│   ├── web/         # Next.js web application
│   └── mobile/      # Expo React Native application
├── packages/
│   ├── analytics/   # PostHog analytics integration
│   ├── db/          # Database models and TypeORM configuration
│   ├── services/    # Shared services (auth, redis, webhooks)
│   ├── trpc/        # tRPC API router definitions and context
│   ├── ui/          # Shared UI components (ShadCN UI for web)
│   ├── websockets/  # Type-safe WebSocket implementation
│   ├── eslint-config/ # Shared ESLint configuration
│   └── typescript-config/ # Shared TypeScript configuration

🖥️ Tech Stack

Backend

• NestJS: A progressive Node.js framework for scalable server-side applications
• TypeORM: ORM for TypeScript and JavaScript with PostgreSQL
• Socket.IO: Real-time bidirectional event-based communication with type safety
• PostgreSQL: Open-source relational database

Frontend

• Next.js: React framework for production-grade applications
• TailwindCSS: Utility-first CSS framework
• ShadCN UI: Beautifully designed components built with Radix UI and Tailwind CSS
• TanStack Query: Data fetching and caching library

Mobile

• Expo: Platform for making universal React applications
• React Native: Framework for building native apps using React
• Tamagui: UI library for React Native with performance and developer experience in mind

Common

• TypeScript: Typed superset of JavaScript
• tRPC: End-to-end typesafe APIs
• Turborepo: High-performance build system for JavaScript/TypeScript monorepos
• Clerk: Authentication and user management
• PostHog: Open-source product analytics platform

📖 Documentation

Each package and application contains its own detailed documentation:

• Backend Documentation
• Mobile Documentation
• Analytics Package
• Database Package
• Services Package
• tRPC Package
• UI Package
• WebSockets Package

💡 Usage Examples

Type-safe API with tRPC

// Client component
function UserProfile() {
  const { data, isLoading } = trpc.users.getProfile.useQuery();
  
  if (isLoading) return <div>Loading...</div>;
  
  return (
    <div>
      <h1>Welcome, {data.name}!</h1>
    </div>
  );
}

Type-safe Real-time Communication

// WebSocket setup with type safety
import { createTypedSocketClient, ClientEvents, ServerEvents } from '@repo/websockets';

const socket = createTypedSocketClient('http://your-api-url');
socket.emit(ClientEvents.JOIN_ROOM, roomId);

// Listen for messages with full type safety
socket.on(ServerEvents.MESSAGE, (message) => {
  console.log('New message:', message);
});

🛠️ Development Scripts

This project includes several helpful scripts for development and maintenance, located in the scripts/ directory.

Environment Variable Inspection

pnpm inspect:envs

This command scans the apps/ and packages/ directories for all .env* files (e.g., .env, .env.local, .env.example). It then prints the key-value pairs found in each file, grouped by project (app or package).

This is useful for:

• Verifying that all necessary environment variables are present in example files.
• Quickly checking the configured values across different environments.
• Debugging environment-related issues.

The script is powered by the EnvManager utility (scripts/utilities/env-manager.ts), which is designed to parse .env files while preserving comments and whitespace, making it useful for both reading and programmatically modifying environment configurations.

🤝 Contributing

Contributions are what