Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js: v18.0.0 or higher (Download)
npm: v9.0.0 or higher (comes with Node.js)
Git: Latest version (Download)
Code Editor: VSCode recommended (Download)

Recommended VSCode Extensions

ESLint
Prettier
Tailwind CSS IntelliSense
EditorConfig
GitLens

Installation

Clone the Repository

git clone https://github.com/your-org/lowcode-visual-builder.git
cd lowcode-visual-builder

Install Dependencies

npm install

This will install:

Electron and Electron Forge
React and React DOM
Development tools (ESLint, Prettier, etc.)
UI libraries (React Flow, Monaco Editor, etc.)

Development

Start the App

npm start

This will:

Start the Electron app in development mode
Enable hot reload for renderer process
Open DevTools automatically

Expected Output:

✓ Electron app started
✓ React dev server running
→ Opening window...

Development Scripts

# Start development mode
npm start

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Format code
npm run format

# Type check (if using TypeScript)
npm run type-check

Project Structure

lowcode-visual-builder/
├── src/
│   ├── main/              # Electron main process
│   │   ├── index.js       # Main entry point
│   │   ├── ipc.js         # IPC handlers
│   │   └── fileSystem.js  # File operations
│   │
│   ├── renderer/          # Electron renderer process (React)
│   │   ├── App.jsx        # Root component
│   │   ├── components/    # UI components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── store/         # State management (Zustand)
│   │   └── utils/         # Helper functions
│   │
│   ├── engine/            # Core logic
│   │   ├── manifest/      # Manifest management
│   │   ├── generator/     # Code generation
│   │   ├── parser/        # Code parsing
│   │   └── plugins/       # Framework plugins
│   │
│   └── shared/            # Shared types and constants
│
├── docs/                  # Documentation
├── tests/                 # Test files
├── templates/             # Project templates
└── public/                # Static assets

Creating Your First Project

1. Launch the App

npm start

2. Create New Project

Click "New Project" button
Fill in project details:
- Name: my-first-app
- Framework: React (only option in MVP)
- Location: Choose directory
Click "Create"

3. Add Components

Right-click in Component Tree panel
Select "Add Component"
Choose component type (e.g., Button)
Configure properties in Properties Panel

4. Preview

Click "Preview" tab in center panel
See your component rendered
Changes update automatically

5. View Generated Code

Click "Code" tab
See generated React code
Code is also saved in my-first-app/src/components/

Using AI to Generate Components

Basic AI Usage

Click "AI Assistant" button (or press Ctrl+K)

Describe component:

Create a UserCard component that displays 
a user's name, email, and avatar image

Review generated component in tree
Adjust properties as needed

AI Best Practices

✅ DO:

Be specific about what you want
Mention props and state explicitly
Describe layout (e.g., "in a card layout")
Request styling (e.g., "using Tailwind classes")

❌ DON'T:

Ask for entire applications at once
Use vague descriptions
Expect AI to understand complex business logic
Assume AI knows your design system

Example Prompts

Good:

Create a SearchBar component with:
- An input field for search query
- A search button
- OnSearch event that passes the query
- Use Tailwind for styling

Better:

Create a SearchBar component:

Props:
- placeholder (string)
- onSearch (function)

State:
- query (string)

UI:
- Input field (Tailwind rounded, border-gray-300)
- Search button (blue background, white text)
- Button triggers onSearch with current query

Configuration

Project Settings

Located in .lowcode/config.json (in generated projects):

{
  "framework": "react",
  "typescript": false,
  "formatting": {
    "style": "prettier",
    "config": {
      "semi": true,
      "singleQuote": true,
      "tabWidth": 2
    }
  }
}

App Settings

In the visual builder app, go to Settings (gear icon):

Theme: Light/Dark mode
AI Provider: Claude (default), OpenAI (future)
Auto-save: Enable/disable
Preview Mode: Isolation/Full app

Keyboard Shortcuts

Global

Shortcut	Action
`Ctrl+N`	New project
`Ctrl+O`	Open project
`Ctrl+S`	Save
`Ctrl+Z`	Undo
`Ctrl+Shift+Z`	Redo
`Ctrl+K`	AI Assistant
`Ctrl+P`	Preview toggle
`F5`	Refresh preview

Component Tree

Shortcut	Action
`Ctrl+A`	Add component
`Delete`	Delete selected
`Ctrl+D`	Duplicate
`Ctrl+Up`	Move up
`Ctrl+Down`	Move down

Editor

Shortcut	Action
`Ctrl+F`	Find
`Ctrl+H`	Replace
`Ctrl+/`	Toggle comment
`Alt+Up/Down`	Move line

Troubleshooting

App Won't Start

Error: Cannot find module 'electron'

Solution:

rm -rf node_modules package-lock.json
npm install

Error: Port 3000 already in use

Solution:

# Kill process using port 3000
npx kill-port 3000
# Or change port in vite.config.js

Preview Not Loading

Issue: Preview shows blank screen

Solutions:

