0Pricing
tRPC End-to-End Type Safe APIs · Lesson

Creating tRPC Context

Understand how to create and populate the tRPC context object with request-specific data like user info.

Creating tRPC Context is a free tRPC End-to-End Type Safe APIs lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the tRPC End-to-End Type Safe APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What is tRPC Context?

Welcome! In tRPC, the context is a special object that's created for each incoming request to your server.

Think of it as a personalized backpack for every request. You can fill this backpack with any data that needs to be accessible by your tRPC procedures.

Why Use tRPC Context?

The tRPC context is incredibly useful for sharing request-specific data across all your API procedures. This prevents you from passing the same arguments repeatedly.

  • Authentication: Store authenticated user details.
  • Database Connections: Provide a database client for the current request.
  • Request-specific Data: Access headers, IP addresses, or other request info.
  • Logging: Attach a unique request ID for tracing.

Defining createContext

You define the context using a function, often named createContext. This function runs once for every incoming tRPC request.

It receives an object containing details about the incoming HTTP request (like headers) and should return the context object.

import { initTRPC } from '@trpc/server';

// This function runs on every request
function createContext(req: { headers: Record<string, string> }) {
  console.log('Context created for a new request!');
  return {
    // We'll add more here later!
  };
}

// We'll use this context to initialize tRPC
const t = initTRPC.context<ReturnType<typeof createContext>>().create();

console.log('tRPC initialized with context.');

Accessing Request Details

Inside your createContext function, you get access to the underlying HTTP request object. This allows you to extract information like request headers or query parameters.

Let's grab a custom header, for example.

import { initTRPC } from '@trpc/server';

function createContext(req: { headers: Record<string, string> }) {
  const userAgent = req.headers['user-agent'] || 'unknown';
  return {
    userAgent: userAgent
  };
}

type Context = ReturnType<typeof createContext>;
const t = initTRPC.context<Context>().create();

// Simulate a request
const mockRequest = {
  headers: { 'user-agent': 'CoddyKit-Browser' }
};

const ctx = createContext(mockRequest);
console.log('User Agent in context:', ctx.userAgent);

Populating Context with Custom Data

You can populate the context object with any data derived from the request. A common use case is adding a user's ID or a full user object after an authentication check.

For now, let's just add a dummy user ID based on a header.

import { initTRPC } from '@trpc/server';

function createContext(req: { headers: Record<string, string> }) {
  // In a real app, this would come from a JWT or session
  const userId = req.headers['x-user-id'] || 'guest_user';
  return {
    userId: userId,
    timestamp: new Date().toISOString()
  };
}

type Context = ReturnType<typeof createContext>;
const t = initTRPC.context<Context>().create();

// Simulate a request with a custom user ID header
const mockRequest = {
  headers: { 'x-user-id': 'coddykit_student_123' }
};

const ctx = createContext(mockRequest);
console.log('Context for request:', ctx);

Typing Your Context

TypeScript is tRPC's superpower! It's crucial to properly type your context object so tRPC can provide full end-to-end type safety.

You can infer the type of your context directly from your createContext function using ReturnType.

import { initTRPC } from '@trpc/server';

function createContext(req: { headers: Record<string, string> }) {
  const userId = req.headers['x-user-id'] || 'anonymous';
  return {
    userId: userId
  };
}

// Infer the Context type from createContext function
type Context = ReturnType<typeof createContext>;

// Now, when initializing tRPC, provide this type
const t = initTRPC.context<Context>().create();

console.log('Context type inferred and used!');
// Example of how TypeScript would see the context:
// const typedContext: Context = { userId: 'some_id' };

Using Context in Procedures

Once your context is defined and typed, any tRPC procedure can easily access it. Procedures receive an object with a ctx property, which holds your context object.

This makes user data, database clients, and other request-scoped data readily available.

import { initTRPC } from '@trpc/server';

function createContext(req: { headers: Record<string, string> }) {
  const userId = req.headers['x-user-id'] || 'guest';
  return { userId };
}

type Context = ReturnType<typeof createContext>;
const t = initTRPC.context<Context>().create();

const appRouter = t.router({
  whoAmI: t.procedure.query(({ ctx }) => {
    // Access userId directly from ctx
    return `Hello, ${ctx.userId}!`;
  }),
});

console.log('Procedure defined using context.');

Context in Action: Full Example

Here's a simplified full example showing how createContext is defined and how its data is used within a tRPC procedure.

The output simulates what the procedure would return if called with the mock request.

import { initTRPC } from '@trpc/server';

// 1. Define your context function
function createContext(req: { headers: Record<string, string> }) {
  const userId = req.headers['x-user-id'] || 'anonymous_user';
  return {
    userId: userId,
    requestTime: new Date().toLocaleTimeString()
  };
}

// 2. Infer the context type for type safety
type Context = ReturnType<typeof createContext>;

// 3. Initialize tRPC with the context type
const t = initTRPC.context<Context>().create();

// 4. Define a simple procedure that uses context
const appRouter = t.router({
  getUserGreeting: t.procedure.query(({ ctx }) => {
    return `Welcome back, ${ctx.userId}! Last accessed at: ${ctx.requestTime}.`;
  }),
});

// --- Simulate a request and context creation ---
const mockRequest = {
  headers: { 'x-user-id': 'CoddyKitUser' }
};

const contextForRequest = createContext(mockRequest);
console.log('Context created:', contextForRequest);

// Simulate the procedure call with the created context
const simulatedOutput = appRouter._def.procedures.getUserGreeting._def.query({ ctx: contextForRequest, input: undefined });
console.log('\nSimulated Procedure Output:');
console.log(simulatedOutput);

Context Best Practices

To keep your tRPC application performant and maintainable:

  • Keep it Lean: Only add data that's truly needed across multiple procedures.
  • Avoid Heavy Logic: Complex operations (like database queries for user data) might be better placed in middleware or services called from context.
  • Security: Always validate and sanitize any data extracted from the raw request before adding it to context.

Context Understanding Check

Let's check your understanding of tRPC context.

Recap: tRPC Context

You've learned about the powerful tRPC context!

  • It's an object created per-request.
  • It allows sharing data like user info or database clients across all procedures.
  • You define it with a createContext function.
  • Type safety is ensured by inferring its type and using it during tRPC initialization.
  • Procedures access context via the ctx parameter.

Next, you'll see how to use context to implement authentication with middleware!

Frequently asked questions

Is the “Creating tRPC Context” lesson free?

Yes — the full text of “Creating tRPC Context” is free to read here on the web, and the tRPC End-to-End Type Safe APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the tRPC End-to-End Type Safe APIs course, upgrade to CoddyKit PRO.

What will I learn in “Creating tRPC Context”?

Understand how to create and populate the tRPC context object with request-specific data like user info. You practise tRPC End-to-End Type Safe APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start tRPC End-to-End Type Safe APIs?

No prior experience is required. tRPC End-to-End Type Safe APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Creating tRPC Context” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this tRPC End-to-End Type Safe APIs lesson?

Yes. Every tRPC End-to-End Type Safe APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Creating tRPC Context
  2. Authentication Middleware
  3. Custom Middleware Chains
  4. Logging and Performance Timing Middleware
← Back to tRPC End-to-End Type Safe APIs