Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/smogon/pokemon-showdown-client/llms.txt

Use this file to discover all available pages before exploring further.

Getting a local copy of the Pokémon Showdown Client running takes only a few minutes. The workflow is straightforward: clone, build, and open one of the two test-client HTML files in your browser. There is no separate server to spin up — by default the test client connects to the live play.pokemonshowdown.com game server, so you can see real battles and chat rooms while developing against your local front-end changes.

​
Prerequisites

Before you begin, make sure the following tools are installed and available on your PATH.

Node.js v20+

The build script requires Node.js version 20 or later. Run node --version to check.

Git

Used to clone the repository. Run git --version to verify it is installed.

​
Step-by-Step Setup

1
Clone the repository
2
Clone the client repository from GitHub. There is no need to fork it first just to run locally.
3
git clone https://github.com/smogon/pokemon-showdown-client.git
cd pokemon-showdown-client
4
Build the client
5
The client requires a build step that compiles TypeScript to JavaScript using Babel. Run the appropriate command for your operating system.
6
macOS / Linux
./build
Windows
node build
7
Re-run the build command after every change you make to a source file to see your updates reflected in the test client.
8
You can also run node build full (or ./build full) to perform a full rebuild, which regenerates all data files in addition to recompiling TypeScript.
9
Open the test client
10
After building, open one of the two test-client HTML files directly in your browser.
11
New Client (Preact)
Open play.pokemonshowdown.com/testclient-new.html.This is the active development target — the Preact-based rewrite available at play.pokemonshowdown.com/beta. Use this file when contributing to the new client.
play.pokemonshowdown.com/testclient-new.html
Old Client (jQuery)
Open play.pokemonshowdown.com/testclient-old.html.This is the legacy jQuery-based client. Use this file when fixing bugs in the old client.
play.pokemonshowdown.com/testclient-old.html
12
Some browsers convert ? to %3F when opening files from the local filesystem, which breaks query-string features. If you run into this, serve the files locally with npx http-server from the repository root, then navigate to http://localhost:8080/play.pokemonshowdown.com/testclient-new.html.
13
Connect to a custom server (optional)
14
By default the test client connects to the live Pokémon Showdown server. To point it at a locally running server, append ?~~host:port to the URL.
15
# Connect to a server on localhost port 8000
testclient-old.html?~~localhost:8000

# Connect to a server on localhost port 8000 via http-server
http://localhost:8080/play.pokemonshowdown.com/testclient-old.html?~~localhost:8000
16
The same syntax works for testclient-new.html.
18
For security reasons, browsers block cross-origin credential sharing, which makes logging into the test client with your normal PS account non-trivial. The default workaround requires you to copy-paste session data each time you refresh. To avoid that friction, create a test key file.
19
Step 1 — Grab your sid cookie value:
20
Navigate to the following URL while logged into your PS account in a normal browser tab:
21
https://play.pokemonshowdown.com/testclient-key.php
22
Copy the value shown on the page.
23
Step 2 — Create the key file:
24
Create the file config/testclient-key.js (in the repository root’s config/ directory, not inside play.pokemonshowdown.com/config/) with the following content:
25
const POKEMON_SHOWDOWN_TESTCLIENT_KEY = 'sid';
26
Replace sid with the actual value you copied.
27
macOS / Linux
mkdir -p config
echo "const POKEMON_SHOWDOWN_TESTCLIENT_KEY = 'YOUR_SID_HERE';" > config/testclient-key.js
Windows
mkdir config
echo const POKEMON_SHOWDOWN_TESTCLIENT_KEY = 'YOUR_SID_HERE'; > config\testclient-key.js
28
This is the only supported way to log in on the new (Preact) test client.

​
Known Test Client Limitations

Even with a test key configured, certain account actions do not work in the test client. This is by design.
The following features are intentionally disabled or broken in the test client environment:
  • Registering a new account — not supported.
  • Logging into other registered accounts — not supported. You can switch to unregistered accounts and back, but you cannot authenticate as a different registered user.
Everything else — battles, teambuilder, chat, replays, the ladder — can be tested normally.

​
Development Workflow

Once set up, the typical change-test loop is:
  1. Edit a TypeScript source file in play.pokemonshowdown.com/src/.
  2. Run ./build (or node build on Windows).
  3. Refresh the test client in your browser.
You do not need to restart any server between builds. The build output is static JavaScript that the test client loads from the local filesystem (or via http-server).

​
Next Steps

Architecture

Learn how the client’s four loading phases, observable models, and panel system fit together.

Introduction

Read about the project’s features, browser support matrix, and licensing.

Build docs developers (and LLMs) love

Get started for freeTalk to us