Publishing Packages

WARNING: this documentation is out of date

You can publish a package for use by Pak in one of three package catalogs:

This document describes the process for creating a package in the Pak catalog. Consult the relevant NPM or Bower documentation for creating packages in those catalogs.

Publishing to the Pak Catalog

To publish a new package in the Pak catalog, create your pak.json and then run pak publish in your application directory.

$ pak publish

$ pak publish NAME ENDPOINT EMAIL [OVERRIDE]

In the first example, the package name, repository endpoint and author's email address will be extracted from the pak.json. The third example supplies the name, endpoint and email. You will be prompted to enter a password to secure management of the package. You can supply a file containing the password via the --password password option. Choose and protect your password very carefully. You may use it to modify or retract your package from the catalog.

The package name should be a globally unique name for your package. It may contain -, _ or . characters. Check the Pak Catalog for currently published Pak names to ensure your chosen name is unique. Note that Pak names that start with appweb, esp, ejs, embedthis, exp, expansive, go, goahead, makeme, me and pak are reserved.

The email address should be that of the person responsible for the catalog entry for the package. This email address will be used for password reset requests.

The package endpoint is a valid GitHub account or endpoint that hosts your package contents. For example:

pak publish jquery/jquery ...
pak publish https://github.com/jquery/jquery.git ...
pak publish git@github.com:jquery/jquery ...
pak publish git@github.com:jquery/jquery ...

To publish a package that is hosted on NPM, use an @npm: package alias to query the NPM catalog. For example:

pak publish @npm:jquery name@example.com

Package Aliases

You can publish an alias entry in the catalog that redirects Pak to use another package name. To create an alias, simply use an @ prefix on the endpoint. For example:

pak publish my-angular @angular ...

When Pak installs my-angular it will redirect and search for the angular package and install it instead. You can use a catalog prefix pak:, bower: and npm: to direct Pak to search in the designated catalog. For example:

pak publish my-angular @bower:angular ...

This will search for angular in the Bower catalog.

Override Packages

Sometimes you may need to create a package from third-party source that you cannot modify or control. The package source may not even have its own pak.json file. To support wrapping such existing packages, you can create an entry in the Pak catalog with an override pak.json file. This override file is blended into the package's pak.json when it is saved to the Pak cache. If the package does not have its own pak.json, then this file will be used to create a pak.json. For example:

pak publish my-openssl openssl/openssl me@example.com →
    http://example.com/openssl.json

You can directly access override files in GitHub via the raw.githubusercontent.com site. For example: raw.githubusercontent.com/embedthis/pak/master/overrides/openssl.json.

Pak considers override instructions from several sources (in order):

Override instructions from the Pak catalog.
Over instructions in a local package override file under ~/.pak/overrides/NAME.json
Override instructions in your application's pak.json file.

Override Files

Override files in the ~/.pak/override directory or in the Pak catalog have a slightly different syntax so they can provide different overrides for various versions of a package. One override file can provide override configuration for all versions of a package and for various endpoints hosting the package.

For example, here is a portion of the jQuery override file in the Pak catalog. It has different configuration for version 1.x and 2.x and provides unique configuration when hosted from NPM:

{
    "jquery/jquery": {
        ">=2.1.0": {
            "export": {
                "from":  "dist/jquery.*",
                "trim": 1
            }
        },
        ">=1.11.0": {
            "export": {
                "from":  "dist/jquery.js",
                "trim": 1
            }
        }
    },
    "@npm/jquery": {
        ...
    }
}

An override file is a hash of endpoints that provide the package. Inside each endpoint property hash is a set of configurations for different version expressions. See Version Expressions for details on the version expression syntax.

Here are some example override files from the Pak Catalog: