General usage

irsdk-node is a node.js library that exposes the iRacing SDK to javascript/typescript. The main goals of the library are:

• Expose iRacing SDK data to javascript in a way that can be used for stand-alone scripts or inclusion within Electron apps.
• Expose iRacing SDK data with as-close-as-possible type-safety for developer experience and runtime safety.
• Expose iRacing SDK data as performant as possible.

When you combine all of these goals, the main goal you end up with is developer accessibility. This project aims to do the work of exposing SDK data for you, so that you can focus on building the project that you want to build.

Installation

This is a node.js project that is intended to be installed via npm. While you can download the source code directly, it will not include the necessary binaries to be a plug-and-play solution for your project. The versions deployed to npm have pre-built binaries included that enable immediate usage without the need for compiling the native library on your machine, which would require the node-gyp toolchain.

# Npm...
$ npm install irsdk-node

# Yarn...
$ yarn add irsdk-node

# Pnpm...
$ pnpm add irsdk-node

This provides the baseline library with all dependencies, and a wrapper API around the native code that handles boilerplate and data caching for you. If you want to use the native API's directly, you can do so by instead installing @irsdk-node/native (and @irsdk-node/types for Typescript types). For most devs, irsdk-node will be enough.

From-source installation

If you do not want to use the pre-shipped binaries included within the npm package, you can of course clone or fork the repo to use and build locally. To do so, you must ensure that you have all of the required node-gyp toolchain installed so that you can compile the native C++ addon to a binary usable from Node.js. For more information on the required toolchain, check out the node-gyp package readme.

Usage

irsdk-node provides a JS class that wraps a C++ class, and provides some quality of life API improvements. Most apps will follow the following basic flow:

import { IRacingSDK } from "irsdk-node";

const TIMEOUT = Math.floor((1 / 60) * 1000); // 60fps

// Create a loop to use if the service is running.
function loop(sdk: IRacingSDK): void {
  if (sdk.waitForData(TIMEOUT)) {
    const session = sdk.getSessionData();
    const telemetry = sdk.getTelemetry();

    // Do something with the data
    // . . .

    // Wait for new data
    loop(sdk);
  } else {
    // Disconnected.
  }
}

// Check the iRacing service is running
if (await IRacingSDK.IsSimRunning()) {
  const sdk = new IRacingSDK();
  
  // Start the SDK
  if (await sdk.ready()) {
    // Create a loop
    loop(sdk);
  }
}

To break this down:

1. Check if iRacing is installed via IRacingSDK.IsSimRunning(). This will return false if iRacing is not installed on the current system.
2. Initialize an instance of the SDK via new IRacingSDK().
3. Wait for the SDK to be ready via sdk.ready(). This involves loading the native SDK module for the current system.
4. Create a data-loop. This can be done in many ways, either by creating a recursive function or using something like setTimeout(). a. Wait for data using sdk.waitForData(<maxWaitTime>). If it returns true, data has been received from the SDK (ie. an iRacing session is active). b. Cache data from the SDK using sdk.getSessionData() and sdk.getTelemetry(). These are complex calls, so call them once and re-use the result throughout the data loop tick.

That's it! This should give you a working starting point for your app or script. The library is typed, so you can dig through the available telemetry and session variables by checking the type definitions or directly within your code editor.

Check out the best practices guide to learn about easy and common optimisation strategies.