Class SfProjectJson

The sfdx-project.json config object. This file determines if a folder is a valid sfdx project.

Note: Any non-standard (not owned by Salesforce) properties stored in sfdx-project.json should be in a top level property that represents your project. Plugins should store their configuration

See

SfProject.getPluginConfiguration and
SfProject.setPluginConfiguration

Example: reading a standard property

const project = await SfProject.resolve();
const projectJson = await project.resolveProjectConfig();
const namespace = projectJson.get('namespace');

@example writing
const project = await SfProject.resolve();
const projectJson = await project.resolveProjectConfig();
projectJson.set('namespace', 'new');
await projectJson.write();

See force:project:create

Hierarchy (View Summary)

ConfigFile<ConfigFile.Options, ProjectJson>
- SfProjectJson

Properties

`Static`BLOCKLIST

BLOCKLIST: string[] = ...

json properties that are uppercase, or allow uppercase keys inside them

Methods

access

access(perm?: number): Promise<boolean>
Determines if the config file is read/write accessible. Returns true if the user has capabilities specified by perm.
Parameters
- Optionalperm: number
  The permission.
  
  See https://nodejs.org/dist/latest/docs/api/fs.html#fs_fs_access_path_mode_callback
Returns Promise<boolean>
Inherited from ConfigFile.access
- Defined in src/config/configFile.ts:134

accessSync

accessSync(perm?: number): boolean
Determines if the config file is read/write accessible. Returns true if the user has capabilities specified by perm.
Parameters
- Optionalperm: number
  The permission.
  
  See https://nodejs.org/dist/latest/docs/api/fs.html#fs_fs_access_path_mode_callback
Returns boolean
Inherited from ConfigFile.accessSync
- Defined in src/config/configFile.ts:151

addPackageAlias

addPackageAlias(alias: string, id: string): void
Add a package alias to the project. If the alias already exists, it will be overwritten.
Parameters
- alias: string
- id: string
Returns void
- Defined in src/sfProject.ts:316

addPackageBundle

addPackageBundle(
    bundleEntry: {
        name: string;
        versionDescription?: string;
        versionName: string;
        versionNumber: string;
    },
): void
Add a bundle entry to the project. If the bundle entry already exists, the new entry properties will be merged with the existing properties.
Parameters
- bundleEntry: {
      name: string;
      versionDescription?: string;
      versionName: string;
      versionNumber: string;
  }
Returns void
- Defined in src/sfProject.ts:365

addPackageBundleAlias

addPackageBundleAlias(alias: string, id: string): void
Add a bundle alias to the project. If the bundle alias already exists, it will be overwritten.
Parameters
- alias: string
  The alias name
- id: string
  The bundle ID
Returns void
- Defined in src/sfProject.ts:404

addPackageDirectory

addPackageDirectory(
    packageDir:
        | {
            ancestorId?: string;
            ancestorVersion?: string;
            apexTestAccess?: {
                permissionSetLicenses: string
                | string[];
                permissionSets: string | string[];
            };
            calculateTransitiveDependencies?: boolean;
            default?: boolean;
            definitionFile?: string;
            dependencies?: {
                branch?: string;
                package: string;
                versionNumber?: string;
                [key: string]: unknown;
            }[];
            functions?: string[];
            includeProfileUserLicenses?: boolean;
            package: string;
            packageMetadataAccess?: {
                permissionSetLicenses: string
                | string[];
                permissionSets: string | string[];
            };
            path: string;
            postInstallScript?: string;
            postInstallUrl?: string;
            releaseNotesUrl?: string;
            scopeProfiles?: boolean;
            seedMetadata?: { path: string };
            uninstallScript?: string;
            unpackagedMetadata?: { path: string };
            versionDescription?: string;
            versionName?: string;
            versionNumber: string;
        }
        | { default?: boolean; path: string },
): void
Add a package directory to the project. If the package directory already exists, the new directory properties will be merged with the existing properties.
Parameters
- packageDir:
      | {
          ancestorId?: string;
          ancestorVersion?: string;
          apexTestAccess?: {
              permissionSetLicenses: string
              | string[];
              permissionSets: string | string[];
          };
          calculateTransitiveDependencies?: boolean;
          default?: boolean;
          definitionFile?: string;
          dependencies?: {
              branch?: string;
              package: string;
              versionNumber?: string;
              [key: string]: unknown;
          }[];
          functions?: string[];
          includeProfileUserLicenses?: boolean;
          package: string;
          packageMetadataAccess?: {
              permissionSetLicenses: string
              | string[];
              permissionSets: string | string[];
          };
          path: string;
          postInstallScript?: string;
          postInstallUrl?: string;
          releaseNotesUrl?: string;
          scopeProfiles?: boolean;
          seedMetadata?: { path: string };
          uninstallScript?: string;
          unpackagedMetadata?: { path: string };
          versionDescription?: string;
          versionName?: string;
          versionNumber: string;
      }
      | { default?: boolean; path: string }
