panman

A tool to create and manage TypeScript workspaces according to certain opinionated standards.

Usage:

• npx panman - Interactive wizard to create a workspace with packages. ⚠️ Warns if run inside an existing workspace.
• npx panman create <name> - Creates a new workspace. ⚠️ Warns if run inside an existing workspace.
• npx panman package create <type> <name> - Adds a new package to an existing workspace. Automatically finds the workspace root (searches for panman.json).
• npx panman package retrofit <type> <name> [--preview] - Retrofits an existing package into standard format. Automatically finds the workspace root (searches for panman.json).
• npx panman retrofit <name> [--preview] - Retrofits an existing workspace into standard format. ⚠️ Warns if run inside an existing workspace.
• npx panman standalone create <type> <name> - Creates a package without a workspace. ⚠️ Warns if run inside an existing workspace.
• npx panman standalone retrofit <type> [dir] [--preview] - Retrofits an existing standalone package. ⚠️ Warns if run inside an existing workspace.
• npx panman setup-remote <remote-url> - Configures git remote and updates repository fields in all packages.

Note: Commands that operate on packages (package create, package retrofit) automatically search for the nearest ancestor panman.json file and execute from that directory. This means you can run them from any subdirectory within your workspace.

Available Templates:

• generic - Basic TypeScript library package
  • Main entry point with type declarations
  • Build with tsc-alias for path alias support
  • Minimal setup for TypeScript libraries
• npm - NPM publishable package with README and version/release scripts
  • Publication-ready configuration with prepublishOnly hook
  • Semantic version management: npm run release:patch|minor|major
  • Auto-generated README.md template
  • Keywords, author, license, and repository fields
• node - Node.js application with dependency-aware development
  • Watches both source files and workspace dependencies
  • Auto-restarts when code or dependencies change
  • VSCode debug configurations included (.vscode/launch.json)
  • Uses tsx for TypeScript execution
  • Use with npm run watch from workspace root for live dependency rebuilding

Template Merging: Non-generic templates are recursively merged with the generic template, combining features while allowing template-specific overrides.

Preview Mode

All retrofit commands support a --preview flag that lets you see what changes would be made without actually modifying your files:

Workspace Retrofit Preview

npx panman retrofit myworkspace --preview

Creates a complete preview of the retrofitted workspace in a temporary directory. The preview location is displayed so you can inspect the structure. The temporary directory is not automatically cleaned up, allowing you to review the changes. Remember to manually delete it when done.

Package Retrofit Preview

npx panman package retrofit npm mypackage --preview

Shows what changes would be made to package.json, tsconfig.json, and lists any template files that would be created. No files are modified.

Standalone Retrofit Preview

npx panman standalone retrofit npm . --preview

Shows what changes would be made to your standalone package configuration files without modifying them.

Turborepo Integration

Panman workspaces are powered by Turborepo for efficient build orchestration and caching. This provides:

Automatic Dependency Building

When packages depend on each other, Turborepo automatically builds dependencies first:

// In packages/app/package.json
{
  "dependencies": {
    "@yourworkspace/lib": "workspace:*"
  }
}

When you run npm run build from the workspace root, Turborepo will:

1. Build @yourworkspace/lib first
2. Then build app with the latest version of lib
3. Cache results for faster subsequent builds

Available Workspace Scripts

• npm run build - Build all packages once (with caching)
• npm run watch - Watch all packages and rebuild on file changes
• npm run clean - Clean all build outputs
• npm run type-check - Type-check all packages without emitting files
• npm run test - Run tests in all packages

Package Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run clean - Remove dist folder
• npm run type-check - Type-check without building

Node packages also include:

• npm run dev - Run with auto-reload (watches src + dependency dist folders)
• npm run start - Run the compiled application

Development Workflow

For library packages:

# From workspace root - watches and rebuilds all packages
npm run watch

For node applications:

# Terminal 1: Watch and rebuild all packages
npm run watch

# Terminal 2: Run the app with auto-restart
cd packages/myapp
npm run dev

