@simplysf/simply-package-core

Package/package-version alias resolution, sfdx-project.json dependency management, package dependency installation, and Dev Hub version lookup logic. This is not a Salesforce CLI plugin — it's the library layer behind @simplysf/simply-package's dependency/version commands, published separately so it can be imported directly by anything that wants the same logic (an editor extension, a CI job, a script) without pulling in the CLI framework.

Install

npm install @simplysf/simply-package-core

Requires Node.js >=22 and either "type": "module" or a dynamic import() — this package ships ESM only.

API

Everything below is exported from the package root. Removing or renaming an export is a breaking change; see src/index.ts.

| Export | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | splitPackageAlias(value) | Splits a package reference into its name and version parts, on the last @. | | findPackageVersions(project, packageName, options?) | Finds every place a package name is declared in an sfdx-project.json, and the version declared there. | | buildVersionService(connection, project, filterIds?) | Loads Dev Hub packages/versions and returns a queryable alias-resolution/version-choice service. | | buildProjectService(project) | Reads/writes an sfdx-project.json's package dependencies and related plugin config. | | installPackageDependencies(options) | Installs a project's declared package dependencies into an org, and reports each one's outcome. | | parseDependency(resolvedPackage, versionNumber?) | Parses a resolved dependency reference into its component parts. | | reducePackageInstallRequestErrors(request) | Formats a failed PackageInstallRequest's errors as a numbered-list string. | | isDependenciesPackagingDirectory(packageDir) | Type guard narrowing a package directory to one that declares a dependencies array. | | isPackage2Id / isPackage2VersionId / isSubscriberPackageId / isSubscriberPackageVersionId | Predicates for the four package-ID prefixes (0Ho, 05i, 033, 04t). | | PACKAGE_PREFIX_PACKAGE2 / PACKAGE_PREFIX_PACKAGE2_VERSION / PACKAGE_PREFIX_SUBSCRIBER_PACKAGE / PACKAGE_PREFIX_SUBSCRIBER_PACKAGE_VERSION | The four package-ID prefix constants. | | BasePackageDirWithDependenciesSchema | Zod schema for a package directory entry that declares a dependencies array. | | InstallPackageDependenciesOptions, InstallPackageDependenciesProgress, InstallPackageDependenciesPrompts, PackageToInstall, PackageInstallStatus, PackageInstallType, PackageInstallSecurityType, PackageInstallUpgradeType, PackageInstallApexCompileType | Option, progress/prompt callback, per-package result, and enum types for installPackageDependencies. | | PackageVersionSource, PackageVersionMatch, FindPackageVersionsOptions | Result and option types for findPackageVersions. | | PackageVersionService, VersionChoice, VersionServiceFilterIds | The service buildVersionService returns, the choice rows it builds, and its optional ID filter. | | SfdxProjectService, DependencyChange, PackageDependenciesManageResult | The service buildProjectService returns, and the change/result shapes its applyChanges consumes. | | ParsedDependency, PackageDirDependency, BasePackageDirWithDependencies | A parsed dependency reference, a raw dependencies entry, and a package directory that declares them. |

import { findPackageVersions, splitPackageAlias } from '@simplysf/simply-package-core';

const matches = findPackageVersions(project, 'MyPackage');

import { buildVersionService } from '@simplysf/simply-package-core';

const versionService = await buildVersionService(connection, sfProject);
const alias = versionService.getVersionAlias('04t000000000001AAA');

import { buildProjectService } from '@simplysf/simply-package-core';

const projectService = await buildProjectService(sfProject);
const dependenciesByDirectory = projectService.getDependenciesByDirectory();

import { Duration } from '@salesforce/kit';
import { installPackageDependencies } from '@simplysf/simply-package-core';

// Installs whatever `sfdx-project.json` declares that isn't already installed (or is newer than
// what is), one package at a time, auto-approving any confirmations. Progress goes to `console`.
const results = await installPackageDependencies({
  project: sfProject,
  targetOrgConnection: connection,
  installType: 'Upgrade',
  wait: Duration.minutes(120),
  progress: { info: console.log, warn: console.warn, stepStart: console.log },
});

const upgraded = results.filter(
  (r) => r.Status === 'Installed' && r.ExistingSubscriberPackageVersionId !== r.SubscriberPackageVersionId,
);

Issues

Please report any issues at https://github.com/SimplySF/simply-plugins-core/issues

Contributing

This package is part of the @simplysf/simply monorepo. See CONTRIBUTING.md for what's specific to this package, and the repo's root CONTRIBUTING.md for repo structure, setup, commit conventions, and how to submit a pull request. Please also read our Code of Conduct.

License

Licensed under the Apache-2.0 license.