Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
168 lines (108 loc) · 4.17 KB

DEVELOPMENT.md

File metadata and controls

168 lines (108 loc) · 4.17 KB

5ire Development Setup Guide

This guide will help you set up the development environment for the 5ire project and run it locally.

Prerequisites

  • Node.js (v20.10.0 recommended)
  • Git
  • Supabase account (for authentication and database)
  • Python & UV

Environment Setup

1. Clone the Repository

git clone https://github.com/nanbingxyz/5ire.git
cd 5ire

2. Node.js Setup

We recommend using asdf for managing Node.js versions. If you have asdf installed:

# Install the required Node.js version
asdf install nodejs 20.10.0

# Set it as the local version for this project
asdf local nodejs 20.10.0

Alternatively, you can install Node.js v20.10.0 directly from the official website.

3. Install Dependencies

ensure python venv

depend on you shell

source venv/bin/activate.fish

node.js

npm install

4. Environment Configuration

Create a .env file in the root directory with the following variables:

SUPA_PROJECT_ID=your_supabase_project_id
SUPA_KEY=your_supabase_anon_key
AXIOM_TOKEN=your_axiom_token
AXIOM_ORG_ID=your_axiom_org_id
NODE_ENV=development

We utilize Axiom to collect anonymized minimal operational metrics and Supabase for authorization and backing up settings. If these features aren't involved during development, you can just ignore them and use a dummy.env config.

To get your Axiom credentials:

  1. Create an Organization on Axiom
  2. Get Organization ID from Org Settings.
  3. Create a new API Token in the organization settings.

To get your Supabase credentials:

  1. Create a project on Supabase
  2. Go to Project Settings > API
  3. Copy the Project URL - the project ID is the subdomain (e.g., for https://xvmubowipwszxgjskdme.supabase.co, the ID is xvmubowipwszxgjskdme)
  4. Copy the anon public API key for the SUPA_KEY variable

5. Prepare Husky (Git Hooks)

npm run prepare

Running the Development Environment

Start the Development Server

npm start -- --no-sandbox --disable-gpu

This command will:

  1. Start the Electron application in development mode
  2. Enable hot reloading for changes to the codebase
  3. Open the application window

MCP Tool Servers (Optional)

The application uses Model Context Protocol (MCP) tool servers for various functionalities. These are optional for basic development but required for full functionality.

If you see errors like:

Error: MCP error -1: Connection closed

You may need to set up the relevant MCP tool servers. Check the project documentation for specific MCP tools used.

Troubleshooting

Supabase Connection Issues

If you see errors related to Supabase authentication:

  1. Verify your SUPA_PROJECT_ID and SUPA_KEY in the .env file
  2. Ensure your Supabase project is running and accessible
  3. Check that you're using the correct API key (the anon public key for development)

Node.js Version Issues

If you encounter compatibility issues:

# Check your current Node.js version
node -v

# If using asdf, ensure the correct version is active
asdf current nodejs

Electron Startup Issues

If the application fails to start:

  1. Try running without sandbox and GPU acceleration:

    npm start -- --no-sandbox --disable-gpu

  2. Check the console output for specific errors

Development Workflow

  1. Make your code changes
  2. The application will automatically reload with your changes
  3. For changes to the main process, you may need to restart the application

Building for Production

npm run package

This will create a distributable package in the release/build directory.

Additional Resources

Acknowledgements

A big thanks to @cs3b for helping with this document.