lattefx-cli

A command-line interface (CLI) tool for LatteFX, a Python-based desktop application framework. This CLI helps you initialize, develop, and build LatteFX applications with ease.

NOTA IMPORTANTE: El comando ejecutable de esta CLI es lattefx, no lattefx-cli.

✨ Features

• lattefx init: Initialize a new LatteFX project in an existing frontend application, setting up configuration files and a Python backend structure.
• lattefx dev: Start your frontend development server and the LatteFX Python backend simultaneously for a seamless development experience.
• lattefx build: Build your frontend application and package it with the LatteFX Python backend into a distributable executable using PyInstaller.
• lattefx --help: Display comprehensive help information for all available commands.

📋 Requirements

• Node.js 16+ - For running the CLI
• Python 3.12+ - For the backend
• npm or yarn - For package management

📥 Installation

Option 1: Local Project Installation (Recommended)

Install lattefx-cli as a development dependency in your project:

npm install --save-dev lattefx-cli

Then use it with npx:

npx lattefx --help
npx lattefx init
npx lattefx dev
npx lattefx build

Option 2: Global Installation

npm install -g lattefx-cli

Then use it directly:

lattefx --help
lattefx init
lattefx dev
lattefx build

🚀 Quick Start

1. Initialize a New LatteFX Project

npx lattefx init

This command will interactively prompt you for:

• Frontend development command (e.g., npm run dev)
• Frontend build command (e.g., npm run build)
• Frontend dev server URL (e.g., http://localhost:5173)
• Build output path (e.g., dist)

Example interaction:

? What is your frontend dev command? npm run dev
? What is your frontend build command? npm run build
? What is your frontend dev server URL? http://localhost:5173
? Where is your build output? dist
✅ Project initialized successfully!

Created files:
  - lattefx.config.json
  - src-lattefx/main.py
  - src-lattefx/requirements.txt

2. Set Up Python Environment

After initialization, set up your Python virtual environment:

cd src-lattefx

# Windows
python -m venv .venv
.venv\Scripts\activate

# macOS/Linux
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Start Development

npx lattefx dev

This will:

• Start your frontend development server
• Start the LatteFX Python backend
• Open the desktop application window
• Enable hot-reloading for both frontend and backend

4. Build for Production

npx lattefx build

This will:

• Build your frontend (production optimized)
• Package everything into a standalone executable
• Output to the dist/ directory

📖 Command Reference

lattefx init

Initialize a new LatteFX project structure in your current directory.

npx lattefx init

What it creates:

• lattefx.config.json - Configuration file for your LatteFX project
• src-lattefx/main.py - Main Python entry point
• src-lattefx/requirements.txt - Python dependencies

Configuration example (lattefx.config.json):

{
  "frontend": {
    "devCommand": "npm run dev",
    "buildCommand": "npm run build",
    "devUrl": "http://localhost:5173",
    "buildOutput": "dist"
  },
  "python": {
    "mainFile": "main.py",
    "venvPath": ".venv"
  },
  "app": {
    "name": "My LatteFX App",
    "width": 1024,
    "height": 768
  }
}

lattefx dev

Start the development environment with both frontend and backend running.

npx lattefx dev

What it does:

1. Checks if the Python virtual environment exists
2. Activates the virtual environment
3. Installs any missing Python dependencies
4. Starts the frontend development server
5. Starts the Python backend server
6. Opens the desktop window pointing to your frontend

Requirements:

• You must have run lattefx init first
• Your Python virtual environment should be set up
• Dependencies must be installed: pip install -r src-lattefx/requirements.txt

Troubleshooting:

If the venv is not detected, create it manually:

cd src-lattefx
python -m venv .venv
pip install -r requirements.txt
cd ..
npx lattefx dev

lattefx build

Build your application for production and create a standalone executable.

npx lattefx build

What it does:

1. Builds your frontend application
2. Compiles your Python backend using PyInstaller
3. Packages everything into a single executable
4. Outputs to the dist/ directory

Requirements:

• PyInstaller must be installed: pip install pyinstaller
• Your application must be tested and working in development mode

Output:

• Standalone executable in dist/ directory
• Can be distributed to end users without Python installed

Installation of PyInstaller:

cd src-lattefx
# With venv activated:
pip install pyinstaller

lattefx --help

Display help information for the CLI.

npx lattefx --help

For help on a specific command:

npx lattefx <command> --help
npx lattefx init --help
npx lattefx dev --help
npx lattefx build --help

📚 Complete Example Workflow

Step 1: Create a React/Vue/Svelte App

# Create a Vite React app
npm create vite@latest my-lattefx-app -- --template react
cd my-lattefx-app
npm install

Step 2: Initialize LatteFX

npx lattefx-cli init

When prompted:

? What is your frontend dev command? npm run dev
? What is your frontend build command? npm run build
? What is your frontend dev server URL? http://localhost:5173
? Where is your build output? dist

Step 3: Set Up Python Environment

cd src-lattefx
python -m venv .venv
.venv\Scripts\activate  # Windows or source .venv/bin/activate
pip install -r requirements.txt
cd ..

Step 4: Start Development

npx lattefx dev

Your application window will open automatically!

Step 5: Build for Distribution

npx lattefx build

Your executable will be in dist/ directory.

🔧 Configuration

lattefx.config.json

The configuration file controls how your project builds and runs:

{
  "frontend": {
    "devCommand": "npm run dev",
    "buildCommand": "npm run build",
    "devUrl": "http://localhost:5173",
    "buildOutput": "dist"
  },
  "python": {
    "mainFile": "main.py",
    "venvPath": ".venv"
  },
  "app": {
    "name": "My App",
    "version": "1.0.0",
    "width": 1024,
    "height": 768,
    "resizable": true
  }
}

📁 Project Structure

After running lattefx init, your project will look like:

my-project/
├── src-lattefx/                    # Python backend
│   ├── .venv/                      # Virtual environment
│   ├── main.py                     # Backend entry point
│   ├── requirements.txt            # Python dependencies
│   └── __pycache__/
├── src/                            # Frontend source (React/Vue/etc)
│   ├── App.jsx
│   └── main.jsx
├── public/                         # Static assets
├── dist/                           # Build output
├── lattefx.config.json             # LatteFX configuration
├── package.json
├── vite.config.js                  # or your build tool config
└── README.md

🔌 Frontend-Backend Communication

Your frontend can communicate with the Python backend using the Fetch API:

// In your React/Vue/Svelte component
async function fetchData() {
  const response = await fetch('/api/data');
  const data = await response.json();
  return data;
}

// Or POST request
async function sendData(payload) {
  const response = await fetch('/api/process', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });
  return response.json();
}

