# What Is the TREK Shared Directory Used For? A Complete Guide to @trek/shared

> Discover what the TREK shared directory is for. Learn how @trek/shared centralizes API contracts, Zod schemas, and i18n strings for your NestJS and React applications.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: deep-dive
- Published: 2026-07-10

---

**The TREK shared directory houses the `@trek/shared` package, which serves as the single source of truth for API contracts, Zod validation schemas, and internationalization strings consumed by both the NestJS server and React client.**

The `shared` directory in the [mauriceboe/TREK](https://github.com/mauriceboe/TREK) repository contains a TypeScript package that eliminates type drift between the frontend and backend. By centralizing data structures and validation logic in `shared/src/`, the architecture ensures that changes to API contracts propagate automatically to both ends of the stack without manual synchronization.

## What Is the TREK Shared Directory?

The TREK shared directory is the physical location of the `@trek/shared` package, situated at the repository root under `shared/`. According to [[`shared/README.md`](https://github.com/mauriceboe/TREK/blob/main/shared/README.md)](https://github.com/mauriceboe/TREK/blob/main/shared/README.md), this package follows a "one folder per domain" rule, where each business domain—such as trip, packing, and share—receives its own subdirectory under `src/<domain>/`.

## Core Responsibilities of the Shared Package

The shared package serves five primary functions that enable consistent cross-stack development.

### Define API Contracts with Zod Schemas

All request and response shapes are expressed as **Zod** schemas inside the shared directory. For example, trip validation logic resides in [[`shared/src/trip/trip.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/trip/trip.schema.ts)](https://github.com/mauriceboe/TREK/blob/main/shared/src/trip/trip.schema.ts), while share-link schemas live in [[`shared/src/share/share.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/share/share.schema.ts)](https://github.com/mauriceboe/TREK/blob/main/shared/src/share/share.schema.ts).

These schemas are imported by the NestJS server for runtime request validation and by the React client for strongly-typed HTTP calls. This guarantees that both ends remain synchronized without manual type duplication.

### Centralize i18n Translation Keys

Translation strings used across the application reside under `shared/src/i18n/<lang>/`. Files like [[`shared/src/i18n/en/shared.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/i18n/en/shared.ts)](https://github.com/mauriceboe/TREK/blob/main/shared/src/i18n/en/shared.ts) and [`shared/src/i18n/zh/shared.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/i18n/zh/shared.ts) export keys such as `shared.tabPlan` and `shared.messages` that both the UI and server-generated emails consume.

### Expose Common Domain Logic

Business rules that must execute on both sides of the network live within domain-specific folders. Each folder contains the schema, TypeScript types, and any shared utilities for that domain, preventing duplication of validation logic across the stack.

## TypeScript Path Configuration

Both workspaces resolve `@trek/shared` via TypeScript path mapping and build tool aliases, allowing direct source imports without extra build steps.

### Server Resolution

The NestJS backend maps the alias in [`server/tsconfig.json`](https://github.com/mauriceboe/TREK/blob/main/server/tsconfig.json) using the `paths` field:

```json
{
  "compilerOptions": {
    "paths": {
      "@trek/shared/*": ["../shared/src/*"]
    }
  }
}

```

### Client Resolution

The React client configures the same alias in [`client/vite.config.ts`](https://github.com/mauriceboe/TREK/blob/main/client/vite.config.ts) using the `resolve.alias` field:

```typescript
import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@trek/shared': path.resolve(__dirname, '../shared/src')
    }
  }
});

```

## Gradual Migration Strategy

As TREK migrates from a monolithic NestJS codebase to a modular architecture, new routes are "migrated" by moving their contracts into `@trek/shared`. Until a specific module imports a schema, the package remains dormant for that feature, ensuring zero runtime impact on existing code paths.

## Practical Code Examples

The following examples demonstrate how both the server and client consume schemas from the TREK shared directory.

### Server-Side Request Validation

Import the schema from `@trek/shared` to validate incoming requests in your NestJS controllers:

```typescript
import { shareLinkRequestSchema } from '@trek/shared/src/share/share.schema';
import { z } from 'zod';

app.post('/api/trips/:tripId/share-link', (req, res) => {
  const parsed = shareLinkRequestSchema.safeParse(req.body);
  if (!parsed.success) return res.status(400).json(parsed.error);
  // Handle the valid payload
});

```

### Client-Side Type Safety

Use the same schema to type your React client requests:

```typescript
import { ShareLinkRequest } from '@trek/shared/src/share/share.schema';
import axios from 'axios';

async function createShareLink(tripId: number, payload: ShareLinkRequest) {
  const response = await axios.post(`/api/trips/${tripId}/share-link`, payload);
  return response.data;
}

```

### Accessing Shared Translation Keys

Reference i18n strings for UI labels or server notifications:

```typescript
import i18n from '@trek/shared/src/i18n/en/shared';
console.log(i18n['shared.tabPlan']); // → "Plan"

```

## Summary

- The **TREK shared directory** contains the `@trek/shared` package, acting as the canonical definition layer for code shared between the NestJS server and React client.
- **Zod schemas** defined in files like [`shared/src/trip/trip.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/trip/trip.schema.ts) provide runtime validation and static TypeScript types for both stacks.
- **Internationalization keys** stored in `shared/src/i18n/*` ensure consistent messaging across the UI and server-generated content.
- **TypeScript path aliases** in [`server/tsconfig.json`](https://github.com/mauriceboe/TREK/blob/main/server/tsconfig.json) and [`client/vite.config.ts`](https://github.com/mauriceboe/TREK/blob/main/client/vite.config.ts) enable direct source imports without additional build configuration.
- The package supports **gradual migration**, allowing teams to move features into the shared directory without breaking existing functionality.

## Frequently Asked Questions

### What is the primary purpose of the TREK shared directory?

The TREK shared directory houses the `@trek/shared` workspace package, which centralizes API contracts, validation schemas, and translation strings. It ensures that both the NestJS backend and React frontend operate on identical data structures and validation rules, eliminating type drift and reducing code duplication.

### How does the server validate requests using the shared directory?

The server imports Zod schemas directly from `@trek/shared` subdirectories. For example, `shareLinkRequestSchema` from [`shared/src/share/share.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/share/share.schema.ts) validates request payloads using `safeParse()`, returning structured error responses when validation fails and ensuring only valid data reaches business logic.

### Can I add new schemas to the shared directory without breaking existing code?

Yes. The shared directory supports a gradual migration strategy. New schemas remain dormant until specifically imported by a feature module, meaning you can add contracts to `shared/src/` without impacting existing server routes or client components that do not yet consume them.

### Where are translation strings stored in the TREK shared directory?

Translation strings live under `shared/src/i18n/<language>/`, with individual files like [`shared/src/i18n/en/shared.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/i18n/en/shared.ts) containing keys such as `shared.tabPlan`. Both the React client and NestJS server import these files to ensure consistent terminology across the user interface and automated notifications.