@hyperfrontend/project-scope/nx

NX Module

The nx module provides utilities for detecting and working with NX workspaces. It supports NX monorepo detection, workspace configuration reading, and project enumeration.

Capabilities

Workspace Detection

Detect if a directory is an NX workspace.

import { isNxWorkspace, findNxWorkspaceRoot, isNxProject } from '@hyperfrontend/project-scope'

// Check if current directory is NX workspace root
if (isNxWorkspace('./my-monorepo')) {
  console.log('This is an NX workspace')
}

// Find workspace root from any nested path
const root = findNxWorkspaceRoot('./libs/my-lib/src/utils')
console.log('Workspace root:', root) // '/home/user/my-monorepo'

// Check if directory is an NX project (has project.json)
if (isNxProject('./libs/my-lib')) {
  console.log('This is an NX project')
}

Workspace Information

Get comprehensive workspace details.

import { getNxWorkspaceInfo } from '@hyperfrontend/project-scope'

const info = getNxWorkspaceInfo('./my-monorepo')

console.log('Root:', info.root)
console.log('NX Version:', info.version) // '17.2.0'
console.log('Integrated:', info.isIntegrated) // true
console.log('Default project:', info.defaultProject)
console.log('Layout:', info.workspaceLayout) // { appsDir: 'apps', libsDir: 'libs' }
console.log('NX JSON:', info.nxJson) // Full nx.json content

Project Configuration

Read and parse NX project configuration.

import { readNxProjectConfig, findNxProjects } from '@hyperfrontend/project-scope'

// Read single project config
const config = readNxProjectConfig('./libs/my-lib')
console.log('Name:', config.name)
console.log('Type:', config.projectType) // 'library' | 'application'
console.log('Source root:', config.sourceRoot)
console.log('Tags:', config.tags)
console.log('Targets:', Object.keys(config.targets ?? {}))

// Find all projects in workspace
const projects = findNxProjects('./my-monorepo')
for (const project of projects) {
  console.log(`${project.name} (${project.projectType})`)
}

NX Configuration Files

The module detects these NX configuration files:

File	Description
`nx.json`	Main workspace configuration
`workspace.json`	Legacy workspace configuration
`project.json`	Project-specific configuration

Interfaces

NxWorkspaceInfo

interface NxWorkspaceInfo {
  /** Workspace root path */
  root: string
  /** NX version from package.json */
  version: string | null
  /** Parsed nx.json content */
  nxJson: NxJson
  /** Whether this is an integrated repo */
  isIntegrated: boolean
  /** Default project name */
  defaultProject?: string
  /** Workspace layout configuration */
  workspaceLayout: NxWorkspaceLayout
}

NxWorkspaceLayout

interface NxWorkspaceLayout {
  /** Applications directory (default: 'apps') */
  appsDir: string
  /** Libraries directory (default: 'libs') */
  libsDir: string
}

NxJson

interface NxJson {
  defaultProject?: string
  workspaceLayout?: Partial<NxWorkspaceLayout>
  namedInputs?: Record<string, unknown>
  targetDefaults?: Record<string, unknown>
  nxCloudAccessToken?: string
  plugins?: unknown[]
  tasksRunnerOptions?: Record<string, unknown>
  defaultBase?: string
  [key: string]: unknown
}

Design Principles

Caching: Results are cached appropriately
Version agnostic: Supports multiple NX versions
Standalone support: Detects both integrated and standalone repos
Type safety: Full TypeScript types for all configurations

API Reference

ƒ Functions

§function

buildSimpleProjectGraph(workspacePath: string, projects?: Map<string, NxProjectConfig>): NxProjectGraph

Build a simple project graph from discovered projects.

Parameters

Name	Type	Description
§workspacePath	`string`	Workspace root path
§projects?	`Map<string, NxProjectConfig>`	Existing configuration map to skip auto-discovery

Returns

NxProjectGraph

NxProjectGraph with nodes and dependencies

Example

Building a simple project graph

import { buildSimpleProjectGraph } from '@hyperfrontend/project-scope'

const graph = buildSimpleProjectGraph('/workspace')
console.log('Projects:', Object.keys(graph.nodes))
console.log('Dependencies:', graph.dependencies['my-app'])

§function

discoverNxProjects(workspacePath: string): Map<string, NxProjectConfig>

Discover all NX projects in workspace. Supports both workspace.json (older format) and project.json (newer format).

Parameters

Name	Type	Description
§workspacePath	`string`	Workspace root path

Returns

Map<string, NxProjectConfig>

Map of project name to configuration

Example

Discovering all NX projects

import { discoverNxProjects } from '@hyperfrontend/project-scope'

const projects = discoverNxProjects('/workspace')
for (const [name, config] of projects) {
  console.log(`${name}: ${config.projectType} at ${config.root}`)
}

§function

findNxWorkspaceRoot(startPath: string): string

Find NX workspace root from any path.

Parameters

Name	Type	Description
§startPath	`string`	Starting path to search from

Returns

string

Workspace root path or null if not found

Example

Finding NX workspace root

import { findNxWorkspaceRoot } from '@hyperfrontend/project-scope'

const root = findNxWorkspaceRoot('./libs/my-lib/src')
if (root) {
  console.log('Workspace root:', root) // e.g., '/home/user/my-monorepo'
}

