Configuration

The malv.json file is the main configuration for your MALV project. It defines which apps to run and where to find them.

Basic Structure

{
  "domain": "example.com",
  "apps": {
    "@my-org/auth": "workspace:*",
    "@my-org/notes": "workspace:*"
  },
  "web": ["packages/web"]
}

Fields

domain

Optional. Your production domain. Used for generating URLs and CORS configuration.

{
  "domain": "myapp.com"
}

apps

Required. Maps app names to their locations. Keys are package names (e.g., @my-org/my-app), values specify where to find the app.

{
  "apps": {
    "@my-org/auth": "workspace:*",
    "@my-org/notes": { "version": "workspace:*", "route": "notes" }
  }
}

web

Optional. Array of paths to web projects (Vite apps). These are started alongside your apps during development.

{
  "web": ["packages/web", "packages/admin"]
}

App Location Formats

workspace:*

Auto-discover the app in your workspace. The CLI searches for a folder containing a package.json with a matching name.

{
  "@my-org/notes": "workspace:*"
}

workspace:path

Specify an exact path relative to malv.json:

{
  "@my-org/notes": "workspace:packages/apps/notes"
}

Local Path

Reference a local directory:

{
  "@my-org/notes": "./local-apps/notes"
}

Registry Version

Install from the MALV registry:

{
  "@malv/gmail": "1.2.0",
  "@malv/calendar": "^2.0.0",
  "@malv/auth": "latest"
}

Semver ranges are supported:

Format Example Meaning
Exact 1.2.3 Exactly this version
Caret ^1.2.0 Compatible versions (>=1.2.0 <2.0.0)
Tilde ~1.2.0 Patch versions (>=1.2.0 <1.3.0)
Range >=1.0.0 <2.0.0 Within range
Latest latest Most recent version

Git Repository

Clone from a Git URL:

{
  "@my-org/notes": "git:https://github.com/my-org/notes.git"
}

Extended App Config

For more control, use an object instead of a string:

{
  "@my-org/notes": {
    "version": "workspace:*",
    "route": "notes"
  }
}

version

Required. The location/version string (same formats as above).

route

Optional. Custom route prefix for the app's tools. Defaults to the app name without the org prefix.

Complete Example

{
  "domain": "myapp.com",
  "apps": {
    "@my-org/auth": "workspace:*",
    "@my-org/notes": {
      "version": "workspace:*",
      "route": "notes"
    },
    "@malv/gmail": "^1.0.0",
    "@malv/calendar": "^2.0.0",
    "./local/custom-app": "./local/custom-app"
  },
  "web": [
    "packages/web",
    "packages/admin"
  ]
}

Lock File

When you install registry apps, a malv.lock file is created:

{
  "lockfileVersion": 1,
  "generatedAt": 1703000000000,
  "systems": {
    "@malv/gmail": {
      "version": "1.2.3",
      "resolved": "https://registry.malv.ai/...",
      "integrity": "sha256-abc123...",
      "files": {
        "package.json": "sha256-...",
        "tools.json": "sha256-..."
      }
    }
  }
}

The lock file:

Environment-Specific Config

Environment variables are stored separately from malv.json:

Use malv env to configure these. See malv env for details.

Validation

The CLI validates malv.json on every command. Common errors:

Invalid JSON syntax

Error: Failed to parse malv.json: Unexpected token at line 5

Missing app

Error: App @my-org/missing not found in workspace

Invalid version format

Error: Invalid version "not-a-version" for @my-org/app

Related