USE AN EXTENSION FROM A LOCAL PATH

This guide shows you how to make a swamp repo load an extension from a directory on your filesystem instead of pulling it from the swamp.club registry, by registering the directory as a source in .swamp-sources.yaml.

Use this when:

• iterating on an extension you have not yet published
• consuming a private or internal extension that cannot be published to swamp.club
• composing extensions from several development trees in one repo
• temporarily running a local fork of a published extension

Prerequisites

• A swamp repository where you want to consume the extension (swamp repo init)
• A separate directory containing the extension you want to load. The examples below use systeminit/swamp-extensions, cloned to ~/code/systeminit/swamp-extensions

The extension directory must follow one of two layouts:

• Repo-root layout — contains an extensions/<kind>/ subdirectory (for example, extensions/models/). This is what swamp repo init produces.
• Direct-content layout — contains the extension files themselves (e.g. *.ts files that export const model = …).

If both layouts are present in the same directory, the repo-root layout wins.

Add a local source

From the consuming repo, register the extension directory as a source:

$ swamp extension source add ~/code/systeminit/swamp-extensions

You will see output like:

Added extension source: /Users/you/code/systeminit/swamp-extensions
1 source configured

This creates .swamp-sources.yaml at the repo root if it does not exist.

Verify the source loaded

List the configured sources to confirm the extension kinds were detected:

$ swamp extension source list

You will see output like:

Extension sources (1):

  ✓ /Users/you/code/systeminit/swamp-extensions
    kinds: models

The ✓ marks a valid source. The kinds: line shows which extension types the source contributes (models, vaults, drivers, datastores, reports, workflows).

For machine-readable output, add --json:

{
  "sources": [
    {
      "path": "/Users/you/code/systeminit/swamp-extensions",
      "expandedPaths": [
        "/Users/you/code/systeminit/swamp-extensions"
      ],
      "status": "valid",
      "resolvedKinds": [
        "models"
      ]
    }
  ]
}

Use the extension

Create a model from the local extension type:

$ swamp model create @swamp/issue-lifecycle local-test

Iterate on the extension

Edit the source file in the extension repo, then re-run any swamp command in the consuming repo. Edits are picked up automatically.

Limit a source to specific kinds

Use --only to load just one kind of extension from a directory that contains several:

swamp extension source add ~/code/my-extensions --only vaults
swamp extension source add ~/code/my-extensions --only models,reports

Add several extensions with a glob

To register every matching directory at once, pass a glob pattern. Quote it so your shell does not expand it before swamp sees it:

swamp extension source add "~/code/systeminit/swamp-extensions/model/aws/*"

Override a published extension with a local copy

Sources take precedence over pulled extensions of the same type. Add a source pointing at your local copy of an already-pulled extension and the source version loads instead, until you remove the source.

Remove a source

When you no longer need the local source, remove it so the consuming repo falls back to pulled extensions (or stops resolving the type altogether, if nothing has been pulled):

$ swamp extension source rm ~/code/systeminit/swamp-extensions

You will see output like:

Removed extension source: /Users/you/code/systeminit/swamp-extensions
0 sources configured

Pass the same path you used in add (including any glob pattern, in quotes).

Related

• Create and Publish an Extension — when you do want a local extension to live on the registry.
• Repository Configuration — reference for .swamp.yaml and the surrounding repository files.