@smoud/scripts

The Ultimate Build Tool for HTML5 Games

@smoud/scripts is a powerful build tool for HTML5 games, designed to streamline development, optimization, and packaging for multiple platforms, including web browsers, game portals (CrazyGames, Poki, ...), social media (Facebook, Snapchat, TikTok, ...), mobile, and Web3/blockchain platforms. This tool provides a one-command solution to handle platform-specific requirements, asset optimization, and build automation.

Features

• 🚀 One-Command Build Process – Easily generate builds for different platforms.
• ⚡ Automatic Optimizations – Includes minification, tree-shaking, and dead code elimination.
• 🎯 Pre-configured for Major Platforms – Works out of the box with web browsers, game portals, social media platforms, mobile platforms, and Web3/blockchain platforms.
• 🛠️ Customizable – Extend the default build pipeline as needed.

Installation

npm install --save-dev @smoud/scripts

Quick Start

1. Install the package
2. Create a basic project structure:

your-game/
  ├── src/
  │   ├── index.html
  │   └── index.ts
  ├── package.json
  └── build.json (optional)

3. Add scripts to your package.json:

{
  "scripts": {
    "dev": "smoud-scripts dev",
    "build": "smoud-scripts build"
  }
}

4. Start development:

npm run dev

5. Build for a specific platform:

npm run build browser

CLI Arguments

| Option | Description | Default | Example | | ------------------------- | ---------------------------------------- | ------------------ | -------------------------------------- | | Platform | Target platform | browser | poki | | --name | Project name | from package.json | --name MyGame | | --version | Project version | from package.json | --version 1.0.0 | | --out-dir | Output directory for build files | build/{platform} | --out-dir build/{version}/{platform} | | --static-dir | Source directory of static build files | static | --static-dir public | | --build-config | Path to build.json configuration file | build.json | --build-config custom.json | | --ts-config | Path to tsconfig.json configuration file | tsconfig.json | --ts-config tsconfig.prod.json | | --js-config | Path to jsconfig.json configuration file | jsconfig.json | --js-config jsconfig.prod.json | | --port | Development server port number | 3000 | --port 8080 | | --open | Open browser automatically | false | --open | | --dev | Enable development mode | true | --dev false | | --skip-recommended-meta | Skip recommended meta tags injection | false | --skip-recommended-meta | | --debugger | URL of debugger script to inject | - | --debugger https://... |

Target Platform

Specify the target platform directly as a command argument:

smoud-scripts build poki

Supported Platforms

• Web Browsers

  • browser - Standard web browser

• Web-Based Game Portals

  • crazygames - CrazyGames
  • poki - Poki
  • kongregate - Kongregate
  • newgrounds - Newgrounds
  • y8 - Y8
  • gamedistribution - GameDistribution
  • miniclip - Miniclip

• Indie-Focused & Pay-What-You-Want Platforms

  • itch - itch.io
  • gamejolt - Game Jolt
  • simmer - Simmer.io

• Mobile Platforms (via WebView or PWA)

  • googleplay - Google Play
  • appstore - App Store
  • galaxystore - Galaxy Store
  • amazonappstore - Amazon Appstore

• Social Media & Messenger Games

  • facebook - Facebook
  • snapchat - Snapchat
  • wechat - WeChat
  • tiktok - TikTok
  • telegram - Telegram

• Web3 & Blockchain-Based Platforms

  • sandbox - The Sandbox
  • opgames - OP Games
  • immutablex - Immutable X

Supported Languages

• auto, en, es, zh, hi, ar, fr, de, ja, pt, it, ko, tr, nl, sv, pl, uk, id, vi

Build Configuration (build.json)

The build.json file allows you to customize build options. Here's the format:

{
  "outDir": "dist/{platform}",
  "name": "MyGame",
  "version": "1.2.0",
  "language": "en"
}

All fields are optional and will use the default values if not specified.

Output directory name template

The outDir template (specified with --out-dir option) supports the following variables:

• {name} - Project name
• {version} - Project version
• {language} - Language code
• {platform} - Target platform
• {date} - Current date
• {hash} - Unique build identifier

