Installation Guide

June 15, 2026 ยท View on GitHub

Prerequisites

Before installing the Screeps Framework, ensure you have:

  • Node.js 24.x
  • npm 10.x or higher (comes with Node.js 24)
  • TypeScript 4.0 or higher
  • Screeps account (official server or private server)

Installation Methods

Install only the packages you need:

# Core process management
npm install @ralphschuler/screeps-kernel

# Spawning system
npm install @ralphschuler/screeps-spawn

# Economy management
npm install @ralphschuler/screeps-economy

# Defense systems
npm install @ralphschuler/screeps-defense

# Lab automation
npm install @ralphschuler/screeps-chemistry

# Utilities
npm install @ralphschuler/screeps-utils

Method 2: Install Framework Bundle

Note: Currently, packages must be installed individually. A framework bundle will be available after npm publishing.

# Coming soon: Framework bundle
npm install @ralphschuler/screeps-framework

Method 3: Use Example Bot

Clone the minimal bot example:

git clone https://github.com/ralphschuler/screeps.git
cd screeps/examples/minimal-bot
npm install

Package Installation Matrix

PackageInstallation CommandDependencies
Process Management
screeps-kernelnpm i @ralphschuler/screeps-kernelNone
screeps-posisnpm i @ralphschuler/screeps-posisNone
Economy & Resources
screeps-spawnnpm i @ralphschuler/screeps-spawnNone
screeps-economynpm i @ralphschuler/screeps-economyscreeps-utils
screeps-chemistrynpm i @ralphschuler/screeps-chemistryNone
screeps-rolesnpm i @ralphschuler/screeps-rolesNone
Combat & Defense
screeps-defensenpm i @ralphschuler/screeps-defensescreeps-kernel
Architecture & Utilities
screeps-rolesnpm i @ralphschuler/screeps-rolesscreeps-core, screeps-stats
screeps-utilsnpm i @ralphschuler/screeps-utilsNone
screeps-cachenpm i @ralphschuler/screeps-cacheNone
screeps-pathfindingnpm i @ralphschuler/screeps-pathfindingscreeps-utils
screeps-remote-miningnpm i @ralphschuler/screeps-remote-miningscreeps-pathfinding
Infrastructure
screeps-corenpm i @ralphschuler/screeps-coreNone
screeps-statsnpm i @ralphschuler/screeps-statsscreeps-core
screeps-consolenpm i @ralphschuler/screeps-consoleNone
screeps-visualsnpm i @ralphschuler/screeps-visualsNone
screeps-layoutsnpm i @ralphschuler/screeps-layoutsNone
screeps-intershardnpm i @ralphschuler/screeps-intershardscreeps-core
screeps-clustersnpm i @ralphschuler/screeps-clustersscreeps-core
screeps-empirenpm i @ralphschuler/screeps-empirescreeps-intershard
screeps-standardsnpm i @ralphschuler/screeps-standardsNone

Project Setup

1. Initialize TypeScript Project

If starting from scratch:

# Create project directory
mkdir my-screeps-bot
cd my-screeps-bot

# Initialize npm
npm init -y

# Install TypeScript and types
npm install --save-dev typescript
npm install --save-dev @types/node
npm install --save-dev @types/screeps

2. Configure TypeScript

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

3. Install Framework Packages

Install the packages you need:

# Essential packages for basic bot
npm install @ralphschuler/screeps-kernel
npm install @ralphschuler/screeps-spawn
npm install @ralphschuler/screeps-utils

# Optional: Add economy management
npm install @ralphschuler/screeps-economy

# Optional: Add defense
npm install @ralphschuler/screeps-defense

# Optional: Add lab automation
npm install @ralphschuler/screeps-chemistry

4. Create Bot Entry Point

Create src/main.ts:

import { Kernel } from '@ralphschuler/screeps-kernel';
import { SpawnManager } from '@ralphschuler/screeps-spawn';

const kernel = new Kernel({ cpuBudget: 10 });
const spawnManager = new SpawnManager();

kernel.registerProcess({
  id: 'spawning',
  priority: 90,
  execute: () => {
    // Your spawning logic
  },
  cpuBudget: 0.5
});

export const loop = () => {
  kernel.run();
};

Build Configuration

npm install --save-dev rollup
npm install --save-dev @rollup/plugin-typescript
npm install --save-dev @rollup/plugin-node-resolve
npm install --save-dev @rollup/plugin-commonjs

Create rollup.config.js:

import typescript from '@rollup/plugin-typescript';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: 'src/main.ts',
  output: {
    file: 'dist/main.js',
    format: 'cjs',
    sourcemap: true
  },
  plugins: [
    resolve(),
    commonjs(),
    typescript()
  ]
};

Add to package.json:

{
  "scripts": {
    "build": "rollup -c",
    "watch": "rollup -c -w"
  }
}

Option B: Webpack

npm install --save-dev webpack webpack-cli
npm install --save-dev ts-loader

Create webpack.config.js:

const path = require('path');

module.exports = {
  entry: './src/main.ts',
  mode: 'production',
  target: 'node',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'main.js',
    libraryTarget: 'commonjs2'
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: 'ts-loader',
        exclude: /node_modules/
      }
    ]
  },
  resolve: {
    extensions: ['.ts', '.js']
  }
};

Option C: Plain TypeScript Compiler

# Build
npx tsc

# Watch mode
npx tsc --watch

Deployment Configuration

Using Screeps CLI

npm install --save-dev screeps-api

Create .screeps.json:

{
  "email": "your-email@example.com",
  "password": "your-password",
  "branch": "default",
  "ptr": false
}

Add deploy script to package.json:

{
  "scripts": {
    "deploy": "npm run build && screeps-upload dist/main.js"
  }
}

Using Grunt (screeps-typescript-starter compatible)

npm install --save-dev grunt grunt-screeps

Create Gruntfile.js:

module.exports = function(grunt) {
  const config = require('./.screeps.json');
  
  grunt.loadNpmTasks('grunt-screeps');
  
  grunt.initConfig({
    screeps: {
      options: {
        email: config.email,
        password: config.password,
        branch: config.branch,
        ptr: config.ptr
      },
      dist: {
        src: ['dist/main.js']
      }
    }
  });
};

Verification

After installation, verify the framework is working:

// In your main.ts or in Screeps console
import { Kernel } from '@ralphschuler/screeps-kernel';

console.log('Kernel version:', Kernel.version);
console.log('Framework loaded successfully!');

Common Installation Issues

Issue: Module Not Found

Error: Cannot find module '@ralphschuler/screeps-kernel'

Solution:

# Clear npm cache
npm cache clean --force

# Reinstall packages
rm -rf node_modules package-lock.json
npm install

Issue: Type Errors

Error: Type 'X' is not assignable to type 'Y'

Solution:

# Ensure @types/screeps is installed
npm install --save-dev @types/screeps

# Verify TypeScript version
npm install --save-dev typescript@latest

Issue: Build Errors

Error: Build fails with module resolution errors

Solution:

  1. Check tsconfig.json has correct settings
  2. Verify all dependencies are installed
  3. Clear build cache: rm -rf dist

Updating Packages

Update All Framework Packages

# Check for updates
npm outdated

# Update all @ralphschuler packages
npm update @ralphschuler/screeps-kernel
npm update @ralphschuler/screeps-spawn
# ... etc

Update to Specific Version

# Install specific version
npm install @ralphschuler/screeps-kernel@0.2.0

# Install latest
npm install @ralphschuler/screeps-kernel@latest

Next Steps

Support