mirror of
https://github.com/wailsapp/wails.git
synced 2026-03-14 22:55:48 +01:00
feat(setup): add documentation, bug reporting, and improve dependency detection
- Add user-facing documentation at docs/getting-started/setup.mdx - Remove internal design storyboard (docs/setup-wizard-storyboard.md) - Wire up main `wails3 setup` command in CLI - Add experimental warning with link to feedback issue #4904 - Add "Report Bug" button in wizard sidebar with clipboard template - Fix npm detection on Linux to check PATH, not just package manager - Use term.Warning and term.Hyperlink for styled terminal output Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lea Anthony
parent
30a830136f
commit
d4d2dd0aa3
13 changed files with 266 additions and 837 deletions
|
|
@ -1,765 +0,0 @@
|
|||
# Wails Setup - OOBE Storyboard
|
||||
|
||||
> An Apple/Microsoft-style Out-of-Box Experience for `wails3 setup`
|
||||
|
||||
---
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
Transform the wizard into an OOBE (Out-of-Box Experience):
|
||||
|
||||
- **No footer navigation** - Buttons appear contextually within content
|
||||
- **Full-screen immersive pages** - Each step is its own moment
|
||||
- **Progressive disclosure** - Show only what's needed
|
||||
- **Branching paths** - Adapt flow based on system state
|
||||
- **Conversational tone** - Guide users naturally through decisions
|
||||
|
||||
---
|
||||
|
||||
## Page Layout Template
|
||||
|
||||
All screens (except Splash) use this consistent layout:
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Icon] |
|
||||
| |
|
||||
| Large Title Here |
|
||||
| |
|
||||
| Supporting text in a friendly tone |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | Content Area | |
|
||||
| | (varies per screen) | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Primary Action ] |
|
||||
| secondary link |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
Key principles:
|
||||
- Theme toggle always visible (top-left)
|
||||
- Centered content with generous whitespace
|
||||
- Buttons appear only when relevant
|
||||
- No persistent footer or step indicators
|
||||
|
||||
---
|
||||
|
||||
## Flow Diagram
|
||||
|
||||
```
|
||||
+----------------+
|
||||
| Splash |
|
||||
| "Let's Start" |
|
||||
+-------+--------+
|
||||
|
|
||||
v
|
||||
+------------------------+
|
||||
| Checking System... |
|
||||
| (auto-transition) |
|
||||
+------------+-----------+
|
||||
|
|
||||
+------------------+------------------+
|
||||
| |
|
||||
v v
|
||||
+-----------------------+ +-----------------------+
|
||||
| All deps OK | | Missing deps |
|
||||
| "You're all set!" | | "Almost there" |
|
||||
+-----------+-----------+ +-----------+-----------+
|
||||
| |
|
||||
| v
|
||||
| +-----------------------+
|
||||
| | Install Instructions |
|
||||
| | [Copy] [Re-check] |
|
||||
| +-----------+-----------+
|
||||
| |
|
||||
+<----------------------------------+
|
||||
|
|
||||
v
|
||||
+-----------------------+
|
||||
| Cross-Platform? |
|
||||
| (always shown) |
|
||||
+-----------+-----------+
|
||||
|
|
||||
+-----------+-----------+
|
||||
| |
|
||||
v v
|
||||
+------------+ +------------------------+
|
||||
| Not now | | Yes, set this up |
|
||||
+-----+------+ +------------+-----------+
|
||||
| |
|
||||
| +-----------+-----------+
|
||||
| | |
|
||||
| v v
|
||||
| +------------------+ +------------------+
|
||||
| | Docker missing? | | Docker ready? |
|
||||
| | -> Install link | | -> Build image |
|
||||
| +--------+---------+ +--------+---------+
|
||||
| | |
|
||||
| v v
|
||||
| +------------------+ +------------------+
|
||||
| | [Check Again] | | Building... |
|
||||
| | Skip -> | | (can continue) |
|
||||
| +--------+---------+ +--------+---------+
|
||||
| | |
|
||||
+<------------+-----------------------+
|
||||
|
|
||||
v
|
||||
+-----------------------+
|
||||
| Tell us about you |
|
||||
| (Author details) |
|
||||
+-----------+-----------+
|
||||
|
|
||||
v
|
||||
+-----------------------+
|
||||
| Project Defaults |
|
||||
| (Bundle ID, etc) |
|
||||
+-----------+-----------+
|
||||
|
|
||||
v
|
||||
+-----------------------+
|
||||
| Code Signing? |
|
||||
| [Skip] or [Setup] |
|
||||
+-----------+-----------+
|
||||
|
|
||||
+-----------+-----------+
|
||||
| |
|
||||
v v
|
||||
+-------------+ +-------------+
|
||||
| macOS | | Windows |
|
||||
| Signing | | Signing |
|
||||
+------+------+ +------+------+
|
||||
| |
|
||||
+--------+--------+
|
||||
|
|
||||
v
|
||||
+-----------------------+
|
||||
| All Done! |
|
||||
| "Start Building" |
|
||||
+-----------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Screen-by-Screen Storyboard
|
||||
|
||||
### 1. Splash Screen
|
||||
|
||||
**Purpose:** Welcome, set tone, minimal interaction
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| |
|
||||
| |
|
||||
| [Wails Logo] |
|
||||
| with subtle glow |
|
||||
| |
|
||||
| |
|
||||
| Welcome to Wails |
|
||||
| |
|
||||
| Build beautiful cross-platform apps |
|
||||
| using Go and web tech |
|
||||
| |
|
||||
| |
|
||||
| [ Let's Start ] |
|
||||
| |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Elements:**
|
||||
- Theme toggle (top-left) - only UI control
|
||||
- Logo with glow animation
|
||||
- Minimal copy
|
||||
- Single "Let's Start" button
|
||||
|
||||
**On click:** Triggers dependency check, transitions to Checking screen
|
||||
|
||||
---
|
||||
|
||||
### 2. Checking System (Transitional)
|
||||
|
||||
**Purpose:** Brief loading while checking dependencies (2-3 seconds)
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| |
|
||||
| |
|
||||
| [Spinner] |
|
||||
| |
|
||||
| Checking your system... |
|
||||
| |
|
||||
| This will only take a moment |
|
||||
| |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- No user interaction needed
|
||||
- Auto-advances when check completes
|
||||
- Minimum 1.5s display (perceived thoroughness)
|
||||
|
||||
---
|
||||
|
||||
### 3a. System Ready (Happy Path)
|
||||
|
||||
**When:** All required dependencies installed
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Checkmark] |
|
||||
| (animated) |
|
||||
| |
|
||||
| You're all set! |
|
||||
| |
|
||||
| Your system has everything needed |
|
||||
| to build Wails apps |
|
||||
| |
|
||||
| |
|
||||
| [ Continue ] |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Elements:**
|
||||
- Green animated checkmark
|
||||
- Simple confirmation message (no list of deps)
|
||||
- Single "Continue" button
|
||||
|
||||
**Next:** Goes to Cross-Platform question
|
||||
|
||||
---
|
||||
|
||||
### 3b. Missing Dependencies
|
||||
|
||||
**When:** Required dependencies not found
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Warning] |
|
||||
| (amber icon) |
|
||||
| |
|
||||
| Almost there! |
|
||||
| |
|
||||
| A few things need to be installed |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | [X] npm | |
|
||||
| | Required for frontend tooling | |
|
||||
| | | |
|
||||
| | [X] GTK Development Libraries | |
|
||||
| | Required for Linux builds | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| Run this command to install everything: |
|
||||
| +---------------------------------------------------+ |
|
||||
| | sudo pacman -S npm gtk3 webkit2gtk [Copy] | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Check Again ] |
|
||||
| |
|
||||
| Continue anyway -> |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Dynamic content:**
|
||||
- Platform-specific package manager (apt/dnf/pacman/brew)
|
||||
- Combined command when possible
|
||||
- Individual items if package managers differ
|
||||
|
||||
**Actions:**
|
||||
- Copy button for install command
|
||||
- "Check Again" - re-runs dependency check
|
||||
- "Continue anyway" - for advanced users (subtle link)
|
||||
|
||||
---
|
||||
|
||||
### 4. Cross-Platform Question
|
||||
|
||||
**When:** Always shown (Docker status doesn't matter)
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Platform Icons] |
|
||||
| Win / Mac / Linux |
|
||||
| |
|
||||
| Build for multiple platforms? |
|
||||
| |
|
||||
| Wails can compile your app for Windows, |
|
||||
| macOS, and Linux from a single machine |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | From your {platform} machine, build for: | |
|
||||
| | | |
|
||||
| | - Windows (.exe) | |
|
||||
| | - macOS (.app) | |
|
||||
| | - Linux (AppImage, .deb, etc) | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Yes, set this up ] |
|
||||
| |
|
||||
| Not right now -> |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Branch logic:**
|
||||
- Always shown to everyone
|
||||
- "Yes" -> Checks Docker status, installs if needed, builds image
|
||||
- "Not right now" -> Author details (faster path)
|
||||
|
||||
---
|
||||
|
||||
### 5. Setting Up Cross-Platform Builds
|
||||
|
||||
**When:** User chose "Yes" to cross-platform builds
|
||||
|
||||
This is a single screen that handles all Docker states automatically:
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Docker] |
|
||||
| |
|
||||
| Setting up cross-platform builds |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | [check] Checking Docker... | |
|
||||
| | [spinner] Installing Docker... | |
|
||||
| | [ ] Building cross-compiler image... | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Continue in background ] |
|
||||
| |
|
||||
| The build will complete while you continue |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**States shown in sequence:**
|
||||
1. Checking Docker... (quick check)
|
||||
2. Installing Docker... (if not installed - opens install instructions)
|
||||
3. Starting Docker... (if not running - prompts user)
|
||||
4. Building image... (progress bar, can continue in background)
|
||||
|
||||
**If Docker needs installing:**
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Docker] |
|
||||
| |
|
||||
| Install Docker |
|
||||
| |
|
||||
| Cross-platform builds require Docker Desktop |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | [Download Docker Desktop] | |
|
||||
| | | |
|
||||
| | After installing, come back and we'll | |
|
||||
| | continue setting up. | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Check Again ] |
|
||||
| |
|
||||
| Skip for now -> |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**If Docker not running:**
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Docker] |
|
||||
| |
|
||||
| Start Docker |
|
||||
| |
|
||||
| Please start Docker Desktop to continue |
|
||||
| |
|
||||
| [ Check Again ] |
|
||||
| |
|
||||
| Skip for now -> |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Building image (can continue in background):**
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Docker] |
|
||||
| |
|
||||
| Building cross-compiler image |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | [===================> ] 65% | |
|
||||
| | | |
|
||||
| | This may take several minutes | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Continue in background ] |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Key UX:**
|
||||
- Single flow handles all Docker states
|
||||
- User can wait OR continue while image builds
|
||||
- Background status indicator on subsequent screens
|
||||
|
||||
---
|
||||
|
||||
### 6. Author Details
|
||||
|
||||
**Purpose:** Personalize the setup
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [User] |
|
||||
| |
|
||||
| Tell us about yourself |
|
||||
| |
|
||||
| This information will be used in your apps |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | Your Name | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | Jane Developer | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| | Company (optional) | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | Acme Corp | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Continue ] |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Pre-population:**
|
||||
- Name from `git config user.name` if available
|
||||
|
||||
---
|
||||
|
||||
### 7. Project Defaults
|
||||
|
||||
**Purpose:** Set app identifier conventions
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] [Docker: 78%] |
|
||||
| |
|
||||
| [Package] |
|
||||
| |
|
||||
| Project defaults |
|
||||
| |
|
||||
| These will be used when creating new apps |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | Bundle ID Prefix | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | com.acme | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | Example: com.acme.myapp | |
|
||||
| | | |
|
||||
| | Default Version | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | 0.1.0 | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| | Preferred Template | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | React + TypeScript [v] | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Continue ] |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Note:** Docker status indicator (top-right) if build in progress
|
||||
|
||||
---
|
||||
|
||||
### 8. Code Signing Question
|
||||
|
||||
**Purpose:** Ask about app signing (platform-specific)
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Lock] |
|
||||
| |
|
||||
| Set up code signing? |
|
||||
| |
|
||||
| Code signing lets you distribute apps through |
|
||||
| stores and avoid security warnings |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | Code signing is optional during development. | |
|
||||
| | You can configure this later in your project. | |
|
||||
| | | |
|
||||
| | Available for your platform: | |
|
||||
| | - macOS Developer ID | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Set up signing ] |
|
||||
| |
|
||||
| Skip -> |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Branch logic:**
|
||||
- macOS: Show Apple signing options next
|
||||
- Windows: Show Windows signing options next
|
||||
- Linux: Skip entirely (no signing needed)
|
||||
|
||||
---
|
||||
|
||||
### 9a. macOS Code Signing (Optional)
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Apple] |
|
||||
| |
|
||||
| macOS Code Signing |
|
||||
| |
|
||||
| Required for distribution outside the App Store |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | Developer ID | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | Developer ID Application: Jane Dev... | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| | Apple ID (for notarization) | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | jane@example.com | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| | Team ID | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | ABCD1234 | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Continue ] |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9b. Windows Code Signing (Optional)
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Windows] |
|
||||
| |
|
||||
| Windows Code Signing |
|
||||
| |
|
||||
| Prevents "Unknown Publisher" warnings |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | Certificate Path | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | C:\certs\codesign.pfx [...] | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| | Timestamp Server | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | http://timestamp.digicert.com | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Continue ] |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10. Complete Screen
|
||||
|
||||
**Purpose:** Celebrate and guide next steps
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------+
|
||||
| [Sun/Moon] |
|
||||
| |
|
||||
| [Party] |
|
||||
| (animated) |
|
||||
| |
|
||||
| You're ready to build! |
|
||||
| |
|
||||
| Your development environment is all set up |
|
||||
| |
|
||||
| +---------------------------------------------------+ |
|
||||
| | | |
|
||||
| | Create your first app: | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | wails3 init -n myapp [Copy] | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| | Start developing: | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | cd myapp && wails3 dev [Copy] | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| | Build for production: | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | wails3 build [Copy] | | |
|
||||
| | +---------------------------------------------+ | |
|
||||
| | | |
|
||||
| +---------------------------------------------------+ |
|
||||
| |
|
||||
| [ Start Building ] |
|
||||
| |
|
||||
| Read the documentation |
|
||||
| |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
**Persistent elements:**
|
||||
- If Docker build still in progress, show status indicator
|
||||
- "Start Building" closes the wizard
|
||||
|
||||
---
|
||||
|
||||
## Branching Scenarios Summary
|
||||
|
||||
| Scenario | Flow |
|
||||
|----------|------|
|
||||
| **Happy path** | Splash -> Check -> Ready -> Cross-Platform? -> Author -> Defaults -> Done |
|
||||
| **Missing deps** | Splash -> Check -> Missing -> (install) -> Check -> Ready -> ... |
|
||||
| **Want cross-platform, Docker ready** | ... -> Cross-Platform? (Yes) -> Building -> Author -> ... |
|
||||
| **Want cross-platform, no Docker** | ... -> Cross-Platform? (Yes) -> Install Docker -> Check -> Building -> ... |
|
||||
| **Skip cross-platform** | ... -> Cross-Platform? (Not now) -> Author -> ... |
|
||||
| **Skip signing** | ... -> Signing? -> Skip -> Done |
|
||||
| **macOS w/ signing** | ... -> Signing? -> macOS Signing -> Done |
|
||||
| **Windows w/ signing** | ... -> Signing? -> Windows Signing -> Done |
|
||||
| **Linux** | ... -> Defaults -> Done (signing skipped) |
|
||||
|
||||
---
|
||||
|
||||
## State Machine
|
||||
|
||||
```typescript
|
||||
type OOBEStep =
|
||||
| 'splash'
|
||||
| 'checking'
|
||||
| 'deps-ready'
|
||||
| 'deps-missing'
|
||||
| 'cross-platform-question'
|
||||
| 'docker-setup' // handles install/start/build states
|
||||
| 'docker-building' // can continue in background
|
||||
| 'author'
|
||||
| 'project-defaults'
|
||||
| 'signing-question'
|
||||
| 'signing-macos'
|
||||
| 'signing-windows'
|
||||
| 'complete'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Background Processes
|
||||
|
||||
### Docker Image Build
|
||||
- Runs in background while user continues
|
||||
- Persistent status indicator on subsequent screens
|
||||
- Blocks wizard close only if still building
|
||||
- User can wait on build screen OR continue setup
|
||||
|
||||
### Dependency Check
|
||||
- Runs immediately after "Let's Start"
|
||||
- Shows transitional loading screen
|
||||
- Auto-advances when complete
|
||||
|
||||
---
|
||||
|
||||
## Animation Guidelines
|
||||
|
||||
- **Page transitions:** Fade + slight slide up (Apple-style)
|
||||
- **Checkmarks:** Draw animation with scale bounce
|
||||
- **Progress bars:** Smooth continuous animation
|
||||
- **Error states:** Gentle shake
|
||||
- **Buttons:** Subtle glow on hover
|
||||
|
||||
---
|
||||
|
||||
## Key Differences from Wizard Style
|
||||
|
||||
| Wizard | OOBE |
|
||||
|--------|------|
|
||||
| Footer with Back/Next | Contextual buttons only |
|
||||
| Step indicator (1 of 5) | No step counter |
|
||||
| Linear progression | Branching based on state |
|
||||
| All screens shown | Skip irrelevant screens |
|
||||
| Form-heavy | Question-driven |
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priorities
|
||||
|
||||
1. Remove footer navigation from all screens
|
||||
2. Update Splash to only show theme toggle + "Let's Start"
|
||||
3. Add "Checking" transitional screen
|
||||
4. Split dependency results into Ready/Missing paths
|
||||
5. Add cross-platform question (conditional on Docker)
|
||||
6. Split Docker into sub-states
|
||||
7. Add code signing question/screens (conditional on platform)
|
||||
8. Update Complete screen with next steps
|
||||
71
docs/src/content/docs/getting-started/setup.mdx
Normal file
71
docs/src/content/docs/getting-started/setup.mdx
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
title: Setup
|
||||
sidebar:
|
||||
order: 15
|
||||
badge:
|
||||
text: Experimental
|
||||
variant: caution
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, Aside, Steps } from "@astrojs/starlight/components";
|
||||
|
||||
The `wails3 setup` command provides an interactive wizard that helps configure your development environment for building Wails applications.
|
||||
|
||||
<Aside type="caution" title="Experimental Feature">
|
||||
The setup wizard is new and primarily tested on Linux. If you encounter issues on macOS or Windows, please [report them](https://github.com/wailsapp/wails/issues/4904) and follow the [manual installation steps](/docs/getting-started/installation#platform-specific-dependencies) instead.
|
||||
</Aside>
|
||||
|
||||
## Quick Start
|
||||
|
||||
After [installing the Wails CLI](/docs/getting-started/installation#installation), run:
|
||||
|
||||
```bash
|
||||
wails3 setup
|
||||
```
|
||||
|
||||
This launches a browser-based wizard that guides you through:
|
||||
|
||||
<Steps>
|
||||
1. **System Check** - Verifies required dependencies (Go, npm, platform tooling)
|
||||
2. **Cross-Platform Builds** - Optional Docker setup for building Windows/macOS/Linux from any host
|
||||
3. **Project Defaults** - Configure author info, bundle ID prefix, preferred templates
|
||||
4. **Code Signing** - Optional setup for macOS, Windows, and Linux signing
|
||||
</Steps>
|
||||
|
||||
## What It Configures
|
||||
|
||||
The setup wizard creates a global configuration file at `~/.config/wails/config.yaml` containing:
|
||||
|
||||
- **Author defaults** - Name and company for new projects
|
||||
- **Project defaults** - Bundle ID prefix, default template, version format
|
||||
- **Signing configuration** - Platform-specific code signing settings
|
||||
|
||||
These defaults are used when running `wails3 init` to create new projects.
|
||||
|
||||
## Sub-Commands
|
||||
|
||||
The setup command also includes focused wizards for specific tasks:
|
||||
|
||||
### Code Signing Setup
|
||||
|
||||
```bash
|
||||
wails3 setup signing
|
||||
```
|
||||
|
||||
Interactive wizard for configuring code signing on your current platform.
|
||||
|
||||
### macOS Entitlements
|
||||
|
||||
```bash
|
||||
wails3 setup entitlements
|
||||
```
|
||||
|
||||
Configure macOS entitlements for your application (sandbox, hardened runtime, etc).
|
||||
|
||||
## Having Issues?
|
||||
|
||||
If the setup wizard doesn't work on your system:
|
||||
|
||||
1. Run `wails3 doctor` to diagnose dependency issues
|
||||
2. Follow the [manual installation steps](/docs/getting-started/installation#platform-specific-dependencies) for your platform
|
||||
3. [Report the issue](https://github.com/wailsapp/wails/issues/4904) with your `wails3 doctor` output so we can improve the wizard
|
||||
|
|
@ -109,7 +109,7 @@ func main() {
|
|||
})
|
||||
|
||||
// Setup commands
|
||||
setup := app.NewSubCommand("setup", "Project setup wizards")
|
||||
setup := app.NewSubCommandFunction("setup", "Project setup wizards", commands.Setup)
|
||||
setupSigning := setup.NewSubCommand("signing", "Configure code signing")
|
||||
var setupSigningFlags flags.SigningSetup
|
||||
setupSigning.AddFlags(&setupSigningFlags)
|
||||
|
|
|
|||
|
|
@ -2,12 +2,20 @@ package commands
|
|||
|
||||
import (
|
||||
"github.com/wailsapp/wails/v3/internal/setupwizard"
|
||||
"github.com/wailsapp/wails/v3/internal/term"
|
||||
)
|
||||
|
||||
type SetupOptions struct{}
|
||||
|
||||
func Setup(_ *SetupOptions) error {
|
||||
DisableFooter = true
|
||||
|
||||
term.Println("")
|
||||
term.Warning("The setup wizard is experimental and not fully tested on all platforms.")
|
||||
term.Println("If you encounter issues, please report them at:")
|
||||
term.Println(" " + term.Hyperlink("https://github.com/wailsapp/wails/issues/4904", "GitHub Issue #4904"))
|
||||
term.Println("")
|
||||
|
||||
wizard := setupwizard.New()
|
||||
return wizard.Run()
|
||||
}
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
1
v3/internal/setupwizard/frontend/dist/assets/index-BwhVCaCt.css
vendored
Normal file
1
v3/internal/setupwizard/frontend/dist/assets/index-BwhVCaCt.css
vendored
Normal file
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
60
v3/internal/setupwizard/frontend/dist/assets/index-eaMhLHYM.js
vendored
Normal file
60
v3/internal/setupwizard/frontend/dist/assets/index-eaMhLHYM.js
vendored
Normal file
File diff suppressed because one or more lines are too long
|
|
@ -7,8 +7,8 @@
|
|||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">
|
||||
<script type="module" crossorigin src="/assets/index-Cxh5b1cS.js"></script>
|
||||
<link rel="stylesheet" crossorigin href="/assets/index-BVQMnJjn.css">
|
||||
<script type="module" crossorigin src="/assets/index-eaMhLHYM.js"></script>
|
||||
<link rel="stylesheet" crossorigin href="/assets/index-BwhVCaCt.css">
|
||||
</head>
|
||||
<body>
|
||||
<div id="root"></div>
|
||||
|
|
|
|||
|
|
@ -91,6 +91,8 @@ function Sidebar({ currentStep, dockerStatus, buildingDocker }: {
|
|||
const { theme, toggleTheme } = useTheme();
|
||||
const currentStage = getWizardStage(currentStep);
|
||||
const currentIndex = getStageIndex(currentStage);
|
||||
const [showBugOverlay, setShowBugOverlay] = useState(false);
|
||||
const [bugReportUrl, setBugReportUrl] = useState('');
|
||||
|
||||
const stages = [
|
||||
{ key: 'welcome' as const, label: 'Welcome' },
|
||||
|
|
@ -105,6 +107,25 @@ function Sidebar({ currentStep, dockerStatus, buildingDocker }: {
|
|||
window.open('https://github.com/sponsors/leaanthony', '_blank', 'noopener,noreferrer');
|
||||
};
|
||||
|
||||
const handleReportBug = async () => {
|
||||
try {
|
||||
const { reportBug } = await import('./api');
|
||||
const result = await reportBug(currentStep);
|
||||
if (result.body && result.url) {
|
||||
await navigator.clipboard.writeText(result.body);
|
||||
setBugReportUrl(result.url);
|
||||
setShowBugOverlay(true);
|
||||
}
|
||||
} catch (e) {
|
||||
console.error('Failed to report bug:', e);
|
||||
}
|
||||
};
|
||||
|
||||
const handleOpenGitHub = () => {
|
||||
window.open(bugReportUrl, '_blank', 'noopener,noreferrer');
|
||||
setShowBugOverlay(false);
|
||||
};
|
||||
|
||||
const isDockerBuilding = buildingDocker;
|
||||
|
||||
return (
|
||||
|
|
@ -195,6 +216,16 @@ function Sidebar({ currentStep, dockerStatus, buildingDocker }: {
|
|||
|
||||
|
||||
<div className="p-4 flex justify-center gap-3">
|
||||
<button
|
||||
onClick={handleReportBug}
|
||||
className="p-1 hover:opacity-70 transition-opacity focus:outline-none focus:ring-2 focus:ring-gray-500 focus:ring-offset-2 dark:focus:ring-offset-gray-900 rounded"
|
||||
aria-label="Report a bug"
|
||||
title="Report a bug"
|
||||
>
|
||||
<svg className="w-4 h-4 text-gray-500 dark:text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
|
||||
</svg>
|
||||
</button>
|
||||
<button
|
||||
onClick={handleSponsorClick}
|
||||
className="p-1 hover:opacity-70 transition-opacity focus:outline-none focus:ring-2 focus:ring-red-500 focus:ring-offset-2 dark:focus:ring-offset-gray-900 rounded"
|
||||
|
|
@ -220,6 +251,39 @@ function Sidebar({ currentStep, dockerStatus, buildingDocker }: {
|
|||
)}
|
||||
</button>
|
||||
</div>
|
||||
|
||||
{/* Bug Report Overlay */}
|
||||
{showBugOverlay && (
|
||||
<div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50">
|
||||
<div className="bg-white dark:bg-gray-800 rounded-lg p-6 max-w-sm mx-4 shadow-xl">
|
||||
<div className="flex items-center gap-3 mb-4">
|
||||
<div className="w-10 h-10 rounded-full bg-green-100 dark:bg-green-900 flex items-center justify-center">
|
||||
<svg className="w-5 h-5 text-green-600 dark:text-green-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
|
||||
</svg>
|
||||
</div>
|
||||
<h3 className="text-lg font-semibold text-gray-900 dark:text-white">Template Copied!</h3>
|
||||
</div>
|
||||
<p className="text-sm text-gray-600 dark:text-gray-300 mb-4">
|
||||
The issue template has been copied to your clipboard. Click below to open the GitHub issue and paste it into a new comment.
|
||||
</p>
|
||||
<div className="flex gap-3">
|
||||
<button
|
||||
onClick={() => setShowBugOverlay(false)}
|
||||
className="flex-1 px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 rounded-lg hover:bg-gray-200 dark:hover:bg-gray-600 transition-colors"
|
||||
>
|
||||
Cancel
|
||||
</button>
|
||||
<button
|
||||
onClick={handleOpenGitHub}
|
||||
className="flex-1 px-4 py-2 text-sm font-medium text-white bg-red-600 rounded-lg hover:bg-red-700 transition-colors"
|
||||
>
|
||||
Open GitHub
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
</aside>
|
||||
);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -158,3 +158,8 @@ export async function saveSigning(signing: SigningDefaults): Promise<{ status: s
|
|||
});
|
||||
return response.json();
|
||||
}
|
||||
|
||||
export async function reportBug(currentStep: string): Promise<{ status: string; body?: string; url?: string }> {
|
||||
const response = await fetch(`${API_BASE}/report-bug?step=${encodeURIComponent(currentStep)}`);
|
||||
return response.json();
|
||||
}
|
||||
|
|
|
|||
|
|
@ -327,6 +327,7 @@ func (w *Wizard) setupRoutes(mux *http.ServeMux) {
|
|||
mux.HandleFunc("/api/signing/status", w.handleSigningStatus)
|
||||
mux.HandleFunc("/api/complete", w.handleComplete)
|
||||
mux.HandleFunc("/api/close", w.handleClose)
|
||||
mux.HandleFunc("/api/report-bug", w.handleReportBug)
|
||||
|
||||
mux.HandleFunc("/assets/apple-sdk-license.pdf", func(rw http.ResponseWriter, r *http.Request) {
|
||||
rw.Header().Set("Content-Type", "application/pdf")
|
||||
|
|
@ -517,6 +518,45 @@ func (w *Wizard) handleClose(rw http.ResponseWriter, r *http.Request) {
|
|||
}()
|
||||
}
|
||||
|
||||
func (w *Wizard) handleReportBug(rw http.ResponseWriter, r *http.Request) {
|
||||
rw.Header().Set("Content-Type", "application/json")
|
||||
|
||||
// Get current step from query parameter
|
||||
currentStep := r.URL.Query().Get("step")
|
||||
if currentStep == "" {
|
||||
currentStep = "unknown"
|
||||
}
|
||||
|
||||
// Gather system info
|
||||
w.stateMu.RLock()
|
||||
system := w.state.System
|
||||
w.stateMu.RUnlock()
|
||||
|
||||
// Build a concise comment body - description first, then details table
|
||||
var sb strings.Builder
|
||||
sb.WriteString("**What went wrong?**\n\n\n\n")
|
||||
sb.WriteString("**What were you doing when the issue occurred?**\n\n\n\n")
|
||||
sb.WriteString("---\n\n")
|
||||
sb.WriteString("| | |\n")
|
||||
sb.WriteString("|--|--|\n")
|
||||
sb.WriteString(fmt.Sprintf("| Platform | %s |\n", system.OS))
|
||||
sb.WriteString(fmt.Sprintf("| Arch | %s |\n", system.Arch))
|
||||
sb.WriteString(fmt.Sprintf("| Wails | %s |\n", system.WailsVersion))
|
||||
sb.WriteString(fmt.Sprintf("| Go | %s |\n", system.GoVersion))
|
||||
sb.WriteString(fmt.Sprintf("| Step | %s |\n", currentStep))
|
||||
|
||||
issueURL := "https://github.com/wailsapp/wails/issues/4904#issue-comment-box"
|
||||
commentBody := sb.String()
|
||||
|
||||
// Return the body for the frontend to copy to clipboard
|
||||
// Frontend will handle opening the browser after showing the overlay
|
||||
json.NewEncoder(rw).Encode(map[string]interface{}{
|
||||
"status": "ready",
|
||||
"url": issueURL,
|
||||
"body": commentBody,
|
||||
})
|
||||
}
|
||||
|
||||
// execCommand runs a command and returns its output
|
||||
func execCommand(name string, args ...string) (string, error) {
|
||||
cmd := exec.Command(name, args...)
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@
|
|||
package setupwizard
|
||||
|
||||
import (
|
||||
"os/exec"
|
||||
"strconv"
|
||||
"strings"
|
||||
|
||||
|
|
@ -12,7 +13,6 @@ import (
|
|||
|
||||
func (w *Wizard) checkAllDependencies() []DependencyStatus {
|
||||
var deps []DependencyStatus
|
||||
hasNpm := false
|
||||
|
||||
deps = append(deps, checkGo())
|
||||
|
||||
|
|
@ -22,8 +22,9 @@ func (w *Wizard) checkAllDependencies() []DependencyStatus {
|
|||
if pm != nil {
|
||||
platformDeps, _ := packagemanager.Dependencies(pm)
|
||||
for _, dep := range platformDeps {
|
||||
// Skip npm from package manager - we'll check it via PATH instead
|
||||
if dep.Name == "npm" {
|
||||
hasNpm = true
|
||||
continue
|
||||
}
|
||||
status := DependencyStatus{
|
||||
Name: dep.Name,
|
||||
|
|
@ -35,18 +36,23 @@ func (w *Wizard) checkAllDependencies() []DependencyStatus {
|
|||
status.Status = "installed"
|
||||
status.Version = dep.Version
|
||||
} else {
|
||||
status.Installed = false
|
||||
status.Status = "not_installed"
|
||||
status.InstallCommand = dep.InstallCommand
|
||||
// Also check if the binary is in PATH (might be installed via other means)
|
||||
if _, err := exec.LookPath(dep.Name); err == nil {
|
||||
status.Installed = true
|
||||
status.Status = "installed"
|
||||
} else {
|
||||
status.Installed = false
|
||||
status.Status = "not_installed"
|
||||
status.InstallCommand = dep.InstallCommand
|
||||
}
|
||||
}
|
||||
|
||||
deps = append(deps, status)
|
||||
}
|
||||
}
|
||||
|
||||
if !hasNpm {
|
||||
deps = append(deps, checkNpm())
|
||||
}
|
||||
// Always check npm via PATH (might be installed via nvm, fnm, etc.)
|
||||
deps = append(deps, checkNpm())
|
||||
|
||||
deps = append(deps, checkDocker())
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue