Quickstart

Get MC World Compressor running locally in minutes

Get Started

Follow this guide to set up and run MC World Compressor on your local machine. You’ll have the application running in under 5 minutes.

This quickstart covers the frontend setup. You’ll need a running backend instance to fully test world compression. The backend URL should be configured via environment variables.

Prerequisites

Before you begin, make sure you have:

• Node.js 18+ installed (Download Node.js)
• npm, yarn, or pnpm package manager
• Git for cloning the repository
• A backend instance URL (or run the backend locally)

Installation Steps

1. Clone the Repository

   Clone the MC World Compressor frontend repository from GitHub:

   git clone https://github.com/MC-World-Compressor/Frontend.git
   cd Frontend
   

   This will download the source code and navigate into the project directory.

2. Install Dependencies

   Install the required npm packages using your preferred package manager:

   npm

   npm install
   

   This will install:

   • Next.js 16+ - React framework
   • React 19 - UI library
   • TailwindCSS 4 - Styling framework
   • next-sitemap - Sitemap generation
3. Configure Environment Variables

   Create a .env file in the root directory by copying the example file (if available) or creating it manually:

   touch .env
   

   Add the following environment variable to your .env file:

   .env

   NEXT_PUBLIC_BACKEND_URL=https://your-backend-url.com
   

   Replace https://your-backend-url.com with your actual backend URL.

   HTTPS Requirement: If your frontend is served over HTTPS (e.g., deployed on Vercel), your backend must also use HTTPS. Browsers block HTTP requests from HTTPS sites due to mixed content security policies.

   Why NEXT_PUBLIC_ prefix?

   In Next.js, environment variables prefixed with NEXT_PUBLIC_ are exposed to the browser. This is necessary because the frontend makes direct API calls to the backend from the client side.

   Variables without this prefix are only available server-side.

4. Run the Development Server

   Start the Next.js development server:

   npm

   npm run dev
   

   The application will start on http://localhost:3000.

   The development server supports hot reload - your changes will automatically appear in the browser without manual refresh!

5. Open in Browser

   Navigate to http://localhost:3000 in your web browser.

   You should see the MC World Compressor homepage with:

   • Welcome message and compression statistics
   • Upload button
   • “How it works” section
   • FAQ section

Verify Installation

Once the application is running, verify that everything works:

Check the Homepage

Visit http://localhost:3000 and ensure:

• The page loads without errors
• The navigation bar appears
• The language selector works (EN/ES/HI/AR)
• The “Compress Now” button is visible

Test Language Switching

Click the language selector in the navigation bar and switch between:

• English (EN)
• Spanish (ES)
• Hindi (HI)
• Arabic (AR)

The page content should update to reflect the selected language.

Navigate to Upload Page

Click the “Compress Now” or “Upload” button to navigate to /en/upload (or your selected language).

You should see:

• File upload dropzone
• Drag-and-drop area
• File format instructions (.zip, .tar, .tar.gz)
• World structure examples

Backend Connection: The upload functionality will only work if your backend is running and properly configured in the .env file. Without a valid backend, uploads will fail.

Build for Production

When you’re ready to deploy or test a production build:

1. Build the Application

   Create an optimized production build:

   npm

   npm run build
   

   This will:

   • Compile and optimize all pages
   • Generate static assets
   • Create a sitemap (via next-sitemap)
2. Start the Production Server

   Run the production server:

   npm

   npm start
   

   The production build will be available at http://localhost:3000.

Environment Configuration

Required Variables

NEXT_PUBLIC_BACKEND_URL · string · required

The URL of your backend server that handles file uploads and compression.

Example: https://api.mccompressor.com

Must use HTTPS if your frontend is served over HTTPS (e.g., on Vercel).

Backend Requirements

Your backend must:

• Accept POST requests to /api/subir for chunked file uploads
• Support multipart/form-data uploads
• Handle files up to 4GB in size
• Integrate with the thanos library
• Return job/server IDs for status tracking

Common Issues

HTTPS Mixed Content Error

Error: “Mixed content” or “blocked by CORS”

Solution: Ensure your backend uses HTTPS if the frontend is served over HTTPS. Update NEXT_PUBLIC_BACKEND_URL to use https:// instead of http://.

Backend Connection Failed

Error: Upload fails or times out

Solution:

1. Verify the backend URL in .env is correct
2. Check that the backend server is running
3. Test the backend API endpoint directly using curl or Postman
4. Check CORS configuration on the backend

Port Already in Use

Error: “Port 3000 is already in use”

Solution: Either stop the process using port 3000, or run Next.js on a different port:

PORT=3001 npm run dev

Module Not Found

Error: “Cannot find module” or “Module not found”

Solution: Delete node_modules and reinstall:

rm -rf node_modules
npm install

Project Structure

Understanding the project structure helps you navigate the codebase:

Frontend/
├── app/
│   └── [locale]/              # Internationalized routes
│       ├── page.js            # Homepage (app/[locale]/page.js:1)
│       ├── upload/
│       │   └── page.js        # Upload page (app/[locale]/upload/page.js:1)
│       └── status/
│           └── [id]/
│               └── page.js    # Status tracking page
├── lib/
│   └── translations.js        # i18n translation utilities
├── public/
│   └── assets/                # Static assets and images
├── .env                       # Environment variables (create this)
├── package.json               # Dependencies and scripts
└── next.config.js             # Next.js configuration

Key Files

Homepage

Location: app/[locale]/page.js:1

Main landing page with compression info, examples, and FAQ.

Upload Page

Location: app/[locale]/upload/page.js:1

File upload interface with drag-and-drop and chunked transfer.

Translations

Location: lib/translations.js

Multi-language translation system for EN/ES/HI/AR.

Package Config

Location: package.json:1

Dependencies: Next.js 16+, React 19, TailwindCSS 4.

Next Steps

Now that you have MC World Compressor running locally, explore these topics:

Development Setup

Deep dive into the development environment and best practices.

Configuration Guide

Learn about all available configuration options.

Understanding Compression

How the compression algorithm works under the hood.

Deployment Guide

Deploy your instance to production (Vercel, AWS, etc.).

File Upload Component

Understand the chunked file upload implementation.

Internationalization

Add new languages or modify existing translations.

Need Help? Check the GitHub Issues or create a new issue if you encounter problems.