In your Python backend:

from fastapi import FastAPI
import lattefx

app = FastAPI()

@app.get("/api/data")
def get_data():
    return {"message": "Hello from Python!"}

@app.post("/api/process")
def process_data(payload: dict):
    return {"processed": payload}

if __name__ == "__main__":
    lattefx.run(api=app, static_path="./dist")

🐛 Troubleshooting

"Command not found: lattefx"

Solution: Make sure you installed the CLI:

npm install --save-dev lattefx-cli

Or use npx to run it:

npx lattefx --help

Python venv not detected during lattefx dev

Solution: Create it manually:

cd src-lattefx
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
cd ..
npx lattefx dev

"Module not found" error during build

Solution: Ensure all Python dependencies are in requirements.txt:

cd src-lattefx
pip install pyinstaller

Frontend dev server not starting

Solution: Check your lattefx.config.json and verify:

• devCommand is correct for your framework
• Frontend dependencies are installed: npm install
• The port in devUrl matches your dev server configuration

PyInstaller build fails

Solution:

1. Ensure PyInstaller is installed:

   pip install pyinstaller

2. Test your app works in development first:

   npx lattefx dev

3. If still failing, try building manually:

   cd src-lattefx
   pyinstaller --onefile --windowed main.py

🎯 Best Practices

1. Version Control

# .gitignore
node_modules/
dist/
src-lattefx/.venv/
src-lattefx/__pycache__/
*.egg-info/
.DS_Store

2. Environment Variables

Create .env file for sensitive data:

# .env
PYTHON_ENV=development
API_KEY=your_key_here

Access in Python:

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv("API_KEY")

3. Keep Dependencies Updated

# Check outdated packages
npm outdated

# Update npm packages
npm update

# Update Python packages
pip install --upgrade -r requirements.txt

4. Test Before Building

Always test your application in development mode before building:

npx lattefx dev
# Test all features, then CTRL+C
npx lattefx build

📦 Publishing Your App

After building with npx lattefx build:

1. The executable is in dist/ directory
2. You can distribute it directly to users
3. Or use an installer tool like NSIS or InnoSetup (Windows)
4. Or create DMG for macOS
5. Or .deb/.rpm for Linux

🔒 Security Considerations

1. Never hardcode secrets - Use environment variables
2. Validate all inputs - In both frontend and backend
3. Use HTTPS - If communicating with external services
4. Keep dependencies updated - Regularly run npm audit and pip audit
5. Code signing - For production releases

📞 Support & Contributing

• 📖 Read the full documentation: See docs/ in the backend package
• 🐛 Report issues on GitHub
• 💡 Suggest improvements
• 🤝 Contribute code via pull requests

📝 Development

If you're contributing to lattefx-cli itself:

1. Clone the repository
2. Install dependencies: npm install
3. Link the CLI for local testing: npm link
4. Make your changes in the bin/ directory
5. Test with: npx lattefx <command>
6. Update the version before publishing: npm version patch
7. Publish to npm: npm publish

📄 License

ISC

🚀 Next Steps

1. ✅ Install: npm install --save-dev lattefx-cli
2. ✅ Initialize: npx lattefx init
3. ✅ Develop: npx lattefx dev
4. ✅ Build: npx lattefx build
5. ✅ Distribute your app!

Happy building with LatteFX! 🎉