Configuration

PPM uses a single project.toml file to configure your entire polyglot project. This file defines dependencies, scripts, and project metadata in a simple, readable format.

Basic Structure

Every PPM project starts with a project.toml file in the root directory:

[project]
name = "my-project"
version = "1.0.0"
description = "A polyglot application"

[dependencies.js]
# JavaScript/Node.js dependencies

[dependencies.python]
# Python dependencies

[scripts]
# Custom scripts for your project

Project Metadata

The [project] section contains basic information about your project:

[project]
name = "awesome-app"           # Project name (required)
version = "1.0.0"             # Semantic version (required)
description = "My awesome polyglot app"  # Optional description
author = "Your Name"          # Optional author
license = "MIT"               # Optional license
repository = "https://github.com/user/repo"  # Optional repository URL

Field Descriptions

Field	Type	Required	Description
`name`	String	✅	Project name, used for identification
`version`	String	✅	Semantic version (e.g., “1.0.0”)
`description`	String	❌	Brief project description
`author`	String	❌	Project author or maintainer
`license`	String	❌	License identifier (e.g., “MIT”, “GPL-3.0”)
`repository`	String	❌	Repository URL

JavaScript Dependencies

Define JavaScript and Node.js dependencies in the [dependencies.js] section:

[dependencies.js]
# Framework dependencies
react = "^18.2.0"
vue = "^3.3.0"

# Utility libraries
axios = "^1.6.0"
lodash = "^4.17.21"

# Development dependencies
typescript = "^5.0.0"
vite = "^5.0.0"
"@types/react" = "^18.2.0"

# Build tools
webpack = "^5.88.0"
babel = "^7.22.0"

Version Specifications

PPM supports standard npm semantic versioning:

Format	Example	Description
Exact	`"1.2.3"`	Exact version only
Caret	`"^1.2.3"`	Compatible within major version
Tilde	`"~1.2.3"`	Compatible within minor version
Range	`">=1.2.0 <2.0.0"`	Version range
Latest	`"latest"`	Always use latest version

Scoped Packages

Include scoped packages with quotes:

[dependencies.js]
"@types/node" = "^20.0.0"
"@vue/cli" = "^5.0.0"
"@testing-library/react" = "^13.0.0"

Python Dependencies

Define Python packages in the [dependencies.python] section:

[dependencies.python]
# Web frameworks
flask = "^3.0.0"
django = "^4.2.0"
fastapi = "^0.104.0"

# Data science
numpy = "^1.24.0"
pandas = "^2.0.0"
scikit-learn = "^1.3.0"

# Utilities
requests = "^2.31.0"
python-dotenv = "^1.0.0"

# Development
pytest = "^7.4.0"
black = "^23.0.0"

Python Version Constraints

PPM supports PEP 440 version specifiers:

Format	Example	Description
Exact	`"==1.2.3"`	Exact version
Compatible	`"~=1.2.3"`	Compatible release
Greater/Less	`">=1.2.0"`	Minimum version
Exclude	`"!=1.2.3"`	Exclude specific version
Caret (npm-style)	`"^1.2.3"`	Compatible within major version

Package Extras

Include optional dependencies with extras:

[dependencies.python]
requests = { version = "^2.31.0", extras = ["security"] }
django = { version = "^4.2.0", extras = ["bcrypt", "argon2"] }

Scripts

Define custom scripts in the [scripts] section to automate common tasks:

[scripts]
# Development
dev = "ppm run dev:parallel"
"dev:frontend" = "cd frontend && npm run dev"
"dev:backend" = "cd backend && python app.py"
"dev:parallel" = "ppm run dev:backend & ppm run dev:frontend"

# Building
build = "ppm run build:all"
"build:frontend" = "cd frontend && npm run build"
"build:backend" = "echo 'Python backend ready'"
"build:all" = "ppm run build:frontend && ppm run build:backend"

# Testing
test = "ppm run test:all"
"test:frontend" = "cd frontend && npm test"
"test:backend" = "cd backend && python -m pytest"
"test:all" = "ppm run test:frontend && ppm run test:backend"

# Deployment
deploy = "ppm run build && ppm run deploy:prod"
"deploy:staging" = "echo 'Deploying to staging...'"
"deploy:prod" = "echo 'Deploying to production...'"

# Database
"db:migrate" = "cd backend && python manage.py migrate"
"db:seed" = "cd backend && python manage.py loaddata fixtures/sample_data.json"

# Linting and formatting
lint = "ppm run lint:all"
"lint:js" = "cd frontend && npm run lint"
"lint:python" = "cd backend && flake8 ."
"lint:all" = "ppm run lint:js && ppm run lint:python"

format = "ppm run format:all"
"format:js" = "cd frontend && npm run format"
"format:python" = "cd backend && black ."
"format:all" = "ppm run format:js && ppm run format:python"

Script Features

