> ## Documentation Index
> Fetch the complete documentation index at: https://kaiser.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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:

```toml theme={null}
[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

```toml theme={null}
[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

```toml theme={null}
[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

```toml theme={null}
[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:

```bash theme={null}
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:

```bash theme={null}
# PPM can import from existing package.json
ppm import --from package.json
```

### From requirements.txt

Convert existing Python projects:

```bash theme={null}
# PPM can import from existing requirements.txt
ppm import --from requirements.txt
```

### From Both

For existing polyglot projects:

```bash theme={null}
# 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.