Returns void
- Defined in src/sfProject.ts:332

clear

clear(): void
Removes all key/value pairs from the config object.

Returns void
Inherited from ConfigFile.clear
- Defined in src/config/configStore.ts:216

entries

entries(): ConfigEntry[]
Returns an array of ConfigEntry for each element in the config.

Returns ConfigEntry[]
Inherited from ConfigFile.entries
- Defined in src/config/configStore.ts:91

exists

exists(): Promise<boolean>
Check to see if the config file exists. Returns true if the config file exists and has access, false otherwise.

Returns Promise<boolean>
Inherited from ConfigFile.exists
- Defined in src/config/configFile.ts:293

existsSync

existsSync(): boolean
Check to see if the config file exists. Returns true if the config file exists and has access, false otherwise.

Returns boolean
Inherited from ConfigFile.existsSync
- Defined in src/config/configFile.ts:300

forEach

forEach(actionFn: (key: string, value: AnyJson) => void): void
Invokes actionFn once for each key-value pair present in the config object.
Parameters
- actionFn: (key: string, value: AnyJson) => void
  The function (key: string, value: ConfigValue) => void to be called for each element.
Returns void
Inherited from ConfigFile.forEach
- Defined in src/config/configStore.ts:249

get

get<K extends string>(key: K, decrypt?: boolean): ProjectJson[K]
Returns the value associated to the key, or undefined if there is none.
Type Parameters
- K extends string
Parameters
- key: K
  The key (object property)
- Optionaldecrypt: boolean
  If it is an encrypted key, decrypt the value. If the value is an object, a clone will be returned.
Returns ProjectJson[K]
Inherited from ConfigFile.get
- Defined in src/config/configStore.ts:103
get<V = AnyJson>(key: string, decrypt?: boolean): V
Returns the value associated to the key, or undefined if there is none.
Type Parameters
- V = AnyJson
Parameters
- key: string
  The key (object property)
- Optionaldecrypt: boolean
  If it is an encrypted key, decrypt the value. If the value is an object, a clone will be returned.
Returns V
Inherited from ConfigFile.get
- Defined in src/config/configStore.ts:106

getContents

getContents(decrypt?: boolean): Readonly<P>
Returns the entire config contents.

NOTE: Data will still be encrypted unless decrypt is passed in. A clone of the data will be returned to prevent storing un-encrypted data in memory and potentially saving to the file system.
Parameters
- decrypt: boolean = false
Returns Readonly<P>
Inherited from ConfigFile.getContents
- Defined in src/config/configStore.ts:237

getDefaultOptions

getDefaultOptions(options?: ConfigFile.Options): ConfigFile.Options
Parameters
- Optionaloptions: ConfigFile.Options
Returns ConfigFile.Options
- Defined in src/sfProject.ts:120

getKeysByValue

getKeysByValue(value: AnyJson): string[]
Returns the list of keys that contain a value.
Parameters
- value: AnyJson
  The value to filter keys on.
Returns string[]
Inherited from ConfigFile.getKeysByValue
- Defined in src/config/configStore.ts:127

getPackageAliases

getPackageAliases(): Nullable<Dictionary<string>>
Get package aliases defined in the project.

Returns Nullable<Dictionary<string>>
- Defined in src/sfProject.ts:305

getPackageBundleAliases

getPackageBundleAliases(): Nullable<Dictionary<string>>
Get package bundle aliases defined in the project.

Returns Nullable<Dictionary<string>>
- Defined in src/sfProject.ts:393

getPackageBundles

getPackageBundles(): {
    name: string;
    versionDescription?: string;
    versionName: string;
    versionNumber: string;
}[]
Get package bundles defined in the project.

Returns {
    name: string;
    versionDescription?: string;
    versionName: string;
    versionNumber: string;
}[]
- Defined in src/sfProject.ts:355

getPackageDirectories