Cross-platform: Scripts work on Windows, macOS, and Linux
Environment-aware: Python scripts run in the virtual environment
Parallel execution: Use & to run scripts simultaneously
Sequential execution: Use && to run scripts in sequence
Namespacing: Use : to group related scripts

Built-in Script Variables

PPM provides several built-in variables for scripts:

[scripts]
info = "echo 'Project: $PPM_PROJECT_NAME v$PPM_PROJECT_VERSION'"
paths = "echo 'Root: $PPM_PROJECT_ROOT, Python: $PPM_PYTHON_PATH'"

Variable	Description
`$PPM_PROJECT_NAME`	Project name from `project.toml`
`$PPM_PROJECT_VERSION`	Project version from `project.toml`
`$PPM_PROJECT_ROOT`	Absolute path to project root
`$PPM_PYTHON_PATH`	Path to the Python virtual environment

Environment Configuration

Python Virtual Environment

PPM automatically manages Python virtual environments, but you can customize the behavior:

[python]
version = "3.11"              # Prefer specific Python version
venv_dir = ".venv"           # Custom virtual environment directory
requirements_file = "requirements.txt"  # Custom requirements file location

Node.js Configuration

Configure Node.js behavior for JavaScript projects:

[nodejs]
version = "18"               # Prefer specific Node.js version
package_manager = "npm"      # Package manager: npm, yarn, or pnpm
package_file = "package.json"  # Custom package.json location

Advanced Configuration

Development Dependencies

Separate development-only dependencies:

[dependencies.js]
# Production dependencies
react = "^18.2.0"
axios = "^1.6.0"

[dev-dependencies.js]
# Development-only dependencies
typescript = "^5.0.0"
vite = "^5.0.0"
"@types/react" = "^18.2.0"

[dependencies.python]
# Production dependencies
flask = "^3.0.0"
numpy = "^1.24.0"

[dev-dependencies.python]
# Development-only dependencies
pytest = "^7.4.0"
black = "^23.0.0"
mypy = "^1.5.0"

Environment-Specific Configuration

Define different configurations for different environments:

[environments.development]
[environments.development.dependencies.js]
react = "^18.2.0"

[environments.development.dependencies.python]
flask = "^3.0.0"

[environments.production]
[environments.production.dependencies.js]
react = "18.2.37"  # Exact versions in production

[environments.production.dependencies.python]
flask = "3.0.0"
gunicorn = "^21.0.0"  # Production server

Custom Package Sources

Configure custom package registries:

[sources]
[sources.js]
registry = "https://registry.npmjs.org/"
# For private registries:
# registry = "https://npm.internal.company.com/"

[sources.python]
index_url = "https://pypi.org/simple/"
# For private registries:
# index_url = "https://pypi.internal.company.com/simple/"

Lock File Configuration

Control lock file behavior:

[lock]
enabled = true               # Generate lock files
file = "ppm.lock"           # Custom lock file name
auto_update = false         # Auto-update dependencies

File Structure Examples

Here are some complete examples for different project types:

Full-Stack Web Application

[project]
name = "my-web-app"
version = "1.0.0"
description = "Full-stack React + Flask application"
author = "Developer Name"
license = "MIT"

[dependencies.js]
react = "^18.2.0"
react-dom = "^18.2.0"
react-router-dom = "^6.15.0"
axios = "^1.6.0"
typescript = "^5.0.0"
vite = "^5.0.0"

[dependencies.python]
flask = "^3.0.0"
flask-cors = "^4.0.0"
flask-sqlalchemy = "^3.0.0"
python-dotenv = "^1.0.0"

[dev-dependencies.js]
"@types/react" = "^18.2.0"
"@types/react-dom" = "^18.2.0"
"@vitejs/plugin-react" = "^4.0.0"

[dev-dependencies.python]
pytest = "^7.4.0"
pytest-flask = "^1.2.0"
black = "^23.0.0"

[scripts]
dev = "ppm run dev:parallel"
"dev:frontend" = "cd frontend && npm run dev"
"dev:backend" = "cd backend && flask run"
"dev:parallel" = "ppm run dev:backend & ppm run dev:frontend"

build = "cd frontend && npm run build"
test = "ppm run test:frontend && ppm run test:backend"
"test:frontend" = "cd frontend && npm test"
"test:backend" = "cd backend && pytest"

"db:init" = "cd backend && flask db init"
"db:migrate" = "cd backend && flask db migrate"
"db:upgrade" = "cd backend && flask db upgrade"

Data Science Project

[project]
name = "data-analysis"
version = "0.1.0"
description = "Data analysis with Jupyter and React dashboard"

[dependencies.js]
react = "^18.2.0"
"@nivo/core" = "^0.84.0"
"@nivo/line" = "^0.84.0"
axios = "^1.6.0"