§function

getNxWorkspaceInfo(workspacePath: string): NxWorkspaceInfo

Get comprehensive NX workspace information.

Parameters

Name	Type	Description
§workspacePath	`string`	Workspace root path

Returns

NxWorkspaceInfo

Workspace info or null if not an NX workspace

Example

Getting NX workspace information

import { getNxWorkspaceInfo } from '@hyperfrontend/project-scope'

const info = getNxWorkspaceInfo('/path/to/monorepo')
if (info) {
  console.log('NX version:', info.version)
  console.log('Apps dir:', info.workspaceLayout.appsDir)
}

§function

getProjectConfig(projectPath: string, workspacePath: string): NxProjectConfig

Get project configuration from project.json or package.json nx field.

Parameters

Name	Type	Description
§projectPath	`string`	Project directory path
§workspacePath	`string`	Workspace root path (for relative path calculation)

Returns

NxProjectConfig

Project configuration or null if not found

Example

Getting project configuration

import { getProjectConfig } from '@hyperfrontend/project-scope'

const config = getProjectConfig('./libs/my-lib', '/workspace')
// => { name: 'my-lib', root: 'libs/my-lib', projectType: 'library' }

§function

isNxProject(path: string): boolean

Check if directory is an NX project.

Parameters

Name	Type	Description
§path	`string`	Directory path to check

Returns

boolean

True if the directory contains project.json

Example

Checking for NX project

import { isNxProject } from '@hyperfrontend/project-scope'

if (isNxProject('./libs/my-lib')) {
  console.log('This is an NX project')
}

§function

isNxWorkspace(path: string): boolean

Check if directory is an NX workspace root.

Parameters

Name	Type	Description
§path	`string`	Directory path to check

Returns

boolean

True if the directory contains nx.json or workspace.json

Example

Checking for NX workspace

import { isNxWorkspace } from '@hyperfrontend/project-scope'

if (isNxWorkspace('./my-project')) {
  console.log('This is an NX monorepo')
}

§function

readProjectJson(projectPath: string): NxProjectConfig

Read project.json for an NX project.

Parameters

Name	Type	Description
§projectPath	`string`	Project directory path

Returns

NxProjectConfig

Parsed project.json or null if not found

Example

Reading NX project.json

import { readProjectJson } from '@hyperfrontend/project-scope'

const config = readProjectJson('./libs/my-lib')
if (config) {
  console.log('Project:', config.name, 'Type:', config.projectType)
}

◈ Interfaces

§interface

NxJson

nx.json configuration structure.

Properties

§defaultBase?:string—

Default base

§defaultProject?:string—

Default project

§namedInputs?:Record<string, unknown>—

Named inputs for caching

§nxCloudAccessToken?:string—

NX Cloud access token

§plugins?:unknown[]—

Plugins configuration

§targetDefaults?:Record<string, unknown>—

Target defaults

§tasksRunnerOptions?:Record<string, unknown>—

Task runner options

§workspaceLayout?:Partial<NxWorkspaceLayout>—

Workspace layout

§interface

NxProjectConfig

NX project configuration from project.json.

Properties

§generators?:Record<string, unknown>—

Generator defaults

§implicitDependencies?:string[]—

Implicit dependencies

§name?:string—

Project name

§namedInputs?:Record<string, unknown[]>—

Named inputs for caching

§projectType?:"application" | "library"—

Project type

§root?:string—

Project root path (relative to workspace root)

§sourceRoot?:string—

Source root path

§tags?:string[]—

Project tags for filtering

§targets?:Record<string, NxTargetConfig>—

Build targets

§interface

NxProjectDependency

Simplified project dependency.

Properties

§target:string—

Target project name

§type:"static" | "implicit" | "explicit"—

Dependency type

§interface

NxProjectGraph

Simplified project graph.

Properties

§dependencies:Record<string, NxProjectDependency[]>—

Project dependencies

§nodes:Record<string, NxProjectGraphNode>—

Project nodes

§interface

NxProjectGraphNode

Simplified project graph node.

Properties

§data:NxProjectConfig—

Project configuration

§name:string—

Project name

§type:string—

Project type

§interface

NxTargetConfig

NX target configuration.

Properties

§configurations?:Record<string, Record<string, unknown>>—

Target configurations

§defaultConfiguration?:string—

Default configuration

§dependsOn?:(string | NxTargetDependency)[]—

Depends on other targets

§executor?:string—

Executor to run

§inputs?:unknown[]—

Target inputs for caching

§options?:Record<string, unknown>—

Target options

§outputs?:string[]—

Target outputs

§interface

NxWorkspaceInfo

NX workspace information.

Properties

§defaultProject?:string—

Default project name

§isIntegrated:boolean—

Whether this is an integrated repo (vs standalone)

§nxJson:NxJson—

Parsed nx.json

§root:string—

Workspace root path

§version:string—

NX version from package.json

§workspaceLayout:NxWorkspaceLayout—

Workspace layout configuration

§interface

NxWorkspaceLayout

NX workspace layout configuration.

Properties

§appsDir:string—

Applications directory (default: 'apps')

§libsDir:string—

Libraries directory (default: 'libs')

● Variables

§type

NX_CONFIG_FILES

Files indicating NX workspace root.

§type

NX_PROJECT_FILE

NX-specific project file.