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:

1. Workspace projects — any project containing a putnami.template.json
2. Convention directories — <domain>/templates/*/ paths in the workspace
3. 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