← Back to @hyperfrontend/project-scope
@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
NameTypeDescription
§startPath
stringStarting 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'
View source →
§function

getAllDependencies(packageJson: PackageJson): DependencyMap

Get all dependencies merged into a single map.
Parameters
NameTypeDescription
§packageJson
PackageJsonParsed 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'])
}
View source →
§function

getDependencies(packageJson: PackageJson): AllDependencies

Extract all dependencies from package.json.
Parameters
NameTypeDescription
§packageJson
PackageJsonParsed 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))
View source →
§function

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

Get version string of a specific dependency.
Parameters
NameTypeDescription
§packageJson
PackageJsonParsed package.json content
§name
stringName 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
View source →
§function

getDevDependencies(packageJson: PackageJson): DependencyMap

Get development dependencies only.
Parameters
NameTypeDescription
§packageJson
PackageJsonParsed 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' }
View source →
§function

getPeerDependencies(packageJson: PackageJson): DependencyMap

Get peer dependencies only.
Parameters
NameTypeDescription
§packageJson
PackageJsonParsed 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' }
View source →
§function

getProductionDependencies(packageJson: PackageJson): DependencyMap

Get production dependencies only.
Parameters
NameTypeDescription
§packageJson
PackageJsonParsed 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' }
View source →
§function

getWorkspaces(packageJson: PackageJson): string[]

Get workspace patterns from package.json.
Parameters
NameTypeDescription
§packageJson
PackageJsonParsed 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/*']
View source →
§function

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

Check if package has a dependency of any type.
Parameters
NameTypeDescription
§packageJson
PackageJsonParsed package.json content
§name
stringName 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'])
View source →
§function

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

Check if a package is installed in node_modules.
Parameters
NameTypeDescription
§projectPath
stringProject root directory
§packageName
stringPackage 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')
}
View source →
§function

hasWorkspaces(packageJson: PackageJson): boolean

Check if package has workspaces configured (monorepo).
Parameters
NameTypeDescription
§packageJson
PackageJsonParsed 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')
}
View source →
§function

readPackageJson(projectPath: string): PackageJson

Reads and parses package.json from a directory, validating the structure and normalizing fields to the PackageJson interface.
Parameters
NameTypeDescription
§projectPath
stringProject 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)
View source →
§function

readPackageJsonIfExists(projectPath: string): PackageJson

Attempts to read and parse package.json if it exists, returning null on missing file or parse failure.
Parameters
NameTypeDescription
§projectPath
stringProject 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)
}
View source →

◈ Interfaces

§interface

AllDependencies

All dependencies categorized.
Properties
§dependencies:DependencyMapProduction dependencies
§devDependencies:DependencyMapDevelopment dependencies
§peerDependencies:DependencyMapPeer dependencies
§optionalDependencies:DependencyMapOptional dependencies
View source →
§interface

PackageJson

Package.json structure.
Properties
§name?:stringPackage name
§version?:stringPackage version
§description?:stringPackage description
§main?:stringMain entry point
§module?:stringModule entry point
§browser?:stringBrowser entry point
§types?:stringTypes entry point
§bin?:string | Record<string, string>Binary commands
§scripts?:Record<string, string>Scripts
§dependencies?:Record<string, string>Production dependencies
§devDependencies?:Record<string, string>Development dependencies
§peerDependencies?:Record<string, string>Peer dependencies
§optionalDependencies?:Record<string, string>Optional dependencies
§workspaces?:string[] | WorkspacesObjectWorkspaces configuration
§exports?:Record<string, unknown>Exports map
§engines?:Record<string, string>Engines
View source →

◆ Types

§type

DependencyMap

Map of dependency name to version.
type DependencyMap = Record<string, string>
View source →