@mono-labs/project

Foundational utility package for Mono. Provides project root discovery, .mono config loading, and environment variable merging.

Installation

yarn add @mono-labs/project

API Reference

Project Root

import {
  findProjectRoot,
  getRootDirectory,
  getRootJson
} from "@mono-labs/project";

• findProjectRoot(startDir?) -- Walk up the directory tree from startDir (or cwd) to find the nearest package.json. Returns the directory path.
• getRootDirectory() -- Returns the project root directory path.
• getRootJson() -- Reads and returns the root package.json as a parsed object.

Mono Configuration

import {
  resolveMonoDirectory,
  getMonoFiles,
  getMonoConfig
} from "@mono-labs/project";

• resolveMonoDirectory() -- Resolves the path to the .mono/ directory (checks project root and cwd).
• getMonoFiles() -- Returns a MonoFiles record of all .mono/*.json command definitions (excluding config.json).
• getMonoConfig() -- Loads and returns the parsed .mono/config.json as a MonoConfig object.
• clearMonoConfigCache() -- Clears the cached mono config, forcing a fresh read on the next call to getMonoConfig().

App Configuration

import {
  loadAppConfig,
  loadProjectConfig
} from "@mono-labs/project";

• loadAppConfig(configType?, startDir?) -- Loads a typed config file (mono.app.json, mono.deployment.json, etc.) from the project. Supports both local development (workspace discovery) and Lambda runtime (bundled config).
• loadProjectConfig() -- Alias for loadAppConfig().

Environment Merging

import { loadMergedEnv } from "@mono-labs/project";

• loadMergedEnv() -- Loads .env and .env.local from the project root, merges them (.env.local takes precedence), and injects into process.env without overwriting existing variables.

Environment Filtering

import {
  filterEnvByPrefixes,
  filterEnvByConfig
} from "@mono-labs/project";

• filterEnvByPrefixes(env, prefixes, include?) -- Returns only env vars whose keys start with one of the given prefixes. Pass an optional include array for specific keys that should always be kept regardless of prefix.
• filterEnvByConfig(env?, include?) -- Reads prefixes from .mono/config.json envMap and combines them with default prefixes (MONO_, EAS_, APP_, TAMAGUI_). Defaults to process.env if env is omitted.

Subpath Export

The @mono-labs/project/project subpath provides access to app config loading, environment filtering, and documentation generation utilities.

Config Types

import type {
  MonoConfig,
  MonoProjectConfig,
  MonoWorkspaceConfig,
  MonoFiles
} from "@mono-labs/project";

• MonoConfig -- Full mono configuration: envMap?: string[], workspace?: MonoWorkspaceConfig, prodFlag?: string
• MonoWorkspaceConfig -- Workspace settings: packageMaps?: Record<string, string>, preactions?: string[]
• MonoProjectConfig -- Project config with envMap, workspace, and prodFlag
• MonoFiles -- Record of command definition objects keyed by filename

Development

Build the project package:

yarn build:project

This package has no internal dependencies -- it sits at the base of the dependency graph. Both @mono-labs/expo and @mono-labs/cli depend on it.

See the Contributing guide for full development setup.