Configuration

Complete guide to configuring PPM projects with project.toml

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

1. Use semantic versioning for your project version
2. Pin exact versions in production environments
3. Group related scripts with namespaces (e.g., test:frontend, test:backend)
4. Document complex scripts with comments
5. Keep dependencies organized by purpose (framework, utilities, development)
6. Use lock files for reproducible builds
7. 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.