getPackageDirectories(): Promise<
    (
        | {
            ancestorId?: string;
            ancestorVersion?: string;
            apexTestAccess?: {
                permissionSetLicenses: string
                | string[];
                permissionSets: string | string[];
            };
            calculateTransitiveDependencies?: boolean;
            default?: boolean;
            definitionFile?: string;
            dependencies?: {
                branch?: string;
                package: string;
                versionNumber?: string;
                [key: string]: unknown;
            }[];
            functions?: string[];
            includeProfileUserLicenses?: boolean;
            package: string;
            packageMetadataAccess?: {
                permissionSetLicenses: string
                | string[];
                permissionSets: string | string[];
            };
            path: string;
            postInstallScript?: string;
            postInstallUrl?: string;
            releaseNotesUrl?: string;
            scopeProfiles?: boolean;
            seedMetadata?: { path: string };
            uninstallScript?: string;
            unpackagedMetadata?: { path: string };
            versionDescription?: string;
            versionName?: string;
            versionNumber: string;
        }
        | { default?: boolean; path: string }
    )[],
>
Returns the packageDirectories within sfdx-project.json, first reading and validating the file if necessary.

Returns Promise<
    (
        | {
            ancestorId?: string;
            ancestorVersion?: string;
            apexTestAccess?: {
                permissionSetLicenses: string
                | string[];
                permissionSets: string | string[];
            };
            calculateTransitiveDependencies?: boolean;
            default?: boolean;
            definitionFile?: string;
            dependencies?: {
                branch?: string;
                package: string;
                versionNumber?: string;
                [key: string]: unknown;
            }[];
            functions?: string[];
            includeProfileUserLicenses?: boolean;
            package: string;
            packageMetadataAccess?: {
                permissionSetLicenses: string
                | string[];
                permissionSets: string | string[];
            };
            path: string;
            postInstallScript?: string;
            postInstallUrl?: string;
            releaseNotesUrl?: string;
            scopeProfiles?: boolean;
            seedMetadata?: { path: string };
            uninstallScript?: string;
            unpackagedMetadata?: { path: string };
            versionDescription?: string;
            versionName?: string;
            versionNumber: string;
        }
        | { default?: boolean; path: string }
    )[],
>
- Defined in src/sfProject.ts:156

getPackageDirectoriesSync

getPackageDirectoriesSync(): NamedPackageDir[]
Returns a read-only list of packageDirectories within sfdx-project.json, first reading and validating the file if necessary. i.e. modifying this array will not affect the sfdx-project.json file.

Returns NamedPackageDir[]
- Defined in src/sfProject.ts:193

getPath

getPath(): string
Returns the absolute path to the config file.

The first time getPath is called, the path is resolved and becomes immutable. This allows implementers to override options properties, like filePath, on the init method for async creation. If that is required for creation, the config files can not be synchronously created.

Returns string
Inherited from ConfigFile.getPath
- Defined in src/config/configFile.ts:357

getUniquePackageDirectories

getUniquePackageDirectories(): NamedPackageDir[]
Returns a read-only list of packageDirectories within sfdx-project.json, first reading and validating the file if necessary. i.e. modifying this array will not affect the sfdx-project.json file.

There can be multiple packages in packageDirectories that point to the same directory. This method only returns one packageDirectory entry per unique directory path. This is useful when doing source operations based on directories but probably not as useful for packaging operations that want to do something for each package entry.

Returns NamedPackageDir[]
- Defined in src/sfProject.ts:250

getUniquePackageNames

getUniquePackageNames(): string[]
Get a list of the unique package names from within sfdx-project.json. Use SfProject.getUniquePackageDirectories for data other than the names.

Returns string[]
- Defined in src/sfProject.ts:269

has

has(key: string): boolean
Returns a boolean asserting whether a value has been associated to the key in the config object or not.
Parameters
- key: string
Returns boolean
Inherited from ConfigFile.has
- Defined in src/config/configStore.ts:137

hasMultiplePackageBundles

hasMultiplePackageBundles(): boolean
Has multiple package bundles defined in the project.

Returns boolean
- Defined in src/sfProject.ts:290

hasMultiplePackages

hasMultiplePackages(): boolean
Has multiple package directories (MPD) defined in the project.

Returns boolean
- Defined in src/sfProject.ts:283

hasPackageAliases

hasPackageAliases(): Promise<boolean>
Has at least one package alias defined in the project.

Returns Promise<boolean>
- Defined in src/sfProject.ts:298

hasPackageBundleAliases

hasPackageBundleAliases(): boolean
Has at least one package bundle alias defined in the project.

Returns boolean
- Defined in src/sfProject.ts:386

hasPackages

hasPackages(): boolean
Has package directories defined in the project.

Returns boolean
- Defined in src/sfProject.ts:276

isGlobal

isGlobal(): boolean
Returns true if this config is using the global path, false otherwise.

Returns boolean
Inherited from ConfigFile.isGlobal
- Defined in src/config/configFile.ts:380

keys

keys(): string[]
Returns an array that contains the keys for each element in the config object.

Returns string[]
Inherited from ConfigFile.keys
- Defined in src/config/configStore.ts:144

read

read(): Promise<ProjectJson>
Read the config file and set the config contents. Returns the config contents of the config file. As an optimization, files are only read once per process and updated in memory and via write(). To force a read from the filesystem pass force=true. Throws SfError{ name: 'UnexpectedJsonFileFormat' } There was a problem reading or parsing the file.

Returns Promise<ProjectJson>
Overrides ConfigFile.read
- Defined in src/sfProject.ts:91

readSync

readSync(): ProjectJson
Read the config file and set the config contents. Returns the config contents of the config file. As an optimization, files are only read once per process and updated in memory and via write(). To force a read from the filesystem pass force=true. Throws SfError{ name: 'UnexpectedJsonFileFormat' } There was a problem reading or parsing the file.

Returns ProjectJson
Overrides ConfigFile.readSync
- Defined in src/sfProject.ts:103

refreshSync

refreshSync(): SfProjectJson
force a reread of the project contents if you know they may have been modified

Returns SfProjectJson
- Defined in src/sfProject.ts:98

schemaValidate

schemaValidate(): Promise<void>
Validates sfdx-project.json against the schema.

Set the SFDX_PROJECT_JSON_VALIDATION environment variable to true to throw an error when schema validation fails. A warning is emitted by default when the file is invalid.

