Lucky Vite

A Crystal shard to seamlessly integrate Vite with Lucky Framework.

This shard follows Vite's instructions on how to use Vite with a backend framework

Installation

Add the dependency to your shard.yml:

dependencies:
  lucky_vite:
    github: wout/lucky_vite

Run shards install
Run yarn add -D vite vite-plugin-lucky to install Vite and the plugin for Lucky

Note: Look at vite-plugin-lucky for more info about the plugin.

Setup

There are a few things to set up and change to finalize the installation.

1. Generate files

Run bin/lucky_vite init to create the following files:

config/lucky_vite.json: the shared config for Lucky and Vite
vite.config.js: the Vite config loading vite-plugin-lucky
src/js/entry/main.js: the first entry point with a basic setup
src/css/main.css: an empty stylesheet which is referenced by main.js

Note: The initializer accepts a name option for the entry script: bin/lucky_vite init --name=app.

2. Load the Vite manifest

Replace the Lucky::AssetHelpers.load_manifest line in src/app.cr with:

-Lucky::AssetHelpers.load_manifest
+LuckyVite::AssetHelpers.load_manifest

Note: The load_manifest macro optionally takes a path to the lucky_vite.json config.

3. Register the Vite processes

Update the Procfile.dev by removing the assets process and adding the two following ones:

system_check: script/system_check && sleep 100000
web: lucky watch --reload-browser
-assets: yarn watch
+vite_server: yarn vite
+vite_watcher: yarn watch

4. Register the Vite runners

Change the scripts section in package.json to use vite instead of laravel mix:

{
  // ...
  "scripts": {
-    "heroku-postbuild": "yarn prod",
-    "dev": "yarn run mix",
-    "watch": "yarn run mix watch",
-    "prod": "yarn run mix --production",
+    "heroku-postbuild": "yarn build",
+    "build": "yarn run vite build",
+    "watch": "yarn run vite build --watch"
  },
  // ...
}

5. Add manifest setup

In script/setup.cr, find the "Compiling assets" step and change the command:

# ...
notice "Compiling assets"
- run_command "yarn", "dev"
+ run_command "yarn", "run", "vite", "build"
# ...

Further steps

if you use the CI workflow for Github Actions, you need to change yarn prod into yarn build in ci.yml
you may want to exclude Vite's outDir (e.g. public/assets) from the repo
all the laravel-mix dependencies can be removed from from package.json
webpack.mix.js can be removed

Usage

Start with including the shard in your app first:

# in src/shards.cr
require "lucky_vite"

Tags

This shard provides three levels of control over the individual Vite tags.

Important: All vite_* tags should be placed at the absolute bottom of your element. HMR functionality will remove all tags between the entry point tag and the end of head.

Hands-off

The vite_entry_tags macro method serves all your Vite needs, but it gives you the least amount of control over the individual tags that are generated:

# src/components/shared/layout_head.cr
vite_entry_tags "main.js"

It does a bunch of things. In development, it loads @vite/client and the given entry script. Vite will dynamically load any stylesheets imported in the entry script.

In production, it will load the static versions from the manifest and create individual tags for all of them, including stylesheets. With this macro, the whole frontend is served.

It also accepts any attributes you'd want on all the generated tags:

vite_entry_tags "main.js", data_turbo_track: "reload"

One downside is that the attributes will be applied to all generated tags, which you may not want in some cases.

A bit of control

If you need different attribtues on style tags than on script tags, you can use the following three methods:

vite_client_tag
vite_js_link "main.js", defer: true
vite_css_links "main.js"

Together they do the exact same thing as vite_entry_tags.

Note: the vite_css_links macro takes the main JS entry point as an argument, because that's where the CSS is imported. This macro will only generate output in production.

Full control

If you need even more control over the generated tags, you can use the asset macro in combination with Lucky's js_link and css_link methods:

vite_client_tag
js_link asset("main.js"), type: "module"
vite_css_links "main.js"

The example above does the exact same thing as vite_entry_tags.

Using React

If you're using React with the @vitejs/plugin-react plugin, you need to add the vite_react_refresh_tag method before any other asset tags to inject the refresh runtime served by Vite:

vite_react_refresh_tag
vite_client_tag
# ...

Static assets

LuckyVite manages the asset pipeline by overwriting Lucky's asset and dynamic_asset macros.

img src: asset("@images/logo.png")

Note: The asset helper uses Vite's aliases for easier referencing. Aliases can be configured in config/lucky_vite.json.

Configuration

Lucky and Vite share some information which is managed through the config/lucky_vite.json file. It comes with the following defaults:

{
  "aliases": ["css", "fonts", "images", "js"],
  "outDir": "public/assets",
  "root": "src/js",
  "entry": "entry",
  "host": "127.0.0.1",
  "port": 3010
}

Here's a bit more info about the available properties:

aliases (string[]): a list of directories for Vite to create aliases
- default: ["js", "css", "images", "fonts"])
- example: @images becomes src/images
outDir (string): the target dir for Vite
- default: "public/assets"
- note: this will be cleared on every run
root (string): the javascript root
- default: "src/js"
entry (string): this is where Vite looks for entry scripts
- default: "entry"
https (boolean): uses https: for the Vite server if set to true
- default: false
host (string | boolean): host name for the Vite server
- default: "127.0.0.1"
- note: if set to true, it will listen on 0.0.0.0 (all addresses)
port (string | number): port for the Vite server
- default: 3010
origin (string): alternative to using https, host and port
- example: "http://localhost:3210"

Note: Not all Vite's configuration options are recognised here as this file covers that's shared between Vite and Lucky. You can add other Vite-specific configuration options directly in vite.config.js.