How do I publish a package to Pkg?

Publish a prepared local package with socra pkg publish or npm publish against the Pkg registry. Each published name and version identifies immutable package bytes, so use a new version when those bytes change. A managed Pkg Release builds from a successful Checkpoint and needs the managed execution path to be available.

Prepare a local package

Install the Socra CLI with the Account and Pkg plugins and sign in to the Account that will own the package. socra pkg publish also requires bun and tar on your command path.

Check that package.json contains the intended name and a valid semantic version, such as 1.2.3. Run your package's tests and build checks. Review the files included in the packed package.

The local publish command packs and uploads the package. It does not run the managed Release's tests and typecheck for you. The CLI refuses a manifest with private: true; keep that setting when the package should remain unpublished.

Publish through the CLI

From the package directory, run:

socra pkg publish --visibility internal

Use --visibility public when creating a Package that anyone may install. This option supplies the initial visibility when publication creates the Package. It does not change an existing Package's visibility.

Use --root PACKAGE_DIRECTORY to select another directory or --tag TAG for a distribution tag other than latest. The success response identifies the published name and version.

Publish through npm

Configure authentication for the intended Account:

socra pkg configure
export SOCRA_ACCESS_TOKEN="$(socra pkg access-token)"

Then run this command from the package directory:

npm publish --registry=https://pkg.socra.cloud/npm/

A new Package created by this upload defaults to internal. Keep the token out of the package contents and logs. Refresh the shell's token before a later publication if needed.

Managed Releases

For a managed Package, replace PACKAGE with its name or pkg_… ID. Inspect its successful Checkpoints and start a Release from its latest Checkpoint:

socra pkg checkpoint list PACKAGE
socra pkg release create PACKAGE

Use --checkpoint CHECKPOINT_ID with a pchk_… ID on the create command to select another Checkpoint belonging to the Package. Wait for active Changes or Releases to finish before starting another Release. Pkg assigns the new version and starts the build asynchronously.

Keep the returned prel_… ID. Check the Release until its status is succeeded or failed:

socra pkg release retrieve PACKAGE RELEASE_ID

Replace RELEASE_ID with that ID. A queued Release is not a completed publication. Read the error if the Release fails.

If you receive the storage-migration error, new package sandboxes are disabled. An existing Checkpoint does not bypass that restriction. See Why does my Pkg Change fail during storage migration? for the recovery boundary.

A direct npm upload does not create a managed source workspace. Use a verified local upload when you maintain the source outside Pkg's managed workspace.

Verify the publication

Replace PACKAGE and VERSION with the published package name and exact version:

npm view PACKAGE@VERSION --registry=https://pkg.socra.cloud/npm/

Check the name, version, distribution tag, and artifact integrity. Install that exact version in a separate test application and check that it can import the package's public entry point.

If a command stops before returning a result, inspect the registry before repeating it. The upload may already own that version. Pkg rejects an existing name and version instead of overwriting it.