Example: --out-dir "build/{name}_{version}_{platform}"

Meta Tags

Unless --skip-recommended-meta is provided, the following recommended for mobile platforms meta tags are automatically injected:

<meta name="HandheldFriendly" content="True" />
<meta name="cleartype" http-equiv="cleartype" content="on" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="mobile-web-app-capable" content="yes" />
<meta http-equiv="X-UA-Compatible" content="IE=10" />

Examples

Development

Start development server:

smoud-scripts dev --port 3000 --open

Building

Build for browser:

npx smoud-scripts build browser

npm run build browser

Build for Poki:

npx smoud-scripts build poki

npm run build poki

Build for Facebook:

npx smoud-scripts build facebook

npm run build facebook

API Reference

The package provides a programmatic API for integration into your build tools:

Default Options

const options = {
  // CLI options
  name: '', // Project name (default from package.json)
  version: '', // Project version (default from package.json)
  outDir: 'build/{platform}', // Output directory for build files
  staticDir: 'static', // Source directory of static build files
  buildConfig: 'build.json', // Path to build.json configuration file
  tsConfig: 'tsconfig.json', // For TypeScript projects, path to tsconfig.json file
  jsConfig: 'jsconfig.json', // For JavaScript projects, path to jsconfig.json file
  port: 3000, // Development server port number
  open: false, // Whether to open browser automatically
  platform: 'browser', // Target platform
  language: 'auto', // Target language
  dev: undefined, // Development mode flag
  skipRecommendedMeta: undefined, // Skip recommended meta tags injection
  debugger: undefined, // URL of debugger script to inject

  // Defines options (automatically generated from CLI options)
  defines: {
    __DEV__: false, // Development mode flag
    PLATFORM: '...', // Current platform identifier
    LANGUAGE: '...' // Current language code
  }
};

Configuration

const { options, mergeOptions, parseArgvOptions } = require('@smoud/scripts');

// Merge custom options with defaults
const customOptions = mergeOptions(options, {
  outDir: 'custom-dist',
  platform: 'poki'
});

// Parse CLI arguments
const newOptions = parseArgvOptions([
  {
    name: 'custom-option',
    hasValue: true,
    defaultValue: 'default'
  }
]);

// Change options
newOptions.platform = 'crazygames';
newOptions.version = '1.0.5';

// Change defines options
newOptions.defines = {
  CUSTOM_DEFINE: JSON.stringify('custom value'),
  __DEV__: JSON.stringify(false)
};

// Merge new options with defaults
const finalOptions = mergeOptions(options, newOptions);

Webpack Configuration

const { makeWebpackDevConfig, makeWebpackBuildConfig } = require('@smoud/scripts');
const { webpackCommonConfig } = require('@smoud/scripts');
const { merge } = require('webpack-merge');

// Create development configuration
const devConfig = makeWebpackDevConfig(customOptions);

// Create production configuration
const buildConfig = makeWebpackBuildConfig();

// Create production configuration with custom definitions
const buildConfig2 = makeWebpackBuildConfig(customOptions, customDefinitions);

// Create production configuration with custom definitions and custom webpack config to merge
const buildConfig3 = makeWebpackBuildConfig(customOptions, customDefinitions, customWebpackConfig);

// Create your own webpack config, based on webpackCommonConfig
const customConfig = merge(webpackCommonConfig, {
  // ...
});

Development Server

const { runDev } = require('@smoud/scripts');

// Start development server with custom config
runDev(webpackDevConfig);

// Start development server with default config
runDev();

// Start development server with custom definitions
runDev(null, null, customDefines);

Production Build

const { runBuild } = require('@smoud/scripts');

// Run production build with custom config
runBuild(webpackBuildConfig);

// Run production build with default config
runBuild();

// Run production build with custom options
runBuild(null, customOptions);

Plugins

The package includes several webpack plugins for platform integration:

const { DebuggerInjectionPlugin } = require('@smoud/scripts');

// Custom debugger integration
new DebuggerInjectionPlugin('http://debugger-url');

Issues

Report issues at GitHub Issues