Build macOS Menubar Apps with Tuist
Skill for building macOS menubar apps with Tuist and SwiftUI, enforcing model/client/store/view architecture boundaries.
Why it matters
Develop and maintain macOS menubar applications using a Tuist-first approach. This asset provides a structured workflow and stable launch scripts to ensure testable and predictable networking, state management, and UI.
Outcomes
What it gets done
Generate Tuist manifests and project configurations for macOS menubar apps.
Implement architecture guidance for separating networking, state, and UI layers.
Utilize stable launch scripts for local development and iteration.
Ensure code adheres to strict architectural boundaries for testability.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/ag-macos-menubar-tuist-app | bash Overview
Macos Menubar Tuist App
A skill for building Tuist-based macOS menubar apps in SwiftUI, enforcing model/client/store/view architecture boundaries, a defined file layout, and standardized local build and launch scripts. Use when building or maintaining an LSUIElement menubar app with Tuist and SwiftUI. Scoped to this specific stack - not a substitute for environment-specific testing or review.
What it does
macos-menubar-tuist-app is a skill for building and maintaining macOS menubar apps with a Tuist-first workflow and stable launch scripts, preserving strict architecture boundaries so networking, state, and UI stay testable and predictable. It enforces LSUIElement = true menubar-only behavior by default, keeps transport and decoding logic out of SwiftUI view bodies, keeps state transitions in an @Observable (or equivalent) store layer rather than in row/view code, and keeps model decoding resilient to API drift with optional fields, safe fallbacks, and defensive parsing. Tuist manifests are treated as the source of truth over hand-edited generated Xcode artifacts, and tuist xcodebuild build is preferred over raw xcodebuild in local run scripts.
It specifies an expected file layout: Project.swift for app target/settings/resources/Info.plist keys, Sources/*Model*.swift for API/domain models and decoding, Sources/*Client*.swift for requests and response mapping, Sources/*Store*.swift for observable state/refresh/filtering/caching, Sources/*MenuView*.swift for menu composition, Sources/*RowView*.swift for row rendering, plus canonical run-menubar.sh and stop-menubar.sh scripts for local restart/build/launch.
The workflow proceeds bottom-to-top: confirm Tuist ownership (Tuist.swift/Project.swift exist, read existing run scripts before changing launch behavior); probe backend behavior with curl before coding assumptions, implementing full-list handling with local trimming in the store if an endpoint ignores limit/page parameters; implement models first, then client request/decoding logic, then store refresh/filtering/cache policy, then wire views last; keep app entry focused on scene/menu wiring and dependency injection rather than embedding business logic; and standardize launch ergonomics so the run script restarts an existing instance, never opens Xcode as a side effect, and uses tuist generate --no-open plus TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build instead of raw xcodebuild.
TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build -scheme <TargetName> -configuration Debug
Four failure patterns get specific fix directions: when tuist run cannot resolve the macOS destination, use the run/stop scripts as the canonical local path instead; when menu UI is laggy or inconsistent after refresh, move derived state and filtering into the store and keep views render-only; when an API payload change breaks decoding, relax model decoding with optional fields and defaults and surface missing data safely; and when a feature request looks like a quick UI patch, trace the root cause through model/client/store before touching row/menu presentation code. A completion checklist requires preserving menubar-only behavior, keeping network/state logic out of view bodies, keeping Tuist manifests aligned with the actual build/run flow, running the validation matrix for touched areas, and reporting concrete commands run and their outcomes.
When to use - and when NOT to
Use this skill when working on LSUIElement menubar utilities built with Tuist and SwiftUI, or when you need Tuist manifests, launch scripts, or architecture guidance for a menubar app.
It is scoped to Tuist-based macOS menubar apps specifically - the file-layout and workflow guidance assumes this stack and architecture. It is not a substitute for environment-specific validation, testing, or expert review; if required inputs, permissions, or success criteria are missing, ask before proceeding.
Inputs and outputs
Inputs: an existing or new Tuist-managed macOS menubar app project, a feature request, or a build/launch failure to diagnose.
Outputs: Tuist manifest and Swift source changes following the model/client/store/view layering, updated or new run-menubar.sh/stop-menubar.sh scripts, and validation-matrix command output confirming the build/launch still works.
Integrations
Built around Tuist (Tuist.swift, Project.swift, tuist generate, tuist xcodebuild build) and SwiftUI with @Observable state, plus shell-based run-menubar.sh/stop-menubar.sh launch scripts.
Who it's for
macOS developers building or maintaining Tuist-based menubar utilities who want consistent architecture boundaries and reliable local build/launch scripts.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.