Installation

Get started with the iRacing Data Client SDK in your project.

Prerequisites

Before installing the Data Client, ensure you have:

• Node.js 22 or newer, including odd-numbered releases such as 23 and 25, or a modern browser environment with fetch support
• npm, yarn, or pnpm package manager
• An active iRacing subscription with valid credentials
• TypeScript 5.0+ (optional, but recommended for the best experience)

Package Installation

npm install iracing-data-client

yarn add iracing-data-client

pnpm add iracing-data-client

Basic Setup

1. Import the Data Client

   import { IRacingDataClient } from 'iracing-data-client';

2. Initialize with OAuth credentials

   const iracing = new IRacingDataClient({
     auth: {
       type: 'password-limited',
       clientId: process.env.IRACING_CLIENT_ID,
       clientSecret: process.env.IRACING_CLIENT_SECRET,
       username: process.env.IRACING_USERNAME,
       password: process.env.IRACING_PASSWORD,
     },
   });

3. Make your first API call

   const tracks = await iracing.track.get();
   console.log(`Found ${tracks.length} tracks`);

Configuration Options

The SDK accepts these configuration options:

interface IRacingClientOptions {
  auth: AuthConfig;
  fetchFn?: FetchLike;
  validateParams?: boolean;
  validateSemanticParams?: boolean;
  stores?: HttpClientStores;
  retry?: RetryOptions | false;
  rateLimit?: Omit<HttpClientRateLimitOptions, 'store'>;
  observability?: HttpClientObservabilityOptions;
}

See the Authentication guide for details on the AuthConfig types.

Environment Variables

The recommended approach is to use environment variables:

const iracing = new IRacingDataClient({
  auth: {
    type: 'password-limited',
    clientId: process.env.IRACING_CLIENT_ID,
    clientSecret: process.env.IRACING_CLIENT_SECRET,
    username: process.env.IRACING_USERNAME,
    password: process.env.IRACING_PASSWORD,
  },
});

Create a .env file (don’t commit to git):

IRACING_CLIENT_ID=your-client-id
IRACING_CLIENT_SECRET=your-client-secret
IRACING_USERNAME=your-iracing-email
IRACING_PASSWORD=your-iracing-password

Caution

Never hardcode credentials in your source code. Use environment variables or secure configuration management.

TypeScript Setup

The SDK includes TypeScript definitions out of the box. For the best experience:

1. Ensure TypeScript is installed

   npm install --save-dev typescript

   npm install --save-dev @types/node

2. Configure tsconfig.json

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "ESNext",
       "moduleResolution": "bundler",
       "lib": ["ES2022"],
       "strict": true,
       "esModuleInterop": true,
       "skipLibCheck": true,
       "forceConsistentCasingInFileNames": true
     }
   }

3. Enable type checking

   Your IDE should now provide full IntelliSense support and type checking for all SDK methods.

Node.js Compatibility

Node.js 22 and newer (>=22.0.0) are supported, including odd-numbered releases such as 23 and 25. These versions provide native fetch and Web Crypto support. CI tests ESM and CommonJS on Node.js 22 and 24 LTS only; other supported releases are not part of the CI matrix.

Repository development, builds, documentation, and releases use Node.js 24 and the pinned pnpm 12.10.1 version. These tooling requirements are separate from the supported consumer runtimes.

const iracing = new IRacingDataClient({
  auth: { /* ... */ },
});

Node.js versions below 22 are not supported. Upgrade to Node.js 22 or newer; adding a fetch polyfill does not restore support for older Node releases.

Browser Usage

The SDK can be used in browser environments with some considerations:

Caution

Security Warning: Never expose your iRacing credentials in client-side code. Use a backend proxy or serverless functions for authentication.

Recommended Browser Setup

// In a secure backend API route or serverless function
export async function getIRacingData() {
  const iracing = new IRacingDataClient({
    auth: {
      type: 'password-limited',
      clientId: process.env.IRACING_CLIENT_ID,
      clientSecret: process.env.IRACING_CLIENT_SECRET,
      username: process.env.IRACING_USERNAME,
      password: process.env.IRACING_PASSWORD,
    },
  });

  return await iracing.track.get();
}

CORS Considerations

The iRacing API does not support CORS for browser requests. You’ll need to:

1. Use a backend proxy server
2. Deploy serverless functions (Vercel, Netlify, AWS Lambda)
3. Use a CORS proxy service (development only)

Environment Setup Examples

Next.js

app/api/iracing/route.ts

import { IRacingDataClient } from 'iracing-data-client';

const iracing = new IRacingDataClient({
  auth: {
    type: 'password-limited',
    clientId: process.env.IRACING_CLIENT_ID!,
    clientSecret: process.env.IRACING_CLIENT_SECRET!,
    username: process.env.IRACING_USERNAME!,
    password: process.env.IRACING_PASSWORD!,
  },
});

export async function GET() {
  const data = await iracing.track.get();
  return Response.json(data);
}

Express

server.ts

import express from 'express';
import { IRacingDataClient } from 'iracing-data-client';

const app = express();
const iracing = new IRacingDataClient({
  auth: {
    type: 'password-limited',
    clientId: process.env.IRACING_CLIENT_ID!,
    clientSecret: process.env.IRACING_CLIENT_SECRET!,
    username: process.env.IRACING_USERNAME!,
    password: process.env.IRACING_PASSWORD!,
  },
});

app.get('/api/tracks', async (req, res) => {
  const data = await iracing.track.get();
  res.json(data);
});

Verify Installation

Test your setup with this simple script:

import { IRacingDataClient } from 'iracing-data-client';

async function testConnection() {
  try {
    const iracing = new IRacingDataClient({
      auth: {
        type: 'password-limited',
        clientId: process.env.IRACING_CLIENT_ID!,
        clientSecret: process.env.IRACING_CLIENT_SECRET!,
        username: process.env.IRACING_USERNAME!,
        password: process.env.IRACING_PASSWORD!,
      },
    });

    const tracks = await iracing.track.get();
    console.log('Connected successfully!');
    console.log(`Found ${tracks.length} tracks`);
  } catch (error) {
    console.error('Connection failed:', error);
  }
}

testConnection();

Troubleshooting

Authentication Failed

If you get authentication errors:

• Verify your email and password are correct
• Check if your iRacing subscription is active
• Ensure you’re not hitting rate limits
• Try logging into the iRacing website to verify credentials

Network Errors

For network-related issues:

• Check your internet connection
• Verify firewall settings allow HTTPS requests
• Ensure Node.js has network access
• Try using a custom fetch implementation

TypeScript Errors

If TypeScript isn’t working properly:

• Ensure TypeScript 5.0+ is installed
• Check your tsconfig.json settings
• Restart your TypeScript language server
• Verify moduleResolution is set correctly

Next Steps

Now that you have the Data Client installed, check out:

• Quick Start Guide - Build your first application
• Authentication Guide - Learn about authentication options
• API Reference - Explore available services and methods