Have ideas to improve npm?Join in the discussion! »


    0.0.8 • Public • Published

    pko - Package Overlay

    Build Status Maintainability Test Coverage npm package

    pko is a drop-in replacement for npm that uses local files instead of the standard npm registry for the packages it has been set up with. If you're wondering why you would want to do such things, refer to the use-cases section of this document.

    npm is a registered trademark of npm, Inc.


    Adding a package to the pko overlay

    Simply publish your packages using the pko command instead of the npm command (this cannot work for packages that have publishConfig or private: true in their package.json file). No authentication is required.

    • For a package you're developing:
      pko publish path/to/package
    • For a package from your npm registry of choice:
      TGZ=$(npm pack package[@version]) # Download the package locally 
      pko publish ${TGZ}              # Publish the downloaded package 
      rm ${TGZ}                         # Clean-up after yourself 

    Determine which packages you have in the pko overlay

    The ls-overrides subcommand will list all packages present in the local overlay and output their name and (latest) version number to STDOUT.

    pko ls-overrides

    Install packages using the pko overlay

    Simply replace invokations of npm with pko, using the exact same arguments:

    pko install
    pko install --save-dev @types/node
    pko run build

    Overlay location

    The overlay location is determined using the following procedure:

    1. The environment variable $PKO_REPOSITORY
    2. Walk up the tree from $PWD (the process' working directory) until:
      1. A .pko directory is found
      2. The root of the filesystem is reached
    3. Walk up the tree from where pko is installed in until:
      1. A .pko directory is found
      2. The root of the filesystem is reached
    4. Bail out in error.


    Verbose logging can be enabled by setting the PKO_VERBOSE environment variable to a truthy value:

    PKO_VERBOSE=1 pko install


    • Distributing private packages without having to set-up a full-fledged npm registry for private use.

      Simply prepare an overlay locally, then distribute that overlay (for example, in a ZIP file) to interested users.

    • Enable full offline usage of npm

      Prepare an overlay with all the package versions that need to be available offline. No internet connectivity will be required for using those.

    • Replacing a dependency with customized code (for quick experimentations, ...)

      Publish your custom version under the exact same name as the package you want to replace to your overlay, and pko will use that instead of the version found in the public npm registry.

    Contributors ✨

    Thanks goes to these wonderful people (emoji key):

    Elad Ben-Israel

    💻 🐛 👀 ⚠️ 🚧 🤔

    Rico Huijbers

    💻 🐛 👀 ⚠️ 🚧 🤔

    Romain Marcadier

    💻 🐛 👀 ⚠️ 🚧 🤔







    This project follows the all-contributors specification. Contributions of any kind welcome!


    This project is distributed under the Apache-2.0 license.


    npm i pko

    DownloadsWeekly Downloads






    Unpacked Size

    84.1 kB

    Total Files


    Last publish


    • avatar