apkg-lock.json Reference

The apkg-lock.json file records the exact dependency state that APKG resolved for a project. While apkg.json expresses intent through package names and version ranges, the lockfile captures the concrete result used for installation.

Its purpose is reproducibility:

• Every machine installs the same resolved package versions.
• CI can verify that the checked-in dependency state is complete and up to date.
• Teams can review dependency changes explicitly in version control.

What the lockfile does

The lockfile sits next to apkg.json in your project root and represents the resolved dependency tree for that manifest.

In practice, this means APKG can:

• Reuse exact previously resolved versions instead of re-resolving ranges on every install.
• Detect when the checked-in dependency state no longer matches apkg.json.
• Fail fast in CI when the lockfile is missing or stale.

When it changes

You should expect apkg-lock.json to be created or updated when a command changes the resolved dependency graph, including:

• apkg add
• apkg install
• apkg update
• apkg remove

The lockfile is also used by guides such as Use APKG in an existing project, where it is treated as a first-class project file that should be committed.

Commit policy

Commit apkg-lock.json to version control alongside apkg.json.

This is the recommended default for:

• Application repositories
• Team-owned internal projects
• CI-managed deployments

Keeping both files in sync ensures that teammates and automation install the same dependency set that you tested locally.

CI usage

Use the frozen-lockfile mode in CI:

apkg install --frozen-lockfile

This mode is designed to enforce two guarantees already documented in apkg install:

1. The lockfile must already exist.
2. The resolved dependency graph must match the lockfile exactly.

If either condition fails, the install fails instead of silently rewriting dependency state during the build.

Relationship to apkg.json

Use the two files for different purposes:

File	Role
apkg.json	Declares package names, version ranges, and project intent
apkg-lock.json	Pins the exact resolved dependency state used for installation

You edit apkg.json directly only in rare cases. Most of the time, both files are maintained through APKG commands such as add, update, and remove.

Common workflow

For normal team development:

1. Change dependencies with APKG commands.
2. Review both apkg.json and apkg-lock.json.
3. Commit both files together.
4. Use apkg install --frozen-lockfile in CI.

Related pages

Page	Description
apkg install	Install dependencies and enforce a frozen lockfile in CI
apkg add	Add a dependency and update the lockfile
Use APKG in an existing project	Team workflow for installing and committing dependencies