RealWorld: A Full-Stack Example Application with Modern Web Technologies

RealWorld is a comprehensive full-stack example application that demonstrates how to build a Medium.com clone using various modern web technologies. The project showcases best practices in building real-world applications with a focus on maintainability, scalability, and developer experience.

The application provides a complete blogging platform with features including user authentication, article creation and management, commenting system, user profiles, and social interactions like following users and favoriting articles. Built using a modern tech stack including Next.js, Prisma ORM, and Astro for documentation, it demonstrates practical implementations of RESTful API design, database modeling, and frontend-backend integration.

Repository Structure

.
├── api/                      # API specification and testing resources
│   ├── openapi.yml          # OpenAPI/Swagger specification
│   └── run-api-tests.sh     # API test automation script
├── apps/
│   ├── api/                 # Backend API implementation
│   │   ├── prisma/         # Database schema and migrations
│   │   ├── server/         # API routes and business logic
│   │   └── utils/          # Shared utilities and helpers
│   └── documentation/      # Documentation site built with Astro
│       ├── src/           # Documentation source files
│       └── content/       # Markdown content for docs
├── media/                  # Asset files for mobile and web
└── package.json           # Root package configuration

Usage Instructions

Prerequisites

• Node.js >= 18
• pnpm 8.9.0 or higher
• SQLite (for development database)
• Git

Installation

1. Clone the repository:

git clone https://github.com/gothinkster/realworld.git
cd realworld

2. Install dependencies:

pnpm install

3. Set up the database:

cd apps/api
pnpm prisma migrate dev
pnpm prisma db seed

4. Create a .env file in the apps/api directory:

DATABASE_URL="file:./dev.db"
JWT_SECRET="your-secret-key"

Quick Start

1. Start the development server:

pnpm dev

2. Access the application:

• API: http://localhost:3000/api
• Documentation: http://localhost:4321

More Detailed Examples

Creating an Article

// POST /api/articles
const response = await fetch('/api/articles', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({
    article: {
      title: "How to implement RealWorld",
      description: "Implementing RealWorld examples",
      body: "Article content goes here...",
      tagList: ["realworld", "tutorial"]
    }
  })
});

Troubleshooting

Common Issues

1. Database Connection Errors

Error: P1001: Can't reach database server

• Verify DATABASE_URL in .env
• Check if SQLite file exists
• Ensure proper file permissions

2. Authentication Errors

Error: 401 Unauthorized

• Verify JWT_SECRET in .env
• Check token expiration
• Ensure proper Authorization header format

Debug Mode

Enable debug logging:

DEBUG=* pnpm dev

Log files location: apps/api/.nitro/logs/

Data Flow

The application follows a RESTful architecture where the frontend communicates with the backend API, which in turn interacts with a SQLite database through Prisma ORM.

Client Request → API Routes → Business Logic → Prisma ORM → SQLite
     ↑                                            ↓
     └────────────── JSON Response ──────────────┘

Key interactions:

1. Client sends authenticated requests to API endpoints
2. API routes validate requests and handle authentication
3. Business logic processes the request using utility functions
4. Prisma ORM handles database operations
5. Response is transformed using mappers
6. JSON response is sent back to client

Infrastructure

GitHub Actions

• CodeQL Analysis: Weekly security scanning for JavaScript code
• Dependabot: Automated dependency updates for npm packages and GitHub Actions
• Spammy Guardian: Issue monitoring and spam protection

Development Tools

• Turbo: Monorepo build system with caching and task orchestration
• pnpm: Package management with workspace support
• Prisma: Database ORM with migration support
• Nitro: Server engine for API implementation

Testing

• Postman Collection: Automated API testing suite
• Newman: CLI test runner for Postman collections