shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

constructive-boilerplate-pgpm-init

使用pgpm init命令初始化工作区和模块。支持PGPM（PostgreSQL）和PNPM（TypeScript/JavaScript）模板，交互模式和非交互模式，以及自定义模板仓库。在使用pgpm init搭建新的工作区或模块时使用。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

Initialize workspaces and modules using the pgpm init command. Supports PGPM (PostgreSQL) and PNPM (TypeScript/JavaScript) templates, interactive and non-interactive modes, and custom template repositories.

When to Apply

Use this skill when:

  • Scaffolding a new workspace or module with pgpm init
  • Using --template, --boilerplate, or -w flags
  • Setting up non-interactive pgpm init for CI/CD
  • Using custom template repositories (e.g., constructive-io/sandbox-templates)

Basic Commands

Create a Workspace

pgpm init workspace

Creates a new PGPM workspace with pgpm.json, pnpm-workspace.yaml, lerna.json, GitHub Actions workflows, Jest testing setup, and TypeScript configuration.

Create a Module

# Inside a workspace
pgpm init

# Or explicitly
pgpm init module

Creates a new PGPM module with pgpm.plan, .control file, package.json, __tests__/, and deploy/, revert/, verify/ directories.

Create Workspace + Module in One Command

# Create workspace first, then module inside it
pgpm init -w

# With a specific template variant
pgpm init --dir pnpm -w
pgpm init --template pnpm/module -w

The -w (or --create-workspace) flag creates a workspace first, then automatically creates the module inside it. Useful when starting from scratch outside any workspace.

Available Templates

Default Repository (constructive-io/pgpm-boilerplates)

PGPM Variant (Default)

| Template | Command | Description | |----------|---------|-------------| | pgpm/workspace | pgpm init workspace or pgpm init -t pgpm/workspace | PGPM workspace with pgpm.json, migrations support | | pgpm/module | pgpm init or pgpm init -t pgpm/module | PGPM module with pgpm.plan, .control file |

PNPM Variant (Pure TypeScript/JavaScript)

| Template | Command | Description | |----------|---------|-------------| | pnpm/workspace | pgpm init workspace --dir pnpm or pgpm init -t pnpm/workspace | Pure PNPM workspace (no pgpm files) | | pnpm/module | pgpm init --dir pnpm or pgpm init -t pnpm/module | Pure PNPM package (no pgpm.plan/.control) |

PGPM Templates (pgpm/)

Use for PostgreSQL extension development with migrations:

pgpm init workspace
pgpm init -t pgpm/workspace
pgpm init -t pgpm/module -w

Creates: pgpm.json / pgpm.config.js (workspace), pgpm.plan (module), .control file (module), migration directories: deploy/, revert/, verify/

PNPM Templates (pnpm/)

Use for pure TypeScript/JavaScript packages without PostgreSQL:

pgpm init workspace --dir pnpm
pgpm init -t pnpm/workspace
pgpm init -t pnpm/module -w

Creates: pnpm-workspace.yaml (workspace), lerna.json (workspace), standard package.json, src/, __tests__/ directories. No pgpm-specific files.

Using --template (Recommended)

The --template flag (or -t) provides a cleaner syntax by combining the directory variant and template type into a single path:

# These are equivalent:
pgpm init workspace --dir pnpm
pgpm init --template pnpm/workspace

# These are equivalent:
pgpm init module --dir pnpm
pgpm init --template pnpm/module

# Short form with -t alias
pgpm init -t pgpm/module
pgpm init -t pnpm/workspace

The --template flag parses the path by splitting on the first /:

  • Everything before the slash becomes the --dir value
  • Everything after becomes the template type (workspace/module)

Using --boilerplate

# Interactive selection from all available templates
pgpm init --boilerplate

# Select a specific template path
pgpm init pnpm/workspace --boilerplate

When using --boilerplate in CI/CD, you must specify the template path:

# This will error in non-interactive mode
pgpm init --boilerplate --no-tty  # ERROR

# Correct: specify the template path
pgpm init pnpm/workspace --boilerplate --no-tty \
  --name my-workspace \
  --fullName "Your Name" \
  --email "you@example.com" \
  --username your-github-username \
  --license MIT

Custom Template Repositories

# Use a different repository
pgpm init workspace --repo owner/repo
pgpm init workspace --repo https://github.com/owner/repo.git

