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

# Quick Start Guide

> Build your first polyglot application with PPM in under 10 minutes

# Quick Start Guide

This guide will walk you through creating your first polyglot project with PPM, combining JavaScript and Python in a single, unified workflow.

## What We'll Build

A full-stack web application with:

* **React frontend** (JavaScript/TypeScript)
* **Flask backend** (Python)
* **Real-time data processing** using NumPy and Pandas
* **Unified development workflow** with PPM

## Prerequisites

Before starting, make sure you have:

<Steps>
  <Step title="Install PPM">
    If you haven't already, install PPM using our one-liner:

    **Windows:**

    ```powershell theme={null}
    Invoke-WebRequest https://raw.githubusercontent.com/VesperAkshay/polypm/main/install.ps1 -UseBasicParsing | Invoke-Expression
    ```

    **macOS/Linux:**

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/VesperAkshay/polypm/main/install.sh | bash
    ```
  </Step>

  <Step title="Verify Installation">
    ```bash theme={null}
    ppm --version
    ```

    You should see the PPM version number.
  </Step>

  <Step title="Check Dependencies">
    Make sure you have Node.js and Python installed:

    ```bash theme={null}
    node --version  # Should be 14 or later
    python --version  # Should be 3.8 or later
    ```
  </Step>
</Steps>

## Step 1: Create a New Project

Initialize a new PPM project:

```bash theme={null}
ppm init my-fullstack-app
cd my-fullstack-app
```

This creates a new directory with a basic `project.toml` configuration file.

## Step 2: Set Up Project Structure

Create the basic project structure:

```bash theme={null}
mkdir frontend backend
```

Your project should now look like:

```
my-fullstack-app/
├── project.toml
├── frontend/
└── backend/
```

## Step 3: Configure Dependencies

Edit the `project.toml` file to define your dependencies:

```toml theme={null}
[project]
name = "my-fullstack-app"
version = "1.0.0"
description = "A full-stack app demonstrating PPM capabilities"

[dependencies.js]
react = "^18.2.0"
react-dom = "^18.2.0"
typescript = "^5.0.0"
vite = "^5.0.0"
axios = "^1.6.0"
"@types/react" = "^18.2.0"
"@types/react-dom" = "^18.2.0"
"@vitejs/plugin-react" = "^4.0.0"

[dependencies.python]
flask = "^3.0.0"
flask-cors = "^4.0.0"
numpy = "^1.24.0"
pandas = "^2.0.0"
requests = "^2.31.0"

[scripts]
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"
build = "ppm run build:frontend"
"build:frontend" = "cd frontend && npm run build"
```

## Step 4: Install Dependencies

Now install all dependencies with a single command:

```bash theme={null}
ppm install
```

<Note>
  PPM will automatically:

  * Create and activate a Python virtual environment
  * Install all JavaScript packages in the appropriate directory
  * Install all Python packages in the virtual environment
  * Set up the project for development
</Note>

## Step 5: Create the Frontend

### Frontend Package Configuration

Create `frontend/package.json`:

```json theme={null}
{
  "name": "my-fullstack-app-frontend",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "axios": "^1.6.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.15",
    "@types/react-dom": "^18.2.7",
    "@vitejs/plugin-react": "^4.0.3",
    "typescript": "^5.0.2",
    "vite": "^4.4.5"
  }
}
```

### Vite Configuration

Create `frontend/vite.config.ts`:

```typescript theme={null}
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
  },
})
```

### React Application

Create `frontend/src/App.tsx`:

```tsx theme={null}
import React, { useState, useEffect } from 'react';
import axios from 'axios';

interface ApiData {
  message: string;
  data: number[];
  analysis: {
    mean: number;
    std: number;
    count: number;
  };
}

function App() {
  const [data, setData] = useState<ApiData | null>(null);
  const [loading, setLoading] = useState(false);

  const fetchData = async () => {
    setLoading(true);
    try {
      const response = await axios.get<ApiData>('http://localhost:5000/api/data');
      setData(response.data);
    } catch (error) {
      console.error('Error fetching data:', error);
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    fetchData();
  }, []);

  return (
    <div style={{ padding: '2rem', fontFamily: 'Arial, sans-serif' }}>
      <h1>🚀 PPM Full-Stack Demo</h1>
      <p>React frontend communicating with Python Flask backend</p>
      
      <button onClick={fetchData} disabled={loading}>
        {loading ? 'Loading...' : 'Refresh Data'}
      </button>
      
      {data && (
        <div style={{ marginTop: '1rem', padding: '1rem', background: '#f0f0f0' }}>
          <h3>Data from Python Backend:</h3>
          <p><strong>Message:</strong> {data.message}</p>
          <p><strong>Sample Size:</strong> {data.analysis.count}</p>
          <p><strong>Mean:</strong> {data.analysis.mean.toFixed(2)}</p>
          <p><strong>Standard Deviation:</strong> {data.analysis.std.toFixed(2)}</p>
        </div>
      )}
    </div>
  );
}

