How luislavena/crystal-vite works
Based on our analysis of the file tree and the README, this project is an integration library (“shard”) intended to bridge Crystal-based backend applications with Vite.js as the frontend build tool. Its core purpose is to simplify development by proxying front-end requests (and handling HMR in development) and to ease production deployments by using a manifest file for asset loading.
Core Components
• Crystal Application (Backend): This is your main application written in Crystal. It utilizes the Vite integration via the provided shard.
• Vite.js Development Server: When in development mode, the Vite server runs separately but is transparently proxied through the Crystal app. It provides services like Hot Module Replacement (HMR).
• Vite Plugin for Crystal: This is a specialized module (found in the “vite-plugin-crystal” directory) that helps configure Vite’s behavior according to the needs of Crystal applications.
• Frontend Assets: These are the files (JavaScript, CSS, etc.) located in the “src/frontend” folder (and its subdirectories, such as “entrypoints” and “styles”) which are built and served either directly by Vite in development or loaded via a manifest in production.
• Proxy Handler within Crystal (“src/vite/proxy_handler.cr”): This module is crucial when proxying the front-end asset requests during development.
Out Relationships and Dataflows
• One path goes to “Vite.js Development Server” (via the proxy handler) – representing the development mode data flow and enabling HMR.
• A separate path represents production mode: “Crystal Application” reads the static “manifest.json” (generated by Vite in production) and serves the hashed assets from the “public/build” directory.
• That the “Vite Plugin for Crystal” is used during build and configuration time to align frontend code (from “src/frontend”) with the expected configuration of the Crystal integration.
• That the tag helper methods in the library (script_tag, style_tag, etc. used in views) work to dynamically include the proper asset URLs (either direct URLs to the dev server or hashed filenames from the manifest).
Architectural Patterns and Design Principles
• “Convention over Configuration”: Emphasize that the project assumes, by default, specific directories like “src/frontend” and “entrypoints”, reducing custom configuration.
• Transparent Proxying: In development, the responsibility for simplifying the connection between the Crystal application and the Vite server is handled by the “dev_handler”. Ensure that this proxying component is clearly marked.
Technologies and Frameworks
• Crystal Programming Language (backend)
• Vite.js (frontend build tool and dev server)
• Node Package Ecosystem (for Vite plugin and package.json scripts)
• Docker/Compose files are present, so optionally note that containerized workflows for demos can be represented as deployment environments, although the primary focus is on the runtime integration.