@hyperfrontend/project-scope/project/package

package

package.json reading, dependency inspection, and version-check helpers.

readPackageJson and readPackageJsonIfExists parse package.json into a typed PackageJson shape. findNearestPackageJson walks up from a starting path to locate the closest manifest. getDependencies, getDevDependencies, getPeerDependencies, getProductionDependencies, and getAllDependencies slice the manifest into typed maps; hasDependency, hasInstalledPackage, and getDependencyVersion answer presence and version-range questions. getWorkspaces / hasWorkspaces surface monorepo workspace declarations from npm, Yarn, or pnpm.

API Reference

ƒ Functions

§function

findNearestPackageJson(startPath: string): string

Find nearest package.json by walking up the directory tree.

Parameters

Name	Type	Description
§startPath	`string`	Starting path

Returns

string

Path to directory containing package.json, or null if not found

Example

Finding nearest package.json

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

const pkgDir = findNearestPackageJson('./src/deep/nested/file.ts')
// => '/path/to/project'

§function

getAllDependencies(packageJson: PackageJson): DependencyMap

Get all dependencies merged into a single map.

Parameters

Name	Type	Description
§packageJson	`PackageJson`	Parsed package.json

Returns

DependencyMap

All dependencies merged

Example

Getting all merged dependencies

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

const allDeps = getAllDependencies(packageJson)
if ('typescript' in allDeps) {
  console.log('TypeScript version:', allDeps['typescript'])
}

§function

getDependencies(packageJson: PackageJson): AllDependencies

Extract all dependencies from package.json.

Parameters

Name	Type	Description
§packageJson	`PackageJson`	Parsed package.json

Returns

AllDependencies

All dependencies categorized

Example

Extracting all dependencies

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

const deps = getDependencies(packageJson)
console.log('Runtime:', Object.keys(deps.dependencies))
console.log('Dev:', Object.keys(deps.devDependencies))

§function

getDependencyVersion(packageJson: PackageJson, name: string): string

Get version string of a specific dependency.

Parameters

Name	Type	Description
§packageJson	`PackageJson`	Parsed package.json content
§name	`string`	Name of the dependency to look up

Returns

string

Version string or null if not found

Example

Getting dependency version

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

const version = getDependencyVersion(packageJson, 'react')
// => '^18.2.0' or null

§function

getDevDependencies(packageJson: PackageJson): DependencyMap

Get development dependencies only.

Parameters

Name	Type	Description
§packageJson	`PackageJson`	Parsed package.json

Returns

DependencyMap

Map of dependency name to version for dev-time dependencies

Example

Getting development dependencies

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

const devDeps = getDevDependencies(packageJson)
// => { 'jest': '^29.0.0', 'typescript': '^5.0.0' }

§function

getPeerDependencies(packageJson: PackageJson): DependencyMap

Get peer dependencies only.

Parameters

Name	Type	Description
§packageJson	`PackageJson`	Parsed package.json

Returns

DependencyMap

Map of dependency name to version for peer requirements

Example

Getting peer dependencies

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

const peerDeps = getPeerDependencies(packageJson)
// => { 'react': '^18.0.0', 'react-dom': '^18.0.0' }

§function

getProductionDependencies(packageJson: PackageJson): DependencyMap

Get production dependencies only.

Parameters

Name	Type	Description
§packageJson	`PackageJson`	Parsed package.json

Returns

DependencyMap

Map of dependency name to version for runtime dependencies

Example

Getting production dependencies

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

const prodDeps = getProductionDependencies(packageJson)
// => { 'express': '^4.18.0', 'lodash': '^4.17.21' }

§function

getWorkspaces(packageJson: PackageJson): string[]

Get workspace patterns from package.json.

Parameters

Name	Type	Description
§packageJson	`PackageJson`	Parsed package.json

Returns

string[]

Array of workspace patterns or empty array

Example

Getting workspace patterns

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

const patterns = getWorkspaces(packageJson)
// => ['packages/*', 'apps/*']

§function

hasDependency(packageJson: PackageJson, name: string, depTypes?: ("dependencies" | "devDependencies" | "peerDependencies" | "optionalDependencies")[]): boolean

Check if package has a dependency of any type.

Parameters

Name	Type	Description
§packageJson	`PackageJson`	Parsed package.json content
§name	`string`	Name of the dependency to check
§depTypes?	`("dependencies" \| "devDependencies" \| "peerDependencies" \| "optionalDependencies")[]`	Optional array of dependency types to check (defaults to all)

Returns

boolean

True if dependency exists in specified categories

Example

Checking for a dependency

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

// Check any dependency type
hasDependency(packageJson, 'lodash')

// Check only production dependencies
hasDependency(packageJson, 'lodash', ['dependencies'])

§function

hasInstalledPackage(projectPath: string, packageName: string): boolean

Check if a package is installed in node_modules.

Parameters

Name	Type	Description
§projectPath	`string`	Project root directory
§packageName	`string`	Package name to check

Returns

boolean

Boolean indicating whether the package exists in node_modules

Example

Checking installed packages

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

if (hasInstalledPackage('/project', 'typescript')) {
  console.log('TypeScript is installed')
}

§function

hasWorkspaces(packageJson: PackageJson): boolean

Check if package has workspaces configured (monorepo).

Parameters

Name	Type	Description
§packageJson	`PackageJson`	Parsed package.json

Returns

boolean

True if workspaces are defined

Example

Checking for workspaces

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

if (hasWorkspaces(packageJson)) {
  console.log('This is a monorepo')
}

§function

readPackageJson(projectPath: string): PackageJson

Reads and parses package.json from a directory, validating the structure and normalizing fields to the PackageJson interface.

Parameters

Name	Type	Description
§projectPath	`string`	Project directory path or path to package.json

Returns

PackageJson

Parsed package.json

Example

Reading package.json

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

const pkg = readPackageJson('/path/to/project')
console.log(pkg.name, pkg.version)

§function

readPackageJsonIfExists(projectPath: string): PackageJson

Attempts to read and parse package.json if it exists, returning null on missing file or parse failure.

Parameters

Name	Type	Description
§projectPath	`string`	Project directory path or path to package.json

Returns

PackageJson

Parsed package.json or null if not found

Example

Reading package.json if it exists

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

const pkg = readPackageJsonIfExists('/path/to/project')
if (pkg) {
  console.log('Found:', pkg.name)
}

◈ Interfaces

§interface

AllDependencies

All dependencies categorized.

Properties

§dependencies:DependencyMap—

Production dependencies

§devDependencies:DependencyMap—

Development dependencies

§optionalDependencies:DependencyMap—

Optional dependencies

§peerDependencies:DependencyMap—

Peer dependencies

§interface

PackageJson

Package.json structure.

Properties

§bin?:string | Record<string, string>—

Binary commands

§browser?:string—

Browser entry point

§dependencies?:Record<string, string>—

Production dependencies

§description?:string—

Package description

§devDependencies?:Record<string, string>—

Development dependencies

§engines?:Record<string, string>—

Engines

§exports?:Record<string, unknown>—

Exports map

§main?:string—

Main entry point

§module?:string—

Module entry point

§name?:string—

Package name

§optionalDependencies?:Record<string, string>—

Optional dependencies

§peerDependencies?:Record<string, string>—

Peer dependencies

§scripts?:Record<string, string>—

Scripts

§types?:string—

Types entry point

§version?:string—

Package version

§workspaces?:string[] | { packages: string[] }—

Workspaces configuration

◆ Types

§type

DependencyMap

Map of dependency name to version.

type DependencyMap = Record<string, string>