constructive-boilerplate-authoring

Create and customize boilerplate templates for pgpm init.

Overview

PGPM uses the genomic library to scaffold projects from templates. Templates are stored in a boilerplate repository (default: constructive-io/pgpm-boilerplates) and use placeholder substitution for customization.

Template Repository Structure

my-boilerplates/
  .boilerplates.json       # Root config (points to default directory)
  pgpm/                    # Default template variant (PGPM)
    module/
      .boilerplate.json    # Module template config
      package.json         # Template files with placeholders
      pgpm.plan
      ...
    workspace/
      .boilerplate.json    # Workspace template config
      package.json
      pgpm.json
      ...
  pnpm/                    # Alternative variant (pure PNPM, no pgpm files)
    module/
      .boilerplate.json
      ...
    workspace/
      .boilerplate.json
      ...

Root Configuration

The .boilerplates.json file at the repository root specifies the default template directory:

{
  "dir": "pgpm"
}

Template Configuration

Each template has a .boilerplate.json file defining its type, workspace requirements, and questions.

Basic Structure

{
  "type": "workspace",
  "questions": [
    {
      "name": "____repoName____",
      "message": "Enter the repository name",
      "required": true
    }
  ]
}

Template Types

Type	Description
workspace	Creates a new monorepo workspace
module	Creates a package within a workspace
generic	Standalone template (no workspace context)

Workspace Requirements

The requiresWorkspace field controls what type of workspace the template needs:

{
  "type": "module",
  "requiresWorkspace": "pgpm"
}

Value	Description
"pgpm"	Requires PGPM workspace (pgpm.json), creates pgpm.plan/.control files
"pnpm"	Requires PNPM workspace (pnpm-workspace.yaml)
"lerna"	Requires Lerna workspace (lerna.json)
"npm"	Requires npm workspace (package.json with workspaces)
false	No workspace required

Placeholder System

Templates use the ____placeholder____ pattern (4 underscores on each side) for variable substitution:

{
  "name": "@____username____/____moduleName____",
  "version": "0.0.1",
  "description": "____moduleDesc____",
  "author": "____fullName____ <____email____>"
}

Question Configuration

Question Fields

Field	Type	Description
name	string	Placeholder name (e.g., ____fullName____)
message	string	Prompt shown to user
required	boolean	Whether the field is required
type	string	Input type: text, list, checkbox
options	string[]	Static options for list/checkbox
default	any	Static default value
defaultFrom	string	Resolver for dynamic default
setFrom	string	Auto-set value (skips prompt)
optionsFrom	string	Resolver for dynamic options

Question Types

Text Input (default):

{
  "name": "____moduleName____",
  "message": "Enter the module name",
  "required": true
}

List Selection:

{
  "name": "____access____",
  "message": "Module access?",
  "type": "list",
  "options": ["public", "restricted"],
  "default": "public"
}

Checkbox (multi-select):

{
  "name": "____extensions____",
  "message": "Select PostgreSQL extensions",
  "type": "checkbox",
  "options": ["plpgsql", "uuid-ossp", "citext", "pgcrypto"]
}

Resolvers

Resolvers dynamically populate values from the environment or workspace context.

defaultFrom Resolvers:

Resolver	Description
git.user.name	Git config user.name
git.user.email	Git config user.email
npm.whoami	npm whoami result
workspace.dirname	Current directory name

setFrom Resolvers (auto-set, skips prompt):

Resolver	Description
workspace.name	Workspace name from pgpm.json/package.json
workspace.author.name	Workspace author name
workspace.author.email	Workspace author email
workspace.license	Workspace license
workspace.organization.name	Workspace organization

optionsFrom Resolvers:

Resolver	Description
licenses	List of SPDX license identifiers

Example: Complete Module Template

{
  "type": "module",
  "requiresWorkspace": "pgpm",
  "questions": [
    {
      "name": "____fullName____",
      "message": "Enter author full name",
      "setFrom": "workspace.author.name",
      "defaultFrom": "git.user.name",
      "required": true
    },
    {
      "name": "____email____",
      "message": "Enter author email",
      "setFrom": "workspace.author.email",
      "defaultFrom": "git.user.email",
      "required": true
    },
    {
      "name": "____moduleName____",
      "message": "Enter the module name",
      "required": true
    },
    {
      "name": "____moduleDesc____",
      "message": "Enter the module description",
      "required": true
    },
    {
      "name": "____repoName____",
      "message": "Enter the repository name",
      "setFrom": "workspace.name",
      "required": true
    },
    {
      "name": "____username____",
      "message": "Enter your github username",
      "setFrom": "workspace.organization.name",
      "defaultFrom": "npm.whoami",
      "required": true
    },
    {
      "name": "____access____",
      "message": "Module access?",
      "type": "list",
      "options": ["public", "restricted"],
      "default": "public",
      "required": true
    },
    {
      "name": "____license____",
      "message": "Choose a license",
      "type": "list",
      "optionsFrom": "licenses",
      "setFrom": "workspace.license",
      "required": true
    }
  ]
}

Creating a Custom Boilerplate Repository

1. Create a new repository with the structure above
2. Add .boilerplates.json pointing to your default directory
3. Create template directories with .boilerplate.json configs
4. Add template files with ____placeholder____ patterns
5. Use with pgpm init --repo owner/your-boilerplates

Using Custom Templates

# Use your own boilerplate repository
pgpm init workspace --repo myorg/my-boilerplates

# Use a specific branch
pgpm init workspace --repo myorg/my-boilerplates --from-branch develop

# Use a variant directory
pgpm init workspace --repo myorg/my-boilerplates --dir custom-variant

# Use the --template flag (recommended)
pgpm init --template pnpm/module --repo myorg/my-boilerplates
pgpm init -t custom-variant/module --repo myorg/my-boilerplates

# Create workspace + module in one command
pgpm init -t pnpm/module -w --repo myorg/my-boilerplates

Best Practices

1. Use setFrom for values that should inherit from workspace context
2. Use defaultFrom for sensible defaults that users can override
3. Keep placeholder names descriptive and consistent
4. Document custom templates in your repository README
5. Test templates with --no-tty to ensure all required fields are defined