[dependencies.python]
jupyter = "^1.0.0"
pandas = "^2.0.0"
numpy = "^1.24.0"
matplotlib = "^3.7.0"
seaborn = "^0.12.0"
scikit-learn = "^1.3.0"
fastapi = "^0.104.0"
uvicorn = "^0.23.0"

[scripts]
notebook = "cd analysis && jupyter lab"
dashboard = "cd dashboard && npm start"
api = "cd api && uvicorn main:app --reload"
analyze = "cd analysis && python analysis.py"

Microservices Project

[project]
name = "microservices-app"
version = "2.1.0"
description = "Microservices with React frontend and Python services"

[dependencies.js]
react = "^18.2.0"
"@mui/material" = "^5.14.0"
axios = "^1.6.0"
react-query = "^3.39.0"

[dependencies.python]
fastapi = "^0.104.0"
uvicorn = "^0.23.0"
pydantic = "^2.4.0"
sqlalchemy = "^2.0.0"
redis = "^5.0.0"
celery = "^5.3.0"

[scripts]
dev = "ppm run dev:all"
"dev:frontend" = "cd frontend && npm start"
"dev:auth" = "cd services/auth && uvicorn main:app --port 8001 --reload"
"dev:api" = "cd services/api && uvicorn main:app --port 8002 --reload"
"dev:worker" = "cd services/worker && celery worker -A tasks"
"dev:all" = "ppm run dev:auth & ppm run dev:api & ppm run dev:worker & ppm run dev:frontend"

docker = "docker-compose up -d"
"docker:build" = "docker-compose build"

Validation and Best Practices

Configuration Validation

PPM validates your project.toml file and provides helpful error messages:

ppm validate

Common validation errors:

Missing required fields (name, version)
Invalid semantic versions
Conflicting dependency versions
Invalid script syntax

Best Practices

Use semantic versioning for your project version
Pin exact versions in production environments
Group related scripts with namespaces (e.g., test:frontend, test:backend)
Document complex scripts with comments
Keep dependencies organized by purpose (framework, utilities, development)
Use lock files for reproducible builds
Separate dev and production dependencies

Configuration Tips

Start simple: Begin with basic dependencies and add complexity as needed
Use consistent naming: Follow consistent patterns for script names
Test your scripts: Ensure all scripts work across different platforms
Version control: Always commit your project.toml and lock files
Document environment setup: Include setup instructions in your README

Migration from Other Tools

From package.json

Convert existing Node.js projects:

# PPM can import from existing package.json
ppm import --from package.json

From requirements.txt

Convert existing Python projects:

# PPM can import from existing requirements.txt
ppm import --from requirements.txt

From Both

For existing polyglot projects:

# Import from both files
ppm import --from package.json --from requirements.txt

Your project.toml file is the heart of your PPM project. Take time to structure it well, and you’ll enjoy a smooth development experience across your entire polyglot application.

Getting Started

Core Concepts

Guides

Configuration

Configuration

Basic Structure

Project Metadata

Field Descriptions

JavaScript Dependencies

Version Specifications

Scoped Packages

Python Dependencies

Python Version Constraints

Package Extras

Scripts

Script Features

Built-in Script Variables

Environment Configuration

Python Virtual Environment

Node.js Configuration

Advanced Configuration

Development Dependencies

Environment-Specific Configuration

Custom Package Sources

Lock File Configuration

File Structure Examples

Full-Stack Web Application

Data Science Project

Microservices Project

Validation and Best Practices

Configuration Validation

Best Practices

Configuration Tips

Migration from Other Tools

From package.json

From requirements.txt

From Both

Getting Started

Core Concepts

Guides

​Configuration

​Basic Structure

​Project Metadata

​Field Descriptions

​JavaScript Dependencies

​Version Specifications

​Scoped Packages

​Python Dependencies

​Python Version Constraints

​Package Extras

​Scripts

​Script Features

​Built-in Script Variables

​Environment Configuration

​Python Virtual Environment

​Node.js Configuration

​Advanced Configuration

​Development Dependencies

​Environment-Specific Configuration

​Custom Package Sources

​Lock File Configuration

​File Structure Examples

​Full-Stack Web Application

​Data Science Project

​Microservices Project

​Validation and Best Practices

​Configuration Validation

​Best Practices

​Configuration Tips

​Migration from Other Tools

​From package.json

​From requirements.txt

​From Both

Configuration

Basic Structure

Project Metadata

Field Descriptions

JavaScript Dependencies

Version Specifications

Scoped Packages

Python Dependencies

Python Version Constraints

Package Extras

Scripts

Script Features

Built-in Script Variables

Environment Configuration

Python Virtual Environment

Node.js Configuration

Advanced Configuration

Development Dependencies

Environment-Specific Configuration

Custom Package Sources

Lock File Configuration

File Structure Examples

Full-Stack Web Application

Data Science Project

Microservices Project

Validation and Best Practices

Configuration Validation

Best Practices

Configuration Tips

Migration from Other Tools

From package.json

From requirements.txt

From Both