This guide provides an overview of how to migrate your application to node-screeps-api v2 from v1.
Since "Screeps: World" was upgraded to Node.js v24, node-screeps-api v2 also targets Node.js v24. It may work with older node versions, but this is not explicitly supported.
This package is now bundled using the ESM format. If your application is still using CJS, you will need to upgrade to ESM.
ConfigManager has been renamed to ScreepsConfigManager, and it is now publicly exported.
screeps.json credentials files are now supported in addition to the original SS3 (Screeps Unified Credentials File) format.
ScreepsAPI has been renamed to ScreepsHttpClient.
The signature of ScreepsHttpClient.fromConfig() has been changed:
// Old:
const apiEx1 = await ScreepsAPI.fromConfig() // 'main' server; no app config
const apiEx2 = await ScreepsAPI.fromConfig('main', 'myApp')
// New:
// Server name is now required to prevent accidental use of the default server
const apiEx1 = await ScreepsHttpClient.fromConfig('main')
const apiEx2 = await ScreepsHttpClient.fromConfig('main', { app: 'myApp' })
const apiEx3 = await ScreepsHttpClient.fromConfig('main', {
// Client options can be provided directly to the factory function
// instead of loading it from the config file
app: {
// The default shard can now be specified as an option. If left undefined,
// endpoint methods will throw an error if a shard argument is not provided.
defaultShard: 'shard0',
// This option was named experimentalRetry429 in v1. It is now enabled by
// default. To maintain legacy behavior:
retry429Global: false
}
})
In v1, ScreepsAPI grouped its endpoint methods into objects. In v2, all methods are defined directly on ScreepsHttpClient:
// Old:
const api = await ScreepsAPI.fromConfig('main', 'myApp')
const me = await api.raw.auth.me();
const terrain = await api.raw.game.roomTerrain('W0N0', 1, 'shard0');
const objects = await api.raw.game.roomObjects('W0N0', 'shard0');
const segments = await api.raw.user.memory.segment.get('1,5,10', 'shard2');
const messages = await api.raw.userMessages.index();
// New:
const api = await ScreepsHttpClient.fromConfig('main', {
app: { defaultShard: 'shard0' }
})
const me = await api.authMe()
const terrain = await api.gameRoomTerrain('W0N0') // shard0
const terrain = await api.gameRoomObjects('W0N0') // shard0
const terrain = await api.userMemorySegmentGet('1,5,10', 'shard2')
const messages = await api.userMessagesIndex()
The WebSocket API client is largely unchanged. Check out the Examples section of the documentation.