Environment Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/package.json
• turbo.json
• packages/db/drizzle.config.ts
• apps/api/src/app.ts
• apps/api/src/lib/jwt.ts
• packages/db/src/seed.ts
• packages/db/package.json

Environment configuration in the Subito project is managed through a combination of Turbo monorepo orchestration, package-specific .env loading, and strict runtime validation. The configuration system ensures that critical infrastructure details, such as database credentials and security secrets, are consistently available across the API, dashboard, and shared packages.

The architecture relies on standard environment variables to drive behavior in different execution contexts (development vs. production). Key areas influenced by these configurations include database connectivity via Drizzle ORM, authentication token generation using jose, and cross-origin resource sharing (CORS) security policies within the Hono-based API.

Sources: turbo.json:4-19, apps/api/src/app.ts:26-38, packages/db/drizzle.config.ts:11-20

Monorepo Global Environment

The project utilizes Turborepo to manage environment variables across multiple workspaces. A central list of global variables is defined to ensure cache hits are correctly invalidated when sensitive infrastructure parameters change.

Global Environment Variables

The following variables are tracked globally by the build system:

Variable	Context	Description
DATABASE_URL	Infrastructure	Full connection string for the PostgreSQL database.
REDIS_URL	Infrastructure	Connection string for the Redis instance used by BullMQ.
NODE_ENV	Runtime	Specifies the environment (e.g., production, development).
JWT_SECRET	Security	Minimum 32-character secret for signing access and refresh tokens.
PORT	Network	The port on which the API server listens.
CORS_ORIGINS	Security	Comma-separated list of allowed origins for API requests.

Sources: turbo.json:4-19, apps/api/src/lib/jwt.ts:10-14

API and Application Security Configuration

The API server validates environment variables at startup to prevent execution in misconfigured states. This is particularly critical for CORS settings and JWT security.

CORS Origin Validation

The API implements a safety check for CORS_ORIGINS. In production, the application will throw a fatal error if this variable is not explicitly defined. In development, it defaults to local development ports (3000, 4000, 8081).

JWT and Authentication Configuration

Security tokens are configured using several variables that define issuer identity, audience, and expiration durations.

• JWT_SECRET: Required to be at least 32 characters long.
• ACCESS_TOKEN_EXPIRY: Defaults to 15m if not provided.
• REFRESH_TOKEN_EXPIRY: Defaults to 30d if not provided.

Sources: apps/api/src/lib/jwt.ts:10-25

Database Configuration

The database layer uses Drizzle Kit for migrations and Drizzle ORM for runtime queries. The configuration is centralized to ensure the migration tool and the application code use the same credentials.

Environment Loading Strategy

Packages like @subito/db load environment variables by resolving the path to the repository root's .env file. This allows monorepo-wide sharing of the DATABASE_URL.

// packages/db/drizzle.config.ts:11-12
dotenv.config({ path: path.resolve(__dirname, "../../.env") })

export default defineConfig({
  out: "./drizzle",
  schema: "./src/schema/index.ts",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
})

Sources: packages/db/drizzle.config.ts:11-20, packages/db/src/seed.ts:6

Database Integration Flow

The following diagram illustrates how the DATABASE_URL environment variable flows from the configuration file into the operational database pool used for seeding and migrations.

Package Dependencies for Configuration

Management of environment configuration is supported by specific libraries identified in the project's dependency trees.

Package	Dependency	Purpose
@subito/api	dotenv	Loading .env files into process.env.
@subito/api	jose	Using env-derived secrets for JWT operations.
@subito/db	drizzle-kit	Configuration-driven database migrations.
@subito/api	zod	Validation of environment variable structures.

Sources: apps/api/package.json:28-40, packages/db/package.json:25-30, apps/api/src/app.ts:1-12

Environment configuration in Subito provides a secure and scalable foundation by enforcing strict requirements for production environments while maintaining developer ergonomics through sensible defaults and shared monorepo-wide variable loading.