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 Vitevite.config.js
: the Vite config loadingvite-plugin-lucky
src/js/entry/main.js
: the first entry point with a basic setupsrc/css/main.css
: an empty stylesheet which is referenced bymain.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"
},
// ...
}
Further steps
- if you use the CI workflow for Github Actions, you need to change
yarn prod
intoyarn build
inci.yml
- if you use
script/setup
, uncommentyarn dev | indent
underCompiling assets
- you may want to exclude Vite's
outDir
(e.g.public/assets
) from the repo - all the
laravel-mix
dependencies can be removed from frompackage.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.
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"
vite_css_link "main.css"
Together they do the exact same thing as vite_entry_tags
.
Note: vite_css_link
won't output anything in development as stylesheets are dynamically loaded by Vite.
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"
css_link asset("main.css") unless LuckyEnv.development?
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
becomessrc/images
- default:
outDir
(string
): the target dir for Vite- default:
"public/assets"
- note: this will be cleared on every run
- default:
root
(string
): the javascript root- default:
"src/js"
- default:
entry
(string
): this is where Vite looks for entry scripts- default:
"entry"
- default:
https
(boolean
): useshttps:
for the Vite server if set totrue
- default:
false
- default:
host
(string | boolean
): host name for the Vite server- default:
"127.0.0.1"
- note: if set to
true
, it will listen on0.0.0.0
(all addresses)
- default:
port
(string | number
): port for the Vite server- default:
3010
- default:
origin
(string
): alternative to usinghttps
,host
andport
- example:
"http://localhost:3210"
- example:
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
.
Documentation
Development
Make sure you have Guardian.cr installed. Then run:
$ guardian
This will automatically:
- run ameba for src and spec files
- run the relevant spec for any file in src
- run spec file whenever they are saved
Contributing
We use conventional commits for our commit messages, so please adhere to that pattern.
- Fork it (https://github.com/wout/lucky_vite/fork)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'feat: new feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Contributors
- Wout - creator and maintainer