This setup means:

• When you change a library's source: turbo watch build rebuilds it
• The rebuilt dist folder triggers the node app to restart automatically
• Changes to the node app's source also trigger a restart

Referencing Workspace Packages

To use one package from another within the workspace:

1. Add it to your package.json:

   npm install @yourworkspace/other-package --workspace=packages/your-package

2. Import and use it:

   import { something } from '@yourworkspace/other-package';

3. Turborepo handles the build order automatically!

npx panman

Interactive workspace creation wizard.

• ❓ Prompts for workspace name
• ❓ Prompts for packages to create (format: type/name, e.g., npm/my-lib or node/my-app)
• ✨ Accepts multiple packages in one session
• 🔄 Executes npx panman create <workspace name> once, followed by
• 🔄 Executes npx panman package create <package type> <package name> for each package

npx panman create <name>

Creates a new workspace with the following steps:

• ❓ Are we in a folder matching <name>? If not, create the folder and move into it.
• 💻 Command git init is executed to initialize a git repository
• 📄 File .gitignore is created according to default.gitignore
• 📄 File package.json is created according to package.default.json
  • package.json's "name" field is updated to the workspace name
• 💻 Command npm pkg set packageManager="npm@$(npm --version)" is executed to lock npm version
• 📄 File tsconfig.json is created according to tsconfig.default.json
• 📄 File turbo.json is created according to turbo.default.json
• 📄 File <name>.code-workspace is created for VSCode multi-root workspace support
• 📄 File panman.json is created (workspace marker file)
• 📁 Folder packages is created
• 📦 Command npm i is executed to install dependencies

npx panman package create <type> <name>

Adds a new package to the workspace.

• 📁 Folder packages/<name> is created
• 📁 Folder packages/<name>/src is created
• 🔍 Template file templates/<type>.json is loaded. If it does not exist, templates/generic.json is used as fallback
• 📄 Files package.json and tsconfig.json are created according to the "package" and "tsconfig" fields in the template, respectively
• 🔀 Both fields are recursively merged with default values from the generic template
• ✨ The package.json's "name" field is updated to the package name
• 📄 Any other files defined in the template's "files" field are created
  • Files are defined either as "path/name.ext": "string content" or "path/name.json": { ... }
  • The <name> placeholder in file contents is replaced with the actual package name
• 📦 Command npm i is executed to install dependencies

npx panman retrofit <name> [--preview]

❗ Make sure to back up your files before doing this.

Converts an existing workspace to panman standards:

• 💻 Command npx panman create <name> is executed in a temporary location
• 🔍 Recursively finds all package.json files (excluding node_modules, dist, .turbo) and backs them up
• 📦 For each package found, creates a corresponding package in the temporary workspace with dependencies preserved
• 🔍 Recursively finds all *.ts files and copies them to the appropriate package's src folder based on nearest ancestor package.json
• 📁 Maintains folder structure where possible
• ❌ The current directory is wiped clean recursively (skipped in preview mode)
• ✅ The temporary directory's contents are recursively copied into the current directory (skipped in preview mode)
• 📦 Command npm i is executed to install dependencies (skipped in preview mode)
• 🗑️ Temporary directory is cleaned up (skipped in preview mode)
• 🔍 When --preview is used, the temporary directory location is displayed and not cleaned up, allowing you to inspect the retrofitted structure

npx panman package retrofit <type> <name> [--preview]

❗ Make sure to back up your files before doing this.

❗ This command assumes that the workspace itself was already retrofitted.

Applies template defaults to an existing package and ensures it follows panman standards.

• 📁 Ensures src/ folder exists (or displays what would be created in preview mode)
• 📄 Files package.json and tsconfig.json are created or updated
• 🔀 Deep Merge Behavior: Existing values are recursively merged with template defaults
  • Custom scripts, dependencies, and configuration are preserved
  • Template defaults fill in missing values
  • Your customizations take precedence
