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:

1. Install PPM

   If you haven’t already, install PPM using our one-liner:

   Windows:

   Invoke-WebRequest https://raw.githubusercontent.com/VesperAkshay/polypm/main/install.ps1 -UseBasicParsing | Invoke-Expression
   

   macOS/Linux:

   curl -fsSL https://raw.githubusercontent.com/VesperAkshay/polypm/main/install.sh | bash
   
2. Verify Installation

   ppm --version
   

   You should see the PPM version number.

3. Check Dependencies

   Make sure you have Node.js and Python installed:

   node --version  # Should be 14 or later
   python --version  # Should be 3.8 or later
   

Step 1: Create a New Project

Initialize a new PPM project:

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:

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:

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

ppm install

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

Step 5: Create the Frontend

Frontend Package Configuration

Create frontend/package.json:

{
  "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:

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:

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:

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:

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

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:

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:

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
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?

Unified Dependencies

PPM installed both npm and pip packages from a single configuration file

Environment Management

Python virtual environment was created automatically, Node.js dependencies managed separately

Cross-Language Scripts

One command started both frontend and backend with proper environment activation

Seamless Integration

React frontend communicates with Python backend through well-configured CORS

Compare with Traditional Approach

Without PPM (Traditional)

# 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

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

Add More Dependencies

Learn how to add new JavaScript or Python packages

Advanced Configuration

Explore advanced project.toml configurations

Production Deployment

Set up CI/CD pipelines with PPM

More Examples

Explore more complex project examples

Troubleshooting

Frontend shows 'Network Error'

Make sure the Python backend is running on port 5000. Check the terminal for any Flask errors.

Python packages not found

PPM creates a virtual environment automatically. If you see import errors, try:

ppm venv activate
pip list  # Verify packages are installed

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.

---

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