export default App;
```

### Entry Point and HTML

Create `frontend/src/main.tsx`:

```tsx theme={null}
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)
```

Create `frontend/index.html`:

```html theme={null}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>PPM Full-Stack Demo</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

## Step 6: Create the Backend

### Python Requirements

Create `backend/requirements.txt`:

```txt theme={null}
flask==3.0.0
flask-cors==4.0.0
numpy==1.24.0
pandas==2.0.0
requests==2.31.0
```

### Flask Application

Create `backend/app.py`:

```python theme={null}
from flask import Flask, jsonify
from flask_cors import CORS
import numpy as np
import pandas as pd
from datetime import datetime

app = Flask(__name__)
CORS(app)  # Enable CORS for React frontend

@app.route('/api/data')
def get_data():
    """Generate sample data using NumPy and analyze with Pandas"""
    # Generate random data
    sample_data = np.random.normal(50, 15, 100).tolist()
    
    # Analyze with Pandas
    df = pd.DataFrame({'values': sample_data})
    analysis = {
        'mean': float(df['values'].mean()),
        'std': float(df['values'].std()),
        'count': int(df['values'].count()),
        'min': float(df['values'].min()),
        'max': float(df['values'].max())
    }
    
    return jsonify({
        'message': 'Data generated successfully with Python!',
        'timestamp': datetime.now().isoformat(),
        'data': sample_data,
        'analysis': analysis
    })

@app.route('/')
def home():
    return jsonify({
        'message': 'PPM Demo Backend - Python Flask API',
        'endpoints': ['/api/data'],
        'status': 'running'
    })

if __name__ == '__main__':
    print("🐍 Starting Python Flask backend...")
    print("📊 NumPy and Pandas loaded for data processing")
    app.run(debug=True, port=5000)
```

## Step 7: Run Your Application

Now comes the magic! Start both frontend and backend with a single command:

```bash theme={null}
ppm run dev
```

This will:

1. **Start the Python Flask backend** on port 5000
2. **Start the React development server** on port 3000
3. **Run both simultaneously** with proper environment activation

## Step 8: See It in Action

1. **Open your browser** to [http://localhost:3000](http://localhost:3000)
2. **See the React frontend** displaying data from the Python backend
3. **Click "Refresh Data"** to see new random data generated by NumPy
4. **Watch the real-time communication** between JavaScript and Python

## What Just Happened?

<CardGroup cols={2}>
  <Card title="Unified Dependencies" icon="package">
    PPM installed both npm and pip packages from a single configuration file
  </Card>

  <Card title="Environment Management" icon="layer-group">
    Python virtual environment was created automatically, Node.js dependencies managed separately
  </Card>

  <Card title="Cross-Language Scripts" icon="terminal">
    One command started both frontend and backend with proper environment activation
  </Card>

  <Card title="Seamless Integration" icon="link">
    React frontend communicates with Python backend through well-configured CORS
  </Card>
</CardGroup>

## Compare with Traditional Approach

### Without PPM (Traditional)

```bash theme={null}
# Frontend setup
cd frontend
npm install
npm run dev

# Backend setup (separate terminal)
cd ../backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python app.py

# Result: 8+ commands, 2 terminals, manual environment management
```

### With PPM

```bash theme={null}
# Everything
ppm install
ppm run dev

# Result: 2 commands, automatic everything
```

## Next Steps

Now that you have a working polyglot application, explore more PPM features:

<CardGroup cols={2}>
  <Card title="Add More Dependencies" icon="plus" href="/cli/add">
    Learn how to add new JavaScript or Python packages
  </Card>

  <Card title="Advanced Configuration" icon="gear" href="/configuration">
    Explore advanced project.toml configurations
  </Card>

  <Card title="Production Deployment" icon="rocket" href="/guides/ci-cd-integration">
    Set up CI/CD pipelines with PPM
  </Card>

  <Card title="More Examples" icon="code" href="/examples/react-flask">
    Explore more complex project examples
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Frontend shows 'Network Error'">
    Make sure the Python backend is running on port 5000. Check the terminal for any Flask errors.
  </Accordion>

  <Accordion title="Python packages not found">
    PPM creates a virtual environment automatically. If you see import errors, try:

    ```bash theme={null}
    ppm venv activate
    pip list  # Verify packages are installed
    ```
  </Accordion>

  <Accordion title="Port already in use">
    If ports 3000 or 5000 are busy, you can change them in the configuration files or kill the processes using those ports.
  </Accordion>
</AccordionGroup>

***

🎉 **Congratulations!** You've built your first polyglot application with PPM. You've experienced firsthand how PPM eliminates the complexity of managing multiple package ecosystems while maintaining the power and flexibility of each language.