{"id":18158235,"url":"https://github.com/wout/lucky_vite","last_synced_at":"2025-05-07T03:08:23.552Z","repository":{"id":174129844,"uuid":"651626679","full_name":"wout/lucky_vite","owner":"wout","description":"A Crystal shard to seamlessly integrate Vite with Lucky Framework","archived":false,"fork":false,"pushed_at":"2024-04-06T14:54:56.000Z","size":201,"stargazers_count":9,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T03:08:12.578Z","etag":null,"topics":["crystal","lucky","lucky-framework","vite","vitejs"],"latest_commit_sha":null,"homepage":"","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wout.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-09T17:03:17.000Z","updated_at":"2025-03-22T18:06:08.000Z","dependencies_parsed_at":"2024-04-06T15:40:43.625Z","dependency_job_id":null,"html_url":"https://github.com/wout/lucky_vite","commit_stats":null,"previous_names":["wout/lucky_vite"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wout%2Flucky_vite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wout%2Flucky_vite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wout%2Flucky_vite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wout%2Flucky_vite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wout","download_url":"https://codeload.github.com/wout/lucky_vite/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252804217,"owners_count":21806770,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crystal","lucky","lucky-framework","vite","vitejs"],"created_at":"2024-11-02T07:05:55.618Z","updated_at":"2025-05-07T03:08:23.516Z","avatar_url":"https://github.com/wout.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/wout/lucky_vite/main/logo.svg\" width=\"200px\"/\u003e\n\n  \u003cbr\u003e\n\nLucky Vite\n\n\u003c/h1\u003e\n\n\u003ch3 align=\"center\"\u003e\n  A Crystal shard to seamlessly integrate \u003ca href=\"https://vitejs.dev/\" tagret=\"_blank\"\u003eVite\u003c/a\u003e with \u003ca href=\"https://luckyframework.org/\" tagret=\"_blank\"\u003eLucky Framework\u003c/a\u003e.\n\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  This shard follows Vite's instructions on how to \u003ca href=\"https://vitejs.dev/guide/backend-integration.html#backend-integration\" target=\"_blank\"\u003euse Vite with a backend framework\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/wout/lucky_vite\" title=\"Github\"/\u003e\n  \u003cimg src=\"https://img.shields.io/github/v/tag/wout/lucky_vite\" title=\"GitHub tag (latest SemVer)\"/\u003e\n  \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/wout/lucky_vite/ci.yml?branch=main\" title=\"GitHub Workflow Status\"/\u003e\n\u003c/div\u003e\n\n## Installation\n\n1. Add the dependency to your `shard.yml`:\n\n```yaml\ndependencies:\n  lucky_vite:\n    github: wout/lucky_vite\n```\n\n2. Run `shards install`\n\n3. Run `yarn add -D vite vite-plugin-lucky` to install Vite and the plugin for Lucky\n\n**Note**: Look at [vite-plugin-lucky](https://github.com/wout/vite-plugin-lucky) for more info about the plugin.\n\n## Setup\n\nThere are a few things to set up and change to finalize the installation.\n\n### 1. Generate files\n\nRun **`bin/lucky_vite init`** to create the following files:\n\n- `config/lucky_vite.json`: the shared config for Lucky and Vite\n- `vite.config.js`: the Vite config loading `vite-plugin-lucky`\n- `src/js/entry/main.js`: the first entry point with a basic setup\n- `src/css/main.css`: an empty stylesheet which is referenced by `main.js`\n\n**Note**: The initializer accepts a name option for the entry script: `bin/lucky_vite init --name=app`.\n\n### 2. Load the Vite manifest\n\nReplace the `Lucky::AssetHelpers.load_manifest` line in `src/app.cr` with:\n\n```diff\n-Lucky::AssetHelpers.load_manifest\n+LuckyVite::AssetHelpers.load_manifest\n```\n\n**Note**: The `load_manifest` macro optionally takes a path to the `lucky_vite.json` config.\n\n### 3. Register the Vite processes\n\nUpdate the `Procfile.dev` by removing the `assets` process and adding the two following ones:\n\n```diff\nsystem_check: script/system_check \u0026\u0026 sleep 100000\nweb: lucky watch --reload-browser\n-assets: yarn watch\n+vite_server: yarn vite\n+vite_watcher: yarn watch\n```\n\n### 4. Register the Vite runners\n\nChange the scripts section in `package.json` to use vite instead of laravel mix:\n\n```diff\n{\n  // ...\n  \"scripts\": {\n-    \"heroku-postbuild\": \"yarn prod\",\n-    \"dev\": \"yarn run mix\",\n-    \"watch\": \"yarn run mix watch\",\n-    \"prod\": \"yarn run mix --production\",\n+    \"heroku-postbuild\": \"yarn build\",\n+    \"build\": \"yarn run vite build\",\n+    \"watch\": \"yarn run vite build --watch\"\n  },\n  // ...\n}\n```\n\n### Further steps\n\n- if you use the CI workflow for Github Actions, you need to change `yarn prod` into `yarn build` in `ci.yml`\n- if you use `script/setup`, uncomment `yarn dev | indent` under `Compiling assets`\n- you may want to exclude Vite's `outDir` (e.g. `public/assets`) from the repo\n- all the `laravel-mix` dependencies can be removed from from `package.json`\n- `webpack.mix.js` can be removed\n\n## Usage\n\nStart with including the shard in your app first:\n\n```crystal\n# in src/shards.cr\nrequire \"lucky_vite\"\n```\n\n### Tags\n\nThis shard provides three levels of control over the individual Vite tags.\n\n#### Hands-off\n\nThe `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:\n\n```crystal\n# src/components/shared/layout_head.cr\nvite_entry_tags \"main.js\"\n```\n\nIt 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.\n\nIn 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.\n\nIt also accepts any attributes you'd want on all the generated tags:\n\n```crystal\nvite_entry_tags \"main.js\", data_turbo_track: \"reload\"\n```\n\nOne downside is that the attributes will be applied to all generated tags, which you may not want in some cases.\n\n#### A bit of control\n\nIf you need different attribtues on style tags than on script tags, you can use the following three methods:\n\n```crystal\nvite_client_tag\nvite_js_link \"main.js\"\nvite_css_link \"main.css\"\n```\n\nTogether they do the exact same thing as `vite_entry_tags`.\n\n**Note**: `vite_css_link` won't output anything in development as stylesheets are dynamically loaded by Vite.\n\n#### Full control\n\nIf 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:\n\n```crystal\nvite_client_tag\njs_link asset(\"main.js\"), type: \"module\"\ncss_link asset(\"main.css\") unless LuckyEnv.development?\n```\n\nThe example above does the exact same thing as `vite_entry_tags`.\n\n### Using React\n\nIf 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:\n\n```crystal\nvite_react_refresh_tag\nvite_client_tag\n# ...\n```\n\n### Static assets\n\nLuckyVite manages the asset pipeline by overwriting Lucky's `asset` and `dynamic_asset` macros.\n\n```crystal\nimg src: asset(\"@images/logo.png\")\n```\n\n**Note**: The asset helper uses Vite's aliases for easier referencing. Aliases can be configured in `config/lucky_vite.json`.\n\n## Configuration\n\nLucky and Vite share some information which is managed through the `config/lucky_vite.json` file. It comes with the following defaults:\n\n```json\n{\n  \"aliases\": [\"css\", \"fonts\", \"images\", \"js\"],\n  \"outDir\": \"public/assets\",\n  \"root\": \"src/js\",\n  \"entry\": \"entry\",\n  \"host\": \"127.0.0.1\",\n  \"port\": 3010\n}\n```\n\nHere's a bit more info about the available properties:\n\n- **`aliases`** (_`string[]`_): a list of directories for Vite to create aliases\n  - _default_: `[\"js\", \"css\", \"images\", \"fonts\"]`)\n  - _example_: `@images` becomes `src/images`\n- **`outDir`** (_`string`_): the target dir for Vite\n  - _default_: `\"public/assets\"`\n  - _note_: this will be cleared on every run\n- **`root`** (_`string`_): the javascript root\n  - _default_: `\"src/js\"`\n- **`entry`** (_`string`_): this is where Vite looks for entry scripts\n  - _default_: `\"entry\"`\n- **`https`** (_`boolean`_): uses `https:` for the Vite server if set to `true`\n  - _default_: `false`\n- **`host`** (_`string | boolean`_): host name for the Vite server\n  - _default_: `\"127.0.0.1\"`\n  - _note_: if set to `true`, it will listen on `0.0.0.0` (all addresses)\n- **`port`** (_`string | number`_): port for the Vite server\n  - _default_: `3010`\n- **`origin`** (_`string`_): alternative to using `https`, `host` and `port`\n  - _example_: `\"http://localhost:3210\"`\n\n**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`.\n\n## Documentation\n\n- [API (main)](https://wout.github.io/lucky_vite/)\n\n## Development\n\nMake sure you have [Guardian.cr](https://github.com/f/guardian) installed. Then run:\n\n```bash\n$ guardian\n```\n\nThis will automatically:\n\n- run ameba for src and spec files\n- run the relevant spec for any file in src\n- run spec file whenever they are saved\n\n## Contributing\n\nWe use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for our commit messages, so please adhere to that pattern.\n\n1. Fork it (\u003chttps://github.com/wout/lucky_vite/fork\u003e)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'feat: new feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n## Contributors\n\n- [Wout](https://github.com/wout) - creator and maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwout%2Flucky_vite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwout%2Flucky_vite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwout%2Flucky_vite/lists"}