Webpack Upload Guide - Jiran Games

Back to guides

Preparing Your Webpack Game

Webpack is a powerful module bundler that can be used to build various types of web games. Our platform supports multiple Webpack output structures.

Set Up Your Webpack Project

If you haven't already, create a new Webpack project:

# Create a new directory
mkdir my-game
cd my-game

# Initialize npm
npm init -y

# Install webpack
npm install webpack webpack-cli --save-dev

# Install other dependencies as needed
npm install --save-dev html-webpack-plugin style-loader css-loader file-loader

Configure Webpack

Create a webpack.config.js file in your project root:

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist'),
    clean: true,
  },
  plugins: [
    new HtmlWebpackPlugin({
      title: 'My Game',
      template: './src/index.html',
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader'],
      },
      {
        test: /\.(png|svg|jpg|jpeg|gif|mp3|wav)$/i,
        type: 'asset/resource',
      },
    ],
  },
};

Note: This is a basic configuration. You may need to customize it based on your game's specific requirements.

Create Your Project Structure

Set up a basic project structure:

my-game/
  ├── src/
  │   ├── index.js       # Main entry point
  │   ├── index.html     # HTML template
  │   ├── game.js        # Game logic
  │   ├── styles.css     # CSS styles
  │   └── assets/        # Game assets (images, sounds, etc.)
  ├── webpack.config.js  # Webpack configuration
  └── package.json       # Project dependencies

Create a basic index.html template in the src folder:



  
    
    My Game

Build Your Game

Add a build script to your package.json:

"scripts": {
  "build": "webpack --config webpack.config.js"
}

Then run the build command:

npm run build

This will create a dist folder containing your built application with the following structure:

dist/
  ├── index.html
  ├── main.js
  └── assets/
      └── ...

Alternative Webpack Structures

Our platform also supports these alternative Webpack output structures:

Structure with JS Directory

my-game/
  ├── index.html
  ├── js/
  │   ├── main.js
  │   └── ...
  └── assets/
      └── ...

Structure with Public Directory

my-game/
  ├── public/
  │   ├── index.html
  │   ├── bundle.js
  │   └── assets/
  │       └── ...
  └── ...

Note: Our system will automatically detect your Webpack structure and serve it correctly.

Test Your Build Locally

Before uploading, test your built game to ensure everything works correctly:

# Using a simple HTTP server
npx serve dist

Check that all game features, assets, and interactions work as expected.

Zip Your Build

Compress your build folder into a ZIP file:

# On macOS/Linux
cd dist
zip -r ../my-game.zip ./*

# On Windows
# Right-click the dist folder > Send to > Compressed (zipped) folder

Important: Make sure to zip the contents of the dist folder, not the dist folder itself.

Common Issues and Solutions

Missing Assets

If your game assets (images, sounds, etc.) aren't loading:

Ensure your webpack.config.js correctly handles asset files
Check that the paths to your assets are correct
Use relative paths for all assets

Bundle Size Issues

If your bundle is too large:

Enable code splitting in Webpack
Use dynamic imports for large modules
Implement tree shaking to eliminate unused code
Optimize images and other assets

Performance Optimization

To improve your game's performance:

Enable production mode in Webpack
Use code splitting for better initial load times
Implement lazy loading for non-critical assets
Consider using a Web Worker for intensive calculations

Implementing Game Session Tracking

All games uploaded to our platform must implement session tracking functionality. This allows us to track player sessions and maintain leaderboards for your game.

Important: Your game bundle must include API calls to our session tracking endpoints. Our validation system will check for these calls during the upload process. Games without proper session tracking implementation will be rejected.

Option 1: Use Our SDK (Recommended)

The easiest way to implement session tracking is to use our JavaScript SDK. You can download the SDK here or view an example implementation.

Step 1: Install the SDK

Add our SDK script to your HTML template or import it in your JavaScript entry file:

// In your HTML template (index.html)
<script src="/sdk/game-session-tracker.js"></script>

// OR in your JavaScript entry file (index.js)
// You'll need to copy the SDK file to your src directory first
import './game-session-tracker.js';

Step 2: Initialize and use the tracker

// In your main game file
const tracker = new GameSessionTracker();

// Function to call when game ends
function handleGameOver(score) {
  tracker.endSession(score)
    .then(response => {
      console.log("Session recorded successfully", response);
    })
    .catch(error => {
      console.error("Failed to record session", error);
    });
}

// Function to display leaderboard
function showLeaderboard() {
  tracker.getLeaderboard(10)
    .then(response => {
      const leaderboard = response.data.leaderboard;
      // Display leaderboard in your UI
      console.log("Leaderboard:", leaderboard);
    })
    .catch(error => {
      console.error("Failed to fetch leaderboard", error);
    });
}

Option 2: Custom Implementation

If you prefer to implement session tracking yourself, follow these steps:

1. Parse URL parameters when your game loads:

// In your game initialization code
function initializeSession() {
  const urlParams = new URLSearchParams(window.location.search);
  const sessionData = {
    token: urlParams.get('token') || generateRandomToken(),
    appVersion: urlParams.get('appVersion') || '1.0.0',
    language: urlParams.get('language') || 'en',
    sessionStartTime: new Date()
  };
  
  return sessionData;
}

function generateRandomToken() {
  return 'player-' + Math.random().toString(36).substring(2, 15);
}

// Initialize session when game loads
const sessionData = initializeSession();

2. Send session data to our API when the game ends:

// Function to end the session and submit score
async function endSession(score) {
  const sessionEndTime = new Date();
  
  // Get the subdomain from the current hostname
  const hostname = window.location.hostname;
  const parts = hostname.split('.');
  const subdomain = parts.length > 2 ? parts[0] : '';
  
  const payload = {
    token: sessionData.token,
    session_start_time: sessionData.sessionStartTime.toISOString(),
    session_end_time: sessionEndTime.toISOString(),
    score: score,
    app_version: sessionData.appVersion,
    language: sessionData.language
  };

  // REQUIRED: This exact endpoint must be called when a game session ends
  try {
    const response = await fetch(`/api/v1/games/${subdomain}/session-ended`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });
    
    const data = await response.json();
    console.log("Session recorded successfully", data);
    return data;
  } catch (error) {
    console.error("Failed to record session", error);
    throw error;
  }
}

Testing Your Implementation

Before uploading, test your session tracking implementation:

Run your webpack dev server (e.g., yarn start or npm run start)
Add URL parameters to your local development URL (e.g., http://localhost:8080/?token=test123&appVersion=1.0.0&language=en)
Use browser developer tools to verify network requests are being made correctly

In browser developer tools, check that the POST request to /api/v1/games/:subdomain/session-ended is being made with all required parameters.

Uploading to Jiran Games

Log in to Your Account

Create a New Game

Click on "Add New Game" and fill in the required information:

Game Name
Description
Game Logo (recommended size: 512x512px)
Tags (to help users find your game)
Subdomain (this will be your game's URL: yourgame.jiran.games)

Upload Your Game Bundle

Select the ZIP file containing your Webpack build and upload it.

Note: Our system will automatically detect your Webpack build structure and serve it correctly.

Submit for Review

After uploading, your game will be marked as "pending_review". Our team will review it to ensure it meets our guidelines.

The review process typically takes 1-2 business days.