GemShell

Appearance

TypeScript Support ​

Official TypeScript definitions for the entire GemShell API - including Steamworks - are available as a single .d.ts file.

You get autocomplete, parameter hints and type-checking in any TypeScript project (and in plain JavaScript with // @ts-check).

CDN URL: https://gemshell.dev/gemshell.d.ts

What you get ​

  • Full type coverage for gemshell.os, app, window, screen, file, clipboard, dialog, notification, input
  • Complete Steamworks API (gemshell.steam) - 100+ methods, achievements, stats, friends, leaderboards, lobbies, P2P, Workshop, Steam Input, Steam Cloud, Voice, Timeline, Music, Inventory and overlay
  • Global window.gemshell typed as GemShellAPI | undefined
  • All argument and return types, including unions and optional parameters
  • Inline JSDoc on every method

Setup ​

Pick whichever fits your project.

Option 1: Triple-slash reference (no bundler, no config) ​

Drop the file into your project and reference it from your entrypoint.

bash
# from your project root
curl -O https://gemshell.dev/gemshell.d.ts
ts
/// <reference path="./gemshell.d.ts" />

if (gemshell) {
  const name = await gemshell.os.getName();
}

This is the fastest setup. It works with vanilla JS + // @ts-check, TypeScript, and any IDE.

Option 2: tsconfig.json ​

If you have a tsconfig.json, add the file to types:

json
{
  "compilerOptions": {
    "types": ["./gemshell.d.ts"]
  }
}

You no longer need the /// reference - gemshell is now globally typed across your whole project.

Option 3: ES module import ​

If you prefer explicit imports:

ts
import type { GemShellAPI, Display, FriendInfo } from './gemshell.d.ts';

const api = window.gemshell as GemShellAPI | undefined;

JavaScript with type-checking ​

You don't need to migrate to TypeScript to benefit. Add // @ts-check at the top of any .js file and reference the types:

js
// @ts-check
/// <reference path="./gemshell.d.ts" />

if (gemshell) {
  // Autocomplete and type checking work here
  const size = await gemshell.window.getSize();
  console.log(size.width, size.height);
}

Feature detection pattern ​

Because games can run both in a browser and as a packaged build, always check for gemshell before calling it:

ts
async function saveGame(data: { score: number; level: number }) {
  if (typeof gemshell !== 'undefined') {
    await gemshell.file.save('savegame', data);
  } else {
    localStorage.setItem('savegame', JSON.stringify(data));
  }
}

The gemshell global is typed as GemShellAPI | undefined, so the typeof check narrows it correctly:

ts
if (typeof gemshell !== 'undefined') {
  // gemshell is GemShellAPI here
  const v = gemshell.version;
}

Steamworks types ​

gemshell.steam is optional and only present when steamworks.enabled is true in gemshell.config.json. Guard accordingly:

ts
if (gemshell?.steam) {
  await gemshell.steam.init();
  await gemshell.steam.requestStatsAndWait(3000);

  const score = await gemshell.steam.getStatInt('total_score');
  await gemshell.steam.unlockAchievement('FIRST_WIN');
}

Updating ​

The type definitions follow the GemShell runtime. When you upgrade GemShell, re-download gemshell.d.ts to get the new methods.

bash
curl -O https://gemshell.dev/gemshell.d.ts

Coming soon ​

We are evaluating an official npm package (@gemshell/types) for projects that prefer the npm workflow. Until then, the hosted .d.ts is the recommended source.