Vite Mockup Sandbox Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Vite Mockup Sandbox is a specialized development environment within the Hospice Roadmap project designed for rapid prototyping and design iteration. It operates as a non-shipping workspace package (artifacts/mockup-sandbox) that allows developers and designers to build and preview UI components in isolation before they are integrated into the primary React Native mobile application.
The sandbox leverages Vite for high-performance builds and a custom-built preview plugin to automate the discovery of mockup components. This workflow ensures that design decisions are validated in a web-based "sandbox" before being committed to the mobile runtime, maintaining a clean separation between experimental prototypes and production code.
Sources: replit.md, attached_assets/Pasted-Make-a-focused-repo-cleanup-and-dependency-hygiene-pass_1774842983742.txt
Architecture and Core Components
The sandbox is built as a React-based web application. Its primary responsibility is to dynamically scan a specific directory for .tsx files and provide a user interface to toggle between these different mockups.
Mockup Discovery Engine
The core of the workflow is the mockupPreviewPlugin.ts, a custom Vite plugin that automates component registration. It performs the following technical operations:
- Directory Watching: It monitors the
src/components/mockupsdirectory for additions or removals of.tsxfiles. - Dynamic Module Generation: It generates a manifest file (
src/.generated/mockup-components.ts) that maps file paths to dynamic import functions. - Path Filtering: It ignores files or directories starting with an underscore (
_), allowing developers to store utility components or private helpers within the mockups folder without exposing them to the preview UI.
Sources: artifacts/mockup-sandbox/mockupPreviewPlugin.ts:10-40, artifacts/mockup-sandbox/src/App.tsx:1-10
Component Relationship Diagram
The following diagram illustrates how the Vite plugin interacts with the filesystem to update the application's available views.
The diagram shows the automated flow from creating a file in the mockups directory to its availability in the Sandbox UI.
Sources: artifacts/mockup-sandbox/mockupPreviewPlugin.ts:25-70
Mockup Preview Logic
The frontend of the sandbox (App.tsx) utilizes the generated module map to provide a navigation interface.
Dynamic Loading
The application does not bundle all mockups at once. Instead, it uses a lazy-loading strategy where components are imported only when selected by the user. This is achieved through the ModuleMap type defined in the generated code, which returns a Promise of the component.
Key Logic Elements
| Element | Location | Description |
|---|---|---|
MOCKUPS_DIR | mockupPreviewPlugin.ts | The source directory for components: src/components/mockups. |
GENERATED_MODULE | mockupPreviewPlugin.ts | The output path for the auto-generated import map: src/.generated/mockup-components.ts. |
modules | App.tsx | The object containing all discovered mockup components as keys. |
isPreviewTarget | mockupPreviewPlugin.ts | Function that ensures segments starting with _ are excluded from discovery. |
Sources: artifacts/mockup-sandbox/mockupPreviewPlugin.ts:7-15, artifacts/mockup-sandbox/src/App.tsx:5-15
Sequence of Operations
The sandbox workflow follows a specific sequence from initialization to component rendering.
This sequence demonstrates the reactive nature of the sandbox, where filesystem changes trigger UI updates without manual configuration.
Sources: artifacts/mockup-sandbox/mockupPreviewPlugin.ts:90-130, artifacts/mockup-sandbox/src/App.tsx:20-40
Tooling and Workspace Integration
The sandbox is treated as "non-shipping tooling" and is isolated from the production mobile runtime. It uses its own set of dependencies and scripts as defined in its package.json.
- Build Scripts: The sandbox uses standard Vite commands (
vite,vite build,vite preview). - Dependency Hygiene: During repository cleanup passes, the sandbox is explicitly preserved as a design workflow tool but marked as distinct from
artifacts/mobile(the shipping app) andartifacts/api-server(the shipping API). - Replit Integration: The environment is configured to run within the Replit monorepo structure, allowing for web-based design previews.
Sources: artifacts/mockup-sandbox/package.json:6-15, attached_assets/Pasted-Make-a-focused-repo-cleanup-and-dependency-hygiene-pass_1774842983742.txt
Summary of Workflow Rules
The following table summarizes the operational rules governing the sandbox environment.
| Rule | Implementation Detail | Source |
|---|---|---|
| Privacy | Files/Folders starting with _ are ignored by the discovery engine. | mockupPreviewPlugin.ts:36 |
| Automation | The plugin runs discoverComponents on buildStart and on file change events. | mockupPreviewPlugin.ts:114 |
| State | The App.tsx state tracks the currently active "glob key" (path) to render. | App.tsx |
| Isolation | Sandbox is located in artifacts/mockup-sandbox to separate it from React Native code. | replit.md |
Sources: artifacts/mockup-sandbox/mockupPreviewPlugin.ts:34-40, replit.md
The Vite Mockup Sandbox Workflow provides a decoupled environment for the Hospice Roadmap project, enabling designers to verify UI components with high performance and minimal manual overhead. By using a custom Vite plugin to bridge the gap between the filesystem and the React UI, it ensures that the available mockups are always in sync with the source code.