Templates

Templates are project scaffolds that let you create fully configured projects in one command. They are decoupled from extensions — each template is defined by a putnami.template.json manifest and can be installed, versioned, and published independently.

Creating a project from a template

putnami projects create my-app --template typescript-web

The --template flag is required. Options:

--template <name> — Template to scaffold from (required)
--path <path> — Custom project path (default: determined by workspace scopes)

Official templates

Each language extension ships its own templates:

Template	Extension	Description
`typescript-web`	`@putnami/typescript`	React SSR web app with file-based routing, layouts, and client hydration
`typescript-server`	`@putnami/typescript`	HTTP server with `@putnami/application`, file-based API routing, and tests
`typescript-library`	`@putnami/typescript`	TypeScript library with exports and tests
`go-server`	`@putnami/go`	HTTP server with `net/http`, JSON endpoint, and tests
`go-library`	`@putnami/go`	Go library with exported function and tests
`python-server`	`@putnami/python`	FastAPI server with uvicorn and tests
`python-library`	`@putnami/python`	Python library with importable module and tests

# TypeScript
putnami projects create my-app --template typescript-web
putnami projects create my-api --template typescript-server
putnami projects create my-lib --template typescript-library

# Go
putnami projects create my-api --template go-server
putnami projects create my-lib --template go-library

# Python
putnami projects create my-api --template python-server
putnami projects create my-lib --template python-library

Every template produces a project you can serve or test immediately:

putnami serve my-app
putnami test my-lib

Template file processing

Files ending in .template are processed with variable substitution. Other files are copied as-is.

Available variables:

Variable	Description
`<%= projectName %>`	The project name passed to `create`
`<%= projectPath %>`	Path to the project relative to workspace root
`<%= projectModule %>`	Normalized module name (e.g., `my-lib` becomes `my_lib` for Python)
`<%= putnamiVersion %>`	Current Putnami CLI version
`<%= workspaceRelativePath %>`	Relative path from project to workspace root

Template discovery

Templates are discovered from three sources:

Workspace projects — any project containing a putnami.template.json
Convention directories — <domain>/templates/*/ paths in the workspace
Installed templates — downloaded from the template registry

Installing external templates

Configure installable templates in putnami.workspace.json:

{
  "templates": [
    "typescript-library",
    "go-server:^1.0.0"
  ]
}

Then install:

putnami templates install

Or install as part of the combined workspace setup:

putnami install

Templates are downloaded and stored in .putnami/templates/<name>/<version>/. The unified lock file (putnami.lock.json) ensures deterministic installs.

Managing templates

putnami templates list               # List configured and discovered templates
putnami templates update             # Update to latest compatible versions
putnami templates remove <name>      # Remove an installed template
putnami templates validate [path]    # Validate a template manifest
putnami templates test [path]        # Test a template by rendering it
putnami templates package [path]     # Package for distribution

Publishing templates

To publish your own template, configure the template-archives publish channel in the template project's putnami.json:

{
  "publish": ["template-archives"]
}

Then package and publish:

putnami templates package ./my-template
putnami publish --projects my-template