The Preview Problem
When an AI generator produces code, you need to see the result immediately. The question is how. Most platforms take one of two approaches: they either show a static screenshot, or they compile the code in the browser using tools like WebContainers or Sandpack. Both have significant limitations.
Static screenshots are obviously insufficient -- you cannot interact with them, scroll, click buttons, or test functionality. Browser-based compilation is better but introduces its own problems: large download sizes for the compilation toolchain, limited Node.js API support, no backend execution, slow initial compile times, and sandbox restrictions that prevent many npm packages from working.
VULK takes a third approach: server-side preview. Your code is compiled and run on an actual server, and you see the result in an iframe. This sounds simple, but the engineering behind it determines whether the experience is fast and reliable or slow and broken.
How VULK's Preview Works
Here is the step-by-step flow from code generation to visible preview:
Step 1: Code generation. The AI model streams its response, producing files wrapped in vulkAction XML tags. As each file is completed, VULK extracts the file path and content.
Step 2: File transfer. Generated files are sent to the preview service running on a dedicated server (webapp.vulk.dev). Each project gets an isolated environment with its own filesystem and process space.
Step 3: Dependency installation. The preview service reads the generated package.json, installs dependencies with npm, and caches them. If the same dependencies were used in a previous generation, the cached node_modules is reused -- this is a major speed optimization since dependency installation is typically the slowest step.
Step 4: Build and serve. For Vite projects (React, vanilla JS, Three.js), the preview service runs the Vite dev server. For Flutter, it runs the Flutter web build. For PHP/Laravel, it starts a PHP development server. The appropriate build tool for the stack is used automatically.
Step 5: Iframe rendering. The running application is proxied through a unique URL and displayed in an iframe in the VULK editor. The iframe receives the full, running application -- not a simulation, not a partial render, but the actual application running on a real server.
Step 6: Hot reload on edits. When you send a follow-up prompt and VULK generates modified files, only the changed files are updated on the preview server. Vite's hot module replacement picks up the changes and updates the iframe without a full page reload. You see your changes in under a second.
Why Server-Side Beats Browser-Based
The server-side approach has concrete advantages that affect your daily workflow.
Backend code actually runs. If your application has an Express.js API, PostgreSQL queries, or server-side logic, it runs on the preview server. Browser sandboxes cannot execute backend code -- they either mock it or skip it entirely. In VULK, when you generate a full-stack app, both the frontend and backend run in the preview, so you can test the entire flow: registration, login, data creation, API calls, everything.
No browser sandbox limitations. Browser-based compilation tools run inside a Service Worker or Web Worker. They emulate a Node.js environment but cannot support all Node.js APIs. Some npm packages fail silently. Native modules do not work. File system operations are restricted. Server-side preview has none of these limitations -- it is a real Node.js environment.
Faster for complex projects. Browser-based compilation downloads the compiler toolchain to the user's browser and runs the build there. For a simple React app, this works. For a project with 50+ dependencies, TypeScript compilation, and asset processing, it becomes slow. Server-side builds run on dedicated hardware that is consistently fast regardless of the user's device or network.
Consistent across devices. A developer on a high-end MacBook Pro and a developer on a budget Chromebook see the same preview performance. The build runs on the server, not the client. This also means mobile devices -- where browser-based compilation is painfully slow -- get the same experience as desktop.
Accurate rendering. Browser sandboxes sometimes render things slightly differently than a real browser tab because they run inside an iframe with specific Content Security Policy restrictions. VULK's preview is an iframe loading from a real URL, so the rendering matches what users will see in production.
The Preview Service Architecture
The preview service runs on a dedicated server (separate from the main VULK application) to isolate resource usage. Each user project gets:
- An isolated directory on the filesystem
- A dedicated process for the dev server
- Port allocation from a pool of available ports
- Automatic cleanup after inactivity (processes are stopped, files are retained for quick restart)
Process isolation means one user's broken code cannot crash another user's preview. If your generated app has an infinite loop or memory leak, it affects only your preview process, which the service monitors and restarts if necessary.
Supported Stacks and Their Preview Behavior
Different tech stacks have different preview characteristics in VULK.
React + Vite -- The most common stack. Vite's dev server starts in under a second (after initial dependency install). Hot module replacement updates components without losing state. CSS changes are reflected instantly.
Flutter Web -- Flutter compiles Dart to JavaScript. The initial build takes longer (15-30 seconds) but subsequent hot reloads are fast. The preview shows the actual Flutter web rendering, including Material Design widgets and custom painters.
React Native + Expo -- Previewed as a web export via Expo's web support. Not pixel-perfect compared to native, but functional for layout and logic testing.
Shopify (Liquid) -- Liquid templates are rendered server-side with sample data. The preview shows the theme as it would appear in a Shopify store, with products, collections, and pages populated.
PHP/Laravel -- PHP's built-in development server runs Laravel. Blade templates, routing, database queries -- all functional in the preview.
Three.js games -- Standard Vite serving. The 3D canvas renders at full performance since WebGL runs in the iframe's actual browser context, not in a simulated environment.
What You See During Generation
VULK does not make you wait for the entire generation to finish before showing the preview. The preview updates progressively:
- As soon as the base files (
index.html,main.tsx,package.json) are generated, the preview service starts the dev server. - As additional component files stream in, Vite's file watcher detects them and triggers hot updates.
- You see the app building up in real time -- first the layout, then components appearing, then styles applying.
This progressive rendering gives you early feedback. If the AI is going in the wrong direction, you can see it within seconds and stop the generation rather than waiting for it to finish.
Preview Limitations
No system is perfect. The preview has constraints worth knowing:
Cold start time. If your project uses dependencies that are not cached, the initial npm install takes 10-30 seconds. Subsequent generations in the same project are much faster because dependencies are cached.
No native mobile preview. Flutter and React Native are previewed as web exports. The web version is functionally accurate but visually approximate. For pixel-perfect mobile testing, you need to export the project and run it in a simulator or on a device.
Resource limits. Each preview environment has CPU and memory limits to ensure fair resource sharing. Applications that are extremely resource-intensive (e.g., processing large datasets, running complex simulations) may hit these limits.
Network isolation. Preview environments cannot make outbound HTTP requests to arbitrary services for security reasons. If your generated app calls a third-party API, those calls will fail in preview. You can test them after deploying.
From Preview to Production
The preview is not a separate build of your app -- it is the same code running in a development environment. When you click Deploy, VULK takes that same code, runs a production build (npm run build), and deploys the output to Cloudflare Pages. The production version is what you tested in preview, optimized for production with minification, tree shaking, and asset optimization.
This continuity between preview and production means there are no surprises at deploy time. What you saw is what your users get.
