> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselumina.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install and set up the Lumina TypeScript/JavaScript SDK

Install the Lumina SDK for TypeScript and JavaScript applications.

***

## Prerequisites

**Node.js 18+ or Bun 1.0+**

Verify your installation:

```bash theme={null}
node --version  # Should show v18 or higher
```

or

```bash theme={null}
bun --version   # Should show 1.0 or higher
```

***

## Install SDK

<CodeGroup>
  ```bash npm theme={null}
  npm install @uselumina/sdk
  ```

  ```bash yarn theme={null}
  yarn add @uselumina/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @uselumina/sdk
  ```

  ```bash bun theme={null}
  bun add @uselumina/sdk
  ```
</CodeGroup>

***

## Install LLM Provider SDK

Install your LLM provider's official SDK:

<CodeGroup>
  ```bash OpenAI theme={null}
  npm install openai
  ```

  ```bash Anthropic theme={null}
  npm install @anthropic-ai/sdk
  ```

  ```bash Both theme={null}
  npm install openai @anthropic-ai/sdk
  ```
</CodeGroup>

***

## Quick Start

Create a simple trace:

```typescript theme={null}
import { initLumina } from '@uselumina/sdk';
import Anthropic from '@anthropic-ai/sdk';

// Initialize Lumina
const lumina = initLumina({
  endpoint: 'http://localhost:9411/v1/traces',
  service_name: 'my-app',
});

// Initialize LLM provider
const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// Trace an LLM call
async function main() {
  const response = await lumina.traceLLM(
    async () =>
      anthropic.messages.create({
        model: 'claude-sonnet-4-5',
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Hello!' }],
      }),
    {
      name: 'chat-completion',
      system: 'anthropic',
      prompt: 'Hello!',
    }
  );

  console.log('Trace sent! View at http://localhost:3000/traces');
}

main();
```

Run it:

```bash theme={null}
npx tsx app.ts
```

Check your dashboard at [http://localhost:3000/traces](http://localhost:3000/traces) to see the trace.

***

## Framework Integration

### Next.js

**App Router (Recommended):**

```typescript theme={null}
// app/api/chat/route.ts
import { initLumina } from '@uselumina/sdk';
import { OpenAI } from 'openai';

const openai = new OpenAI();
const lumina = initLumina({
  endpoint: process.env.LUMINA_ENDPOINT,
  service_name: 'nextjs-app',
});

export async function POST(req: Request) {
  const { message } = await req.json();

  const response = await lumina.traceLLM(
    () =>
      openai.chat.completions.create({
        model: 'gpt-4',
        messages: [{ role: 'user', content: message }],
      }),
    {
      name: 'chat-completion',
      system: 'openai',
      prompt: message,
    }
  );

  return Response.json(response);
}
```

**Pages Router:**

```typescript theme={null}
// pages/api/chat.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { initLumina } from '@uselumina/sdk';
import { OpenAI } from 'openai';

const openai = new OpenAI();
const lumina = initLumina({
  endpoint: process.env.LUMINA_ENDPOINT,
  service_name: 'nextjs-app',
});

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { message } = req.body;

  const response = await lumina.traceLLM(
    () =>
      openai.chat.completions.create({
        model: 'gpt-4',
        messages: [{ role: 'user', content: message }],
      }),
    { name: 'chat', system: 'openai', prompt: message }
  );

  res.json(response);
}
```

### Express

```typescript theme={null}
import express from 'express';
import { initLumina } from '@uselumina/sdk';
import { OpenAI } from 'openai';

const app = express();
const openai = new OpenAI();
const lumina = initLumina({
  endpoint: process.env.LUMINA_ENDPOINT,
  service_name: 'express-app',
});

app.post('/api/chat', async (req, res) => {
  const { message } = req.body;

  const response = await lumina.traceLLM(
    () =>
      openai.chat.completions.create({
        model: 'gpt-4',
        messages: [{ role: 'user', content: message }],
      }),
    { name: 'chat', system: 'openai', prompt: message }
  );

  res.json(response);
});

app.listen(3000);
```

### Fastify

```typescript theme={null}
import Fastify from 'fastify';
import { initLumina } from '@uselumina/sdk';
import { OpenAI } from 'openai';

const fastify = Fastify();
const openai = new OpenAI();
const lumina = initLumina({
  endpoint: process.env.LUMINA_ENDPOINT,
  service_name: 'fastify-app',
});

fastify.post('/api/chat', async (request, reply) => {
  const { message } = request.body as { message: string };

  const response = await lumina.traceLLM(
    () =>
      openai.chat.completions.create({
        model: 'gpt-4',
        messages: [{ role: 'user', content: message }],
      }),
    { name: 'chat', system: 'openai', prompt: message }
  );

  return response;
});

fastify.listen({ port: 3000 });
```

***

## Environment Variables

Set up environment variables for configuration:

```bash theme={null}
# .env
LUMINA_ENDPOINT=http://localhost:9411/v1/traces
SERVICE_NAME=my-app
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
```

Load in your application:

```typescript theme={null}
import { config } from 'dotenv';
config();

const lumina = initLumina({
  endpoint: process.env.LUMINA_ENDPOINT,
  service_name: process.env.SERVICE_NAME,
});
```

***

## TypeScript Support

The SDK is written in TypeScript with full type definitions.

**tsconfig.json:**

```json theme={null}
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  }
}
```

**Type imports:**

```typescript theme={null}
import type { Lumina, TraceLLMOptions, Span } from '@uselumina/sdk';

const options: TraceLLMOptions = {
  name: 'chat-completion',
  system: 'openai',
  prompt: 'Hello',
};
```

***

## Verification

Verify the SDK is working:

**1. Send a test trace:**

```bash theme={null}
npx tsx -e "
import { initLumina } from '@uselumina/sdk';

const lumina = initLumina({
  endpoint: 'http://localhost:9411/v1/traces',
  service_name: 'test',
});

await lumina.trace('test-trace', async (span) => {
  span.setAttribute('test', 'value');
});

await lumina.flush();
console.log('✓ Test trace sent');
"
```

**2. Check dashboard:**

Open [http://localhost:3000/traces](http://localhost:3000/traces) and verify the trace appears.

***

## Troubleshooting

### Module not found

**Error:** `Cannot find module '@uselumina/sdk'`

**Solution:** Reinstall dependencies:

```bash theme={null}
rm -rf node_modules package-lock.json
npm install
```

### Connection refused

**Error:** `ECONNREFUSED localhost:9411`

**Solution:** Verify Lumina is running:

```bash theme={null}
curl http://localhost:9411/health
```

Start Lumina if not running:

```bash theme={null}
cd Lumina/infra/docker
docker compose up -d
```

### TypeScript errors

**Error:** `TS2307: Cannot find module '@uselumina/sdk'`

**Solution:** Add types to tsconfig.json:

```json theme={null}
{
  "compilerOptions": {
    "types": ["@uselumina/sdk"]
  }
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/docs/sdk/typescript/configuration">
    Configure the SDK for your environment
  </Card>

  <Card title="Basic Usage" icon="play" href="/docs/sdk/typescript/basic-usage">
    Learn basic tracing patterns
  </Card>

  <Card title="Advanced Usage" icon="wand-magic-sparkles" href="/docs/sdk/typescript/advanced-usage">
    Multi-span tracing and error handling
  </Card>

  <Card title="API Reference" icon="book" href="/docs/sdk/typescript/api-reference">
    Complete SDK API documentation
  </Card>
</CardGroup>