Getting Started

Get up and running with Positron in 5 minutes!

Prerequisites

Python 3.8 or higher
Node.js 16 or higher
npm or yarn

Quick Start

The fastest way to get started is using the CLI:

# Initialize a new app
npm create positron-app@latest
# or
npx create-positron-app@latest

Follow the prompts to select a template (React, Vue, Svelte, Next.js, or Vanilla), then:

cd my-app
npm install
npm run dev

You should see a window open with your chosen template!

Manual Installation

If you prefer to install manually or from source:

1. Clone Positron

git clone https://github.com/tomlin7/positron.git
cd positron

2. Install Python Dependencies

pip install -r requirements.txt

3. Run an Example

cd examples/react-app
npm install
python main.py

Next Steps

Add IPC Communication

In main.py:

from positron.ipc import ipc_main

@ipc_main.handle('my-channel')
def handler(event, data):
    # Process data in Python
    return f"Processed: {data}"

In React (src/App.jsx):

const result = await window.ipcRenderer.invoke('my-channel', 'hello')
console.log(result)  // "Processed: hello"

Customize Window

win = BrowserWindow({
    'width': 1200,
    'height': 800,
    'title': 'My Custom App',
    'resizable': True,
    'center': True,
    'backgroundColor': '#282c34',
    'min_width': 800,
    'min_height': 600,
})

Access Python Libraries

Use any Python library in your IPC handlers:

import requests
import pandas as pd
from PIL import Image

@ipc_main.handle('fetch-data')
def fetch_data(event, url):
    response = requests.get(url)
    return response.json()

@ipc_main.handle('process-csv')
def process_csv(event, filepath):
    df = pd.read_csv(filepath)
    return df.to_dict('records')

Common Issues

Dev Server Not Starting

Problem: Error starting dev server

Solution:

Make sure Node.js is installed: node --version
Install dependencies: npm install
Check if port 5173 is available

Pywebview Not Found

Problem: ImportError: webview

Solution:

pip install pywebview

Window Not Showing

Problem: Window opens but is blank

Solution:

Check console for errors
Make sure dev server started successfully
Try loading a simple HTML: win.load_html('<h1>Test</h1>')

Development Tips

Hot Reload

React changes auto-reload thanks to Vite. Python changes require app restart.

Debugging

Python side:

import pdb; pdb.set_trace()  # Breakpoint
print("Debug:", data)  # Print to console

JavaScript side:

console.log("Debug:", data)  // Shows in Python console

Production Build

Build React for production:

npm run build

Then load built files instead of dev server:

# In main.py
win.load_file('dist/index.html')

Learn More

Happy coding with Positron! 🚀

Getting Started

On this page