14. Installing existing modules#

damat module add <source> installs a module shadcn-style: it reads the module's module.json, splits the module across the app's layers (see below), registers it in damat.config.ts, adds its portable tsconfig aliases, regenerates the workflow barrels, syncs required env vars into .env.example, and installs the npm packages it needs. If the module ships any link files, they split into src/links/<moduleId>/ (see below).

A module is authored flat (workflows/<table>, api/routes/<table>, links/models/, tests/); on install the <moduleId>/ segment is added so nothing collides:

Generated routes import workflows from the bare @workflows barrel, which the install wires up via the @workflows / @workflows/* and @<moduleId>/* tsconfig paths it adds.

# from a registry ref (requires DAMAT_MODULE_REGISTRY)
damat module add damatjs/user@0.2.0

# from a local path
damat module add ./packages/modules/user

# from a github shorthand or git URL
damat module add damatjs/modules/user
damat module add https://github.com/damatjs/modules.git#main

# then apply the module's migrations and restart the dev server
bun damat-orm migrate:up

Useful commands:

damat module list                # what's installed in this app
damat module add <src> --force   # overwrite an existing module (incl. shipped link files)
damat module add <src> --name x  # install under a different id

Module-shipped links. A module can ship cross-module link files (a real defineLink) under links/models/. On add they split into src/links/<moduleId>/, the owner index + top-level aggregator are regenerated, and links: "./src/links" is ensured in damat.config.ts. The link is dormant until you run damat-orm migrate:create link:<moduleId> + migrate:up, and harmless if its target module isn't installed. The copied files are yours to edit (e.g. to point at a target installed under a different id) — a re-install won't clobber them unless you pass --force. See §17.3 → Links shipped by a module.

Trust: registry installs carry an owner + verification status; the install gate is controlled by DAMAT_MODULE_VERIFY (off / warn / require). rejected/revoked modules are always blocked. Path and git sources are trusted as-is (you pointed at them). Details in MODULES.md.

Prefer to drive this from an AI assistant? See the next chapter.