Skip to content
Wippy

Dependency Management

Dependency Management

Section titled “Dependency Management”

Wippy uses a lock file-based dependency system. Modules are published to the hub, declared as dependencies in your source, and resolved into a wippy.lock file that tracks exact versions.

Project Files

Section titled “Project Files”

wippy.lock

Section titled “wippy.lock”

The lock file tracks your project’s directory layout and pinned dependencies:

directories:
  modules: .wippy
  src: ./src
modules:
  - name: acme/http
    version: v1.2.0
    hash: 4ea816fe84ca58a1f0869e5ca6afa93d6ddd72fa09e1162d9e600a7fbf39f0a2
  - name: acme/sql
    version: v2.0.1
    hash: b3f9c8e12a456d7890abcdef1234567890abcdef1234567890abcdef12345678
FieldDescription
directories.modulesWhere downloaded modules are stored (default: .wippy)
directories.srcWhere your source code lives (default: ./src)
modules[].nameModule identifier in org/module format
modules[].versionPinned semantic version
modules[].hashContent hash for integrity verification

wippy.yaml

Section titled “wippy.yaml”

Module metadata for publishing. Required only when you publish your own module:

organization: acme
module: http
version: 1.2.0
description: HTTP utilities for Wippy
license: MIT
repository: https://github.com/acme/wippy-http
keywords:
  - http
  - web
FieldRequiredDescription
organizationYesLowercase, alphanumeric with hyphens
moduleYesLowercase, alphanumeric with hyphens
versionNoSemantic version (set at publish time)
descriptionNoModule description
licenseNoSPDX license identifier
repositoryNoSource repository URL
homepageNoProject homepage
keywordsNoDiscovery keywords
authorsNoAuthor list

Declaring Dependencies

Section titled “Declaring Dependencies”

Add ns.dependency entries in your _index.yaml:

version: "1.0"
namespace: app
entries:
  - name: dependency.http
    kind: ns.dependency
    component: acme/http
    version: "^1.0.0"


  - name: dependency.sql
    kind: ns.dependency
    component: acme/sql
    version: ">=2.0.0"

Version Constraints

Section titled “Version Constraints”
ConstraintExampleMatches
Exact1.2.3Only 1.2.3
Caret^1.2.0>=1.2.0, <2.0.0
Tilde~1.2.0>=1.2.0, <1.3.0
Range>=1.0.01.0.0 and above
Wildcard*Any version (picks highest)
Combined>=1.0.0 <2.0.0Between 1.0.0 and 2.0.0

Workflow

Section titled “Workflow”

Starting a New Project

Section titled “Starting a New Project”
Terminal window
wippy init

Creates a wippy.lock with default directories.

Adding Dependencies

Section titled “Adding Dependencies”
Terminal window
wippy add acme/http               # Latest version
wippy add acme/http@1.2.3         # Exact version
wippy add acme/http@latest         # Latest label

This updates the lock file. Then install:

Terminal window
wippy install

Resolving from Source

Section titled “Resolving from Source”

If your source already declares ns.dependency entries:

Terminal window
wippy update

This scans your source directory, resolves all dependency constraints, updates the lock file, and installs modules.

Updating Dependencies

Section titled “Updating Dependencies”
Terminal window
wippy update                       # Re-resolve all dependencies
wippy update acme/http             # Update only acme/http
wippy update acme/http acme/sql    # Update specific modules

When updating specific modules, other modules stay pinned to their current versions. If the update would require changing non-target modules, you are prompted for confirmation.

Installing from Lock File

Section titled “Installing from Lock File”
Terminal window
wippy install                      # Install all from lock
wippy install --refresh            # Re-fetch every module (--force and --repair are aliases)

Module Storage

Section titled “Module Storage”

Downloaded modules are stored under the .wippy/vendor/ directory:

project/
  wippy.lock
  src/
    _index.yaml
  .wippy/
    vendor/
      acme/
        http-v1.2.0.wapp
        sql-v2.0.1.wapp

By default, modules are kept as .wapp files. To extract them into directories:

# wippy.lock
options:
  unpack_modules: true

With unpacking enabled:

.wippy/
  vendor/
    acme/
      http/
        wippy.yaml
        src/
          _index.yaml
          ...

Local Development with Replacements

Section titled “Local Development with Replacements”

Override hub modules with local directories for development:

# wippy.lock
directories:
  modules: .wippy
  src: ./src
modules:
  - name: acme/http
    version: v1.2.0
    hash: ...
replacements:
  - from: acme/http
    to: ../local-http

The replacement path is relative to the lock file. When a replacement is active, the local directory is used instead of the vendored module. Replacements are preserved across wippy update operations.

Load Order

Section titled “Load Order”

At boot, Wippy loads entries from directories in this order:

  1. Source directory (src)
  2. Replacement directories
  3. Vendored module directories

Modules with active replacements skip their vendor path.

Integrity Verification

Section titled “Integrity Verification”

Each module in the lock file has a content hash. During installation, downloaded modules are verified against their expected hashes. Mismatched modules are rejected and re-downloaded from the registry.

See Also

Section titled “See Also”