Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wout/lucky_vite
A Crystal shard to seamlessly integrate Vite with Lucky Framework
https://github.com/wout/lucky_vite
crystal lucky lucky-framework vite vitejs
Last synced: 13 days ago
JSON representation
A Crystal shard to seamlessly integrate Vite with Lucky Framework
- Host: GitHub
- URL: https://github.com/wout/lucky_vite
- Owner: wout
- License: mit
- Created: 2023-06-09T17:03:17.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-04-06T14:54:56.000Z (7 months ago)
- Last Synced: 2024-05-06T00:05:06.842Z (6 months ago)
- Topics: crystal, lucky, lucky-framework, vite, vitejs
- Language: Crystal
- Homepage:
- Size: 196 KB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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
1. Add the dependency to your `shard.yml`:
```yaml
dependencies:
lucky_vite:
github: wout/lucky_vite
```
2. Run `shards install`
3. Run `yarn add -D vite vite-plugin-lucky` to install Vite and the plugin for Lucky
**Note**: Look at [vite-plugin-lucky](https://github.com/wout/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:
```diff
-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:
```diff
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:
```diff
{
// ...
"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` into `yarn build` in `ci.yml`
- if you use `script/setup`, uncomment `yarn dev | indent` under `Compiling 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 from `package.json`
- `webpack.mix.js` can be removed
## Usage
Start with including the shard in your app first:
```crystal
# 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:
```crystal
# 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:
```crystal
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:
```crystal
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:
```crystal
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:
```crystal
vite_react_refresh_tag
vite_client_tag
# ...
```
### Static assets
LuckyVite manages the asset pipeline by overwriting Lucky's `asset` and `dynamic_asset` macros.
```crystal
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:
```json
{
"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`.
## Documentation
- [API (main)](https://wout.github.io/lucky_vite/)
## Development
Make sure you have [Guardian.cr](https://github.com/f/guardian) installed. Then run:
```bash
$ 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](https://www.conventionalcommits.org/en/v1.0.0/) for our commit messages, so please adhere to that pattern.
1. Fork it ()
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'feat: new feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
## Contributors
- [Wout](https://github.com/wout) - creator and maintainer