How flowtricks/stacki works
Purpose and Entry Points
Stacki is an Electron desktop visual editor for Astro projects. The Electron main process starts the application and mediates local-project operations; the Vite/React renderer provides the editor UI. Primary entry points are electron/main.js, electron/preload.js, src/main.jsx, and src/App.jsx.
Desktop Process and Privileged Boundary
The main process owns filesystem access, child-process execution, project lifecycle, Git/GitHub commands, Astro dev-server management, and app updates. The preload bridge exposes approved IPC capabilities to the renderer rather than giving UI code direct Node access. Relevant paths: electron/main.js, electron/preload.js, electron/scaffold.js.
Astro Project Model and Safe Source Editing
Astro pages are parsed into a constrained visual model: an optional layout wrapper plus a flat sequence of self-closing component instances and props. That model is serialized back to .astro; pages outside this grammar are routed to code editing, avoiding destructive rewrites. Astro-specific parsing and component/prop extraction are centered in electron/astroParser.js, with UI schema support in src/elementSchemas.js and src/bindings.js.
Renderer Composition and Workspace Control
src/App.jsx coordinates project-open/welcome state, editor selection, and the major workspace panes. src/panels/WelcomeScreen.jsx starts or scaffolds projects; src/panels/PagesPanel.jsx manages page navigation; src/ui/PageSwitcher.jsx provides page switching. Renderer actions cross the preload IPC boundary for reads, writes, project mutations, and process commands.
Visual Page Authoring Flow
Users select components from the palette, build or reorder the page structure, then edit instance props. src/panels/PalettePanel.jsx exposes discovered Astro components, src/panels/StructurePanel.jsx represents the flat page model, and src/panels/PropsPanel.jsx renders typed prop controls. Drag/drop state is shared through src/dragState.js; source updates are auto-saved and passed to Astro’s hot-reload loop.
Preview and Code Fallback
The app launches astro dev for the selected project and embeds its local output as the live preview. src/panels/PreviewPane.jsx is the preview surface; src/panels/CanvasView.jsx supports visual canvas interaction. Complex or unsupported pages use the code-editor path rather than the structural editor, through src/ui/CodeEditor.jsx and src/ui/CodeWindow.jsx.
Styling, Assets, and CMS Editing
The Style panel is a substantial CSS authoring subsystem, mapping selected elements to style sections, cascading/resolved values, and native-style output. Its main boundary is src/panels/StylePanel.jsx / src/style-panel/index.tsx, with CSS resolution logic in src/style-panel/lib/cascade.ts and src/style-panel/lib/resolved.ts. Asset selection is handled by src/panels/AssetsPanel.jsx and src/assetPick.js; CMS schema/reference workflows use src/panels/CmsPanel.jsx, src/cmsSchema.js, and electron/cmsRefs.js.
External Runtime and Delivery
Runtime dependencies are Node.js/npm, an opened Astro project’s astro dev server, local Git, and optionally authenticated GitHub CLI for publishing. Git UI is represented by src/panels/GitChip.jsx; command execution remains in Electron. Packaging targets macOS and Windows, with signed release automation in .github/workflows/release.yml, macOS entitlements under resources/, and Electron auto-update publication configured through package.json.
Main entry points: main.js Electron main process · App.jsx Workspace controller · StructurePanel.jsx Visual page editor · preload.js Preload IPC bridge
Components 19
Electron Desktop
- Electron main process · Owns project operations, commands, dev server, and updates.
electron/main.js - Preload IPC bridge · Exposes approved renderer capabilities.
electron/preload.js - Project scaffolder
electron/scaffold.js - Astro parser · Parses only the supported layout and flat-component grammar.
electron/astroParser.js - CMS references
electron/cmsRefs.js
Renderer Workspace
- Workspace controller · Coordinates project state, editor selection, and panes.
src/App.jsx - Renderer entry
src/main.jsx - Welcome and pages · Opens, scaffolds, navigates, and switches pages.
src/panels/PagesPanel.jsx
Authoring Subsystems
- Visual page editor · Palette, flat structure, typed props, and shared drag state.
src/panels/StructurePanel.jsx - Component schemas · Supplies prop and binding UI definitions.
src/elementSchemas.js - Preview canvas · Embeds local output and supports canvas interaction.
src/panels/PreviewPane.jsx - Code fallback editor · Handles pages outside the safe visual grammar.
src/ui/CodeEditor.jsx - Style authoring · Resolves cascading styles and emits native CSS.
src/style-panel/index.tsx - Asset picker
src/panels/AssetsPanel.jsx - CMS editor
src/panels/CmsPanel.jsx
Project Runtime
- Opened Astro project · Contains Astro pages, components, assets, and CMS content.
- Astro dev server · Builds and hot-reloads the selected project.
- Git and GitHub CLI · Used for local Git actions and optional GitHub publishing.
Release Delivery
- Signed release automation · Packages macOS and Windows builds with auto-update publication.
.github/workflows/release.yml
Connections 21
- Renderer entry → Workspace controller: mounts
- Workspace controller → Preload IPC bridge: uses IPC
- Preload IPC bridge → Electron main process: approved calls
- Electron main process → Project scaffolder: creates projects
- Electron main process → Astro parser: reads and serializes pages
- Electron main process → CMS references: updates references
- Electron main process → Opened Astro project: reads and writes
- Electron main process → Astro dev server: starts and manages
- Electron main process → Git and GitHub CLI: runs commands
- Workspace controller → Welcome and pages: hosts
- Workspace controller → Visual page editor: hosts
- Workspace controller → Preview canvas: hosts
- Workspace controller → Code fallback editor: routes unsupported pages
- Visual page editor → Component schemas: uses schemas
- Visual page editor → Astro parser: edits safe model
- Style authoring → Opened Astro project: writes CSS
- Asset picker → Opened Astro project: selects local assets
- CMS editor → CMS references: manages schema references
- Preview canvas → Astro dev server: embeds output
- Astro dev server → Opened Astro project: serves and watches
- Signed release automation → Electron main process: packages desktop app