Check console for errors (right-click preview → Inspect)
Verify generated code compiles:
```
cd my-first-app
npm run build
```
Restart dev server

Generated Code Has Errors

Issue: ESLint errors in generated code

Solutions:

Check manifest for invalid values
Regenerate code: Right-click component → "Regenerate"
Report bug if consistent

AI Not Responding

Issue: AI request times out

Solutions:

Check internet connection
Verify API key in settings
Try simpler prompt
Check API status: https://status.anthropic.com/

Working with Generated Projects

Opening Generated Project

Generated projects are standard Vite + React apps:

cd my-first-app
npm install  # First time only
npm run dev  # Start dev server

Open in browser: http://localhost:3000

Editing Generated Code

You can edit generated code directly:

Open project in VSCode
Edit files in src/components/
Changes appear in browser (HMR)

Note: Manual edits will be preserved, but visual editor sync is a post-MVP feature.

Adding Dependencies

cd my-first-app
npm install axios  # Or any package

Then import in script nodes or protected regions.

Deploying Generated Projects

Deploy like any Vite app:

Vercel

npm install -g vercel
cd my-first-app
vercel

Netlify

npm install -g netlify-cli
cd my-first-app
npm run build
netlify deploy --prod

Static Hosting

cd my-first-app
npm run build
# Upload dist/ folder to any host

Contributing

Setting Up Development Environment

Fork the repository
Create a branch:
```
git checkout -b feature/my-feature
```
Make changes
Run tests:
```
npm test
```
Commit:
```
git commit -m "Add my feature"
```
Push and create PR

Code Style

We use:

ESLint for linting
Prettier for formatting
Conventional Commits for commit messages

Run before committing:

npm run lint
npm run format

Testing

Add tests for new features:

// tests/component.test.js
import { describe, it, expect } from 'vitest';

describe('ComponentManager', () => {
  it('adds component to manifest', () => {
    // Test code
  });
});

Run tests:

npm test

Getting Help

Documentation

Architecture: ARCHITECTURE.md
Component Schema: COMPONENT_SCHEMA.md
Data Flow: DATA_FLOW.md
Expression System: EXPRESSION_SYSTEM.md

Community

GitHub Issues: Bug reports and feature requests
Discussions: Questions and ideas
Discord: Real-time chat (coming soon)

FAQ

Q: Can I use this with TypeScript? A: Not in MVP, but planned for future release.

Q: Can I use Vue/Svelte instead of React? A: Not in MVP. Plugin system for other frameworks is post-MVP.

Q: Can I import existing React components? A: Partially. You can reference external components in script nodes, but visual editing of imported components is post-MVP.

Q: Is this production-ready? A: MVP is for prototyping. Generated code is production-quality React, but the tool itself is early stage.

Q: Do I need to know React? A: Basic understanding helps, but tool is designed for low-code developers with minimal React knowledge.

Sample Projects

Example 1: Todo App

npm run example:todo

Features:

Add/remove todos
Mark complete
Filter (all/active/completed)
Uses global state

Example 2: User Dashboard

npm run example:dashboard

Features:

User list and detail views
Search and filter
Component connections
Script nodes for data transformation

Example 3: Form Builder

npm run example:forms

Features:

Dynamic form fields
Validation
Conditional logic
Submit handling

Next Steps

✅ Complete Tutorial: Follow in-app tutorial
✅ Explore Examples: Open and study sample projects
✅ Build Something: Start with simple project
✅ Read Docs: Deep dive into specific topics
✅ Join Community: Share your creations

Useful Resources

Learning React

Low-Code Concepts

Our Inspiration

License

TBD

Acknowledgments

Built with:

⚛️ React
⚡ Vite
🔌 Electron
🤖 Claude AI
💙 Open Source

Questions? Open an issue on GitHub or check the docs!

Ready to build? npm start and let's go! 🚀

FilesExpand file tree

GETTING_STARTED.md

Latest commit

History

GETTING_STARTED.md

File metadata and controls

Getting Started

Prerequisites

Recommended VSCode Extensions

Installation

Clone the Repository

Install Dependencies

Development

Start the App

Development Scripts

Project Structure

Creating Your First Project

1. Launch the App

2. Create New Project

3. Add Components

4. Preview

5. View Generated Code

Using AI to Generate Components

Basic AI Usage

AI Best Practices

Example Prompts

Configuration

Project Settings

App Settings

Keyboard Shortcuts

Global

Component Tree

Editor

Troubleshooting

App Won't Start

Preview Not Loading

Generated Code Has Errors

AI Not Responding

Working with Generated Projects

Opening Generated Project

Editing Generated Code

Adding Dependencies

Deploying Generated Projects

Vercel

Netlify

Static Hosting

Contributing

Setting Up Development Environment

Code Style

Testing

Getting Help

Documentation

Community

FAQ

Sample Projects

Example 1: Todo App

Example 2: User Dashboard

Example 3: Form Builder

Next Steps

Useful Resources

Learning React

Low-Code Concepts

Our Inspiration

License

Acknowledgments