• 📄 Missing template files (defined in the template's "files" field) are created automatically
• ✨ The <name> placeholder in file contents is replaced with the actual package name
• 🔍 When --preview is used, shows what changes would be made without modifying any files

npx panman standalone create <type> <name>

• ❓ Are we in a folder matching <name>? If not, create the folder and move into it.
• 💫 Mirrors functionality of npx panman package create, but does not expect the presence of a workspace.
• 📁 No packages folder is created or expected - rather, the package files are created directly in the current folder.

npx panman standalone retrofit <type> [dir] [--preview]

❗ Make sure to back up your files before doing this.

Retrofits an existing standalone package to panman standards. The [dir] parameter is optional and defaults to the current directory.

• 📁 Ensures src/ folder exists (or displays what would be created in preview mode)
• 📄 Files package.json and tsconfig.json are created or updated
• 🔀 Deep Merge Behavior: Existing values are recursively merged with template defaults (preserves your customizations)
• 🔧 Removes workspace-specific extends paths from tsconfig.json and adds necessary compiler options directly
• 📄 Missing template files (defined in the template's "files" field) are created automatically
• ✨ The <name> placeholder in file contents is replaced with the actual package name (derived from package.json or folder name)
• 🔍 When --preview is used, shows what changes would be made without modifying any files

npx panman setup-remote <remote-url>

Configures git remote origin and updates repository information across the workspace.

• 🔗 Adds or updates the git remote named origin with the provided URL
• 📄 Finds all package.json files in the packages/ folder
• 🔧 Updates the repository field in each package with:
  • The remote URL
  • The relative directory path (e.g., directory: "packages/mypackage")
• 💾 Stages all changes with git add -A
• 💬 Creates a commit with message "Setup git remote and update package repository fields" (if there are changes)
• 🚀 Pushes to remote with upstream tracking (-u flag if not already tracking)
• ✅ Handles existing upstream branches gracefully

VSCode Integration

Panman workspaces include VSCode-specific features for an enhanced development experience:

Multi-Root Workspace

• 📄 <name>.code-workspace file is automatically created
• 🔍 Configures file exclusions (node_modules, dist, .vscode hidden in explorer)
• ⚙️ Sets npm as the default package manager
• 📦 Auto-organize imports on file save
• 🔗 Prefers non-relative import module specifiers

Node Package Debug Support

Node template packages include .vscode/launch.json with debug configurations:

• Debug Current File - Debug any TypeScript file in the package
• Debug Package - Debug the package's main entry point (src/index.ts)

Both configurations use tsx for seamless TypeScript debugging without separate build steps.

Workspace Structure

A panman workspace follows this structure:

my-workspace/
├── .gitignore              # Ignores node_modules, dist, logs, IDE files, etc.
├── package.json            # Workspace root with npm workspaces and turbo scripts
├── tsconfig.json           # Shared TypeScript configuration
├── turbo.json              # Turborepo task pipeline configuration
├── panman.json             # Workspace marker file (version: 1.0.0)
├── my-workspace.code-workspace  # VSCode multi-root workspace
└── packages/
    ├── my-lib/             # Example generic/npm package
    │   ├── src/
    │   │   └── index.ts
    │   ├── package.json
    │   └── tsconfig.json   # Extends workspace tsconfig
    └── my-app/             # Example node package
        ├── .vscode/
        │   └── launch.json # Debug configurations
        ├── src/
        │   └── index.ts
        ├── package.json
        └── tsconfig.json

Configuration Files

.gitignore

• Ignores: node_modules, dist, logs, OS files (.DS_Store, Thumbs.db)
• Ignores: IDE files (.vscode, .idea, vim/emacs temp files)
• Ignores: .cache, *.tmp files, package-lock.json

Root tsconfig.json

• Target: ES2020
• Module: commonjs
• Lib: ES2020
• Strict mode enabled
• Path aliases support (src/*)
• Declaration files enabled

turbo.json

• Configures build pipeline with dependency awareness
• Caches build outputs for performance
• Tasks: build, clean, test, type-check