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

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 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), 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), 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).

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) and 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 using the paths field:

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

Client Resolution

The React client configures the same alias in client/vite.config.ts using the resolve.alias field:

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:

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:

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:

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 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 and 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}