See [sfdx-project.schema.json] ((https://github.com/forcedotcom/schemas/blob/main/sfdx-project.schema.json)

Returns Promise<void>
- Defined in src/sfProject.ts:132

schemaValidateSync

schemaValidateSync(): void
Validates sfdx-project.json against the schema.

Set the SFDX_PROJECT_JSON_VALIDATION environment variable to true to throw an error when schema validation fails. A warning is emitted by default when the file is invalid.

See [sfdx-project.schema.json] ((https://github.com/forcedotcom/schemas/blob/main/sfdx-project.schema.json)

Returns void
- Defined in src/sfProject.ts:168

set

set<K extends string>(key: K, value: ProjectJson[K]): void
Sets the value for the key in the config object. This will override the existing value. To do a partial update, use BaseConfigStore.update.
Type Parameters
- K extends string
Parameters
- key: K
  The key.
- value: ProjectJson[K]
  The value.
Returns void
Inherited from ConfigFile.set
- Defined in src/config/configStore.ts:155

setContentsFromObject

setContentsFromObject(obj: ProjectJson): void
Convert an object to a ConfigContents and set it as the config contents.
Parameters
- obj: ProjectJson
  The object.
Returns void
Inherited from ConfigFile.setContentsFromObject
- Defined in src/config/configStore.ts:266

stat

stat(): Promise<Stats>
Get the stats of the file. Returns the stats of the file.

fs.stat

Returns Promise<Stats>
Inherited from ConfigFile.stat
- Defined in src/config/configFile.ts:309

statSync

statSync(): Stats
Get the stats of the file. Returns the stats of the file.

fs.stat

Returns Stats
Inherited from ConfigFile.statSync
- Defined in src/config/configFile.ts:318

toObject

toObject(): JsonMap
Convert the config object to a JSON object. Returns the config contents. Same as calling ConfigStore.getContents

Returns JsonMap
Inherited from ConfigFile.toObject
- Defined in src/config/configStore.ts:257

unlink

unlink(): Promise<void>
Delete the config file if it exists.

Throws Error{ name: 'TargetFileNotFound' } If the ConfigFile.getFilename file is not found. fs.unlink

Returns Promise<void>
Inherited from ConfigFile.unlink
- Defined in src/config/configFile.ts:328

unlinkSync

unlinkSync(): void
Delete the config file if it exists.

Throws Error{ name: 'TargetFileNotFound' } If the ConfigFile.getFilename file is not found. fs.unlink

Returns void
Inherited from ConfigFile.unlinkSync
- Defined in src/config/configFile.ts:342

unset

unset<K extends string>(key: K): boolean
Returns true if an element in the config object existed and has been removed, or false if the element does not exist. BaseConfigStore.has will return false afterwards.
Type Parameters
- K extends string
Parameters
- key: K
  The key
Returns boolean
Inherited from ConfigFile.unset
- Defined in src/config/configStore.ts:195

unsetAll

unsetAll(keys: string[]): boolean
Returns true if all elements in the config object existed and have been removed, or false if all the elements do not exist (some may have been removed). BaseConfigStore.has(key) will return false afterwards.
Parameters
- keys: string[]
  The keys
Returns boolean
Inherited from ConfigFile.unsetAll
- Defined in src/config/configStore.ts:209

update

update<K extends string>(key: K, value: Partial<P[K]>): void
Updates the value for the key in the config object. If the value is an object, it will be merged with the existing object.
Type Parameters
- K extends string
Parameters
- key: K
  The key.
- value: Partial<P[K]>
  The value.
Returns void
Inherited from ConfigFile.update
- Defined in src/config/configStore.ts:179

values

values(): AnyJson[]
Returns an array that contains the values for each element in the config object.

Returns AnyJson[]
Inherited from ConfigFile.values
- Defined in src/config/configStore.ts:223

write

write(): Promise<ProjectJson>
Write the config file with new contents. If no new contents are provided it will write the existing config contents that were set from ConfigFile.read, or an empty file if ConfigFile.read was not called.

Returns Promise<ProjectJson>
Overrides ConfigFile.write
- Defined in src/sfProject.ts:109

writeSync

writeSync(): ProjectJson
Write the config file with new contents. If no new contents are provided it will write the existing config contents that were set from ConfigFile.read, or an empty file if ConfigFile.read was not called.

Returns ProjectJson
Overrides ConfigFile.writeSync
- Defined in src/sfProject.ts:114

`Static`getDefaultOptions

getDefaultOptions(isGlobal?: boolean): ConfigFile.Options
Returns the default options for the config file.
Parameters
- isGlobal: boolean = false
  If the file should be stored globally or locally.
Returns ConfigFile.Options
Overrides ConfigFile.getDefaultOptions
- Defined in src/sfProject.ts:85

`Static`getFileName

getFileName(): string
Returns the config's filename.

Returns string
Overrides ConfigFile.getFileName
- Defined in src/sfProject.ts:81

`Static`resolveRootFolder

resolveRootFolder(isGlobal: boolean): Promise<string>
Helper used to determine what the local and global folder point to. Returns the file path of the root folder.
Parameters
- isGlobal: boolean
  True if the config should be global. False for local.
Returns Promise<string>
Inherited from ConfigFile.resolveRootFolder
- Defined in src/config/configFile.ts:113

`Static`resolveRootFolderSync

resolveRootFolderSync(isGlobal: boolean): string
Helper used to determine what the local and global folder point to. Returns the file path of the root folder.
Parameters
- isGlobal: boolean
  True if the config should be global. False for local.
Returns string
Inherited from ConfigFile.resolveRootFolderSync
- Defined in src/config/configFile.ts:122

Class SfProjectJson

See

Example: reading a standard property

Hierarchy (View Summary)

Index

Properties

Methods

Properties

StaticBLOCKLIST

Methods

access

Parameters

Returns Promise<boolean>

accessSync

Parameters

Returns boolean

addPackageAlias

Parameters

Returns void

addPackageBundle

Parameters

Returns void

addPackageBundleAlias

Parameters

Returns void

addPackageDirectory

Parameters

Returns void

clear

Returns void

entries

Returns ConfigEntry[]

exists

Returns Promise<boolean>

existsSync

Returns boolean

forEach

Parameters

Returns void

get

Type Parameters

Parameters

Returns ProjectJson[K]

Type Parameters

Parameters

Returns V

getContents

Parameters

Returns Readonly<P>

getDefaultOptions

Parameters

Returns ConfigFile.Options

getKeysByValue

Parameters

Returns string[]

getPackageAliases

Returns Nullable<Dictionary<string>>

getPackageBundleAliases

Returns Nullable<Dictionary<string>>

getPackageBundles

Returns { name: string; versionDescription?: string; versionName: string; versionNumber: string;}[]

getPackageDirectories

getPackageDirectoriesSync

Returns NamedPackageDir[]

getPath

Returns string

getUniquePackageDirectories

Returns NamedPackageDir[]

getUniquePackageNames

Returns string[]

has

Parameters

Returns boolean

hasMultiplePackageBundles

Returns boolean

hasMultiplePackages

Returns boolean

hasPackageAliases

Returns Promise<boolean>

hasPackageBundleAliases

`Static`BLOCKLIST

Returns {
name: string;
versionDescription?: string;
versionName: string;
versionNumber: string;
}[]

`Static`getDefaultOptions

`Static`getFileName

`Static`resolveRootFolder

`Static`resolveRootFolderSync