Workspace

A workspace is the root of a Putnami project. It is a single directory identified by a putnami.workspace.json file that defines how projects are discovered, how dependencies are resolved, and how jobs run across the entire codebase.

Projects

Every project has a physical Path relative to the workspace root and a canonical logical ID used in CLI output, dependency declarations, and target expressions. Normally the ID is the slash-prefixed path. A complete, non-empty parenthesized path segment is a transparent group folder: it stays in Path but is omitted from ID.

Physical Path Logical ID
typescript/frameworks/web /typescript/frameworks/web
identity/(workloads)/auth-server /identity/auth-server
identity/(libs)/identity-client /identity/identity-client

Only complete segments are transparent. Names such as work(loads), (workloads)-legacy, and () remain part of the ID. Group folders can use any non-empty name; libs and workloads have no special treatment beyond the parentheses convention.

Filesystem operations—including discovery, includes, file ownership, package-manager workspaces, and projects sync—continue to use physical paths. ID selectors, aliases, groups, graph keys, and generated artifacts use logical IDs. This is a clean break: Putnami does not register former or physical path-derived forms (for example /identity/workloads/auth-server or /identity/(workloads)/auth-server) as compatibility ID aliases.

Projects come in two shapes:

  • App — a runnable or deployable project (web app, API, worker)
  • Library — shared code consumed by other projects

Use putnami projects list to see all projects and their IDs.

Workspace structure

You can organize projects however you like. Common patterns:

# Classic apps + packages
apps/<project>
packages/<project>

# Domain-based
domains/<domain>/services/<project>
domains/<domain>/libs/<project>

# Domain-based with transparent grouping folders
domains/<domain>/(workloads)/<project>
domains/<domain>/(libs)/<project>

# Language-first with scopes
go/framework/<project>
typescript/framework/<project>

A minimal workspace:

my-workspace/
  apps/
    web/
      package.json
  packages/
    shared/
      package.json
  putnami.workspace.json
  package.json

Project discovery

Putnami discovers projects from two sources, in priority order:

  1. Workspace includes — root putnami.workspace.json entries that resolve to direct projects or autonomous scopes
  2. Package manager workspaces — the root package.json workspaces field

If a project appears in multiple sources, the first source wins.

Scopes

Scopes are an organizational layer between the workspace and projects. A scope is a directory with a putnami.json that declares its own includes, tags, extensions, and groups. This decentralizes ownership — each subtree manages its own config instead of everything living in the root.

Register scope directories in putnami.workspace.json:

{
  "includes": ["go/framework", "typescript/framework", "typescript/samples", "tooling/cli", "platform/ci"]
}

Each scope directory has its own putnami.json:

{
  "includes": ["app", "http", "sql", "inject"],
  "tags": ["go"],
  "extensions": ["@putnami/go"],
  "publishConfig": {
    "go": { "namePattern": "go.putnami.dev/{name}" }
  },
  "groups": {
    "go-core": "/go/framework/app,/go/framework/inject"
  }
}

Scope inheritance

Scopes form an inheritance chain from the workspace root down to each project:

  • Tags: merged (union) — a project inherits all tags from its ancestor scopes
  • Extensions: deepest scope wins (replaces parent)
  • PublishConfig: deepest scope wins per channel
  • Groups and aliases: aggregated across all scopes (duplicates are errors)

Scopes are most useful when your workspace has many projects organized by language or domain. Instead of listing 50+ projects in the root config, you declare a few scopes that each manage their own subtree.

Use putnami projects list to inspect the projects resolved from workspace and scope includes.

Tags and filtering

Projects can declare tags in putnami.json or in package.json under the putnami key:

{
  "name": "@myorg/my-app",
  "tags": ["frontend", "deployable"]
}

Use tags to narrow which projects a job targets:

putnami build --all --tag frontend
putnami test --all --exclude-tag e2e
putnami build --all --tag backend,deployable

Tags listed in putnami.workspace.json under disable.tags are excluded from all selections by default. Use --tag to explicitly include them:

{
  "disable": {
    "tags": ["e2e"]
  }
}

Dependency graph and --impacted

Putnami maintains a dependency graph across all projects in the workspace. The --impacted flag uses this graph to run jobs only on projects affected by git changes compared to a resolved baseline.

A project is impacted if:

  • It has changed files, or
  • It depends on a project with changed files

Impact propagates transitively — if a shared library changes, every project that depends on it (directly or indirectly) is considered impacted.

# Build only what changed
putnami build --impacted

# Preview what would run
putnami build --impacted --plan

When --baseline is omitted, Putnami resolves the baseline from workspace baseline, the branch upstream, origin/HEAD, then local main or master. If none resolve, --impacted falls back to --all; use --impacted-strict to fail instead.

Aliases and groups

Define shortcuts in putnami.workspace.json for frequently used targets:

{
  "projectAliases": {
    "web": "/typescript/frameworks/web",
    "cli": "/tooling/cli"
  },
  "groups": {
    "frontend": "/typescript/frameworks/web,/typescript/frameworks/ui",
    "all-go": "/go/..."
  }
}

Aliases and groups can also be defined in scope-level putnami.json files.

Introspection commands

putnami workspace describe          # Workspace name, root, version
putnami projects list               # All projects with paths and tags
putnami projects describe <project> # Dependencies, exports, config for one project

All introspection commands support --output=jsonl for machine-readable output.