# Use a specific branch
pgpm init workspace --repo owner/repo --from-branch develop

# Example: Constructive Next.js app template
pgpm init -w --repo constructive-io/sandbox-templates --template nextjs/constructive-app

Non-Interactive Mode

For CI/CD pipelines and automation, use --no-tty or set CI=true:

pgpm init workspace --no-tty \
  --name my-workspace \
  --fullName "Your Name" \
  --email "you@example.com" \
  --username your-github-username \
  --license MIT

Required Parameters for Non-Interactive Workspace

| Parameter | Description | |-----------|-------------| | --name | Workspace name (becomes directory name) | | --fullName | Author's full name | | --email | Author's email | | --username | GitHub username | | --license | License (MIT, Apache-2.0, etc.) |

Required Parameters for Non-Interactive Module

| Parameter | Description | |-----------|-------------| | --moduleName | Module name | | --moduleDesc | Module description | | --fullName | Author's full name | | --email | Author's email | | --username | GitHub username | | --repoName | Repository name | | --license | License | | --access | npm access level (public/restricted) | | --extensions | PostgreSQL extensions (comma-separated) |

Example:

pgpm init --no-tty \
  --moduleName my-module \
  --moduleDesc "My PostgreSQL module" \
  --fullName "Your Name" \
  --email "you@example.com" \
  --username your-github-username \
  --repoName my-workspace \
  --license MIT \
  --access public \
  --extensions "plpgsql,uuid-ossp"

Workspace Type Requirements

Templates specify what type of workspace they require via requiresWorkspace:

| Value | Meaning | |-------|---------| | "pgpm" | Must be inside a PGPM workspace (has pgpm.json) | | "pnpm" | Must be inside a PNPM workspace (has pnpm-workspace.yaml) | | "lerna" | Must be inside a Lerna workspace (has lerna.json) | | "npm" | Must be inside an npm workspace (package.json with workspaces) | | false | Can be created anywhere |

CLI Options

| Option | Description | |--------|-------------| | --help, -h | Show help message | | --cwd <directory> | Working directory (default: current directory) | | --repo <repo> | Template repository (default: constructive-io/pgpm-boilerplates) | | --from-branch <branch> | Branch/tag to use when cloning repo | | --dir <variant> | Template variant directory (e.g., pnpm, supabase) | | --template, -t <path> | Full template path (e.g., pnpm/module) - combines dir and type | | --boilerplate | Prompt to select from available boilerplates | | --create-workspace, -w | Create a workspace first, then create the module inside it | | --no-tty | Run in non-interactive mode |

Note: The -W flag is used for the interactive workspace recovery prompt (when you run pgpm init outside a workspace and it asks if you want to create one).

Workflow Examples

Starting a New Project

# 1. Create workspace
pgpm init workspace
cd my-workspace

# 2. Create first module
pgpm init
cd packages/my-module

# 3. Add a database change
pgpm add my_first_change

# 4. Deploy to database
pgpm deploy --createdb

Quick Start with -w Flag

# Create workspace + module in one command
pgpm init -w
# Prompts for workspace name, then module name
# Creates workspace and module inside packages/

# With PNPM template variant
pgpm init --template pnpm/module -w

Create a Pure TypeScript Monorepo

# 1. Create PNPM workspace
pgpm init workspace --dir pnpm
cd my-workspace

# 2. Create packages
pgpm init --dir pnpm  # Creates TypeScript package

CI/CD Pipeline Setup

# .github/workflows/setup.yaml
jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - name: Install pgpm
        run: npm install -g pgpm

      - name: Create workspace
        run: |
          pgpm init workspace --no-tty \
            --name test-workspace \
            --fullName "CI Bot" \
            --email "ci@example.com" \
            --username ci-bot \
            --license MIT

Template Caching

Templates are cached locally under ~/.pgpm/cache/repos with a one-day TTL. To force a fresh pull:

pgpm cache clean

Best Practices

  1. Use --template (or -t) for specifying templates — cleaner than --dir + positional arg
  2. Use -w flag to create workspace + module in one command when starting fresh
  3. Use --no-tty in CI/CD pipelines to avoid hanging on prompts
  4. Pin template versions with --from-branch for reproducible builds
  5. Use --boilerplate when exploring available templates interactively
  6. Create organization-specific boilerplates for standardized project setup
  7. Use pgpm cache clean if templates seem outdated