Add JS asset instructions to README (#69)

josefarias · Mar 6, 2024 · 5e011e3 · 5e011e3
1 parent 5726f44
commit 5e011e3
Showing 1 changed file with 77 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -12,26 +12,98 @@
 
 ## Installation
 
-Add this line to your application's Gemfile and run `bundle install`:
+First, make sure [Turbo](https://github.com/hotwired/turbo-rails) and [Stimulus](https://github.com/hotwired/stimulus-rails) are configured and running properly on your app.
+
+Then, add this line to your application's Gemfile and run `bundle install`:
 
 ```ruby
 gem "hotwire_combobox"
 ```
 
-Then add the stylesheet to your layout:
+Finally, configure your assets:
+
+### Configuring JS
+
+Before continuing, you should know whether your app is using importmaps or JS bundling in your asset pipeline.
+
+#### Importmaps
+
+Most apps using importmaps won't need any configuration. If things aren't working for you, read on.
+
+In `app/javascript/controllers/index.js` you should have one of the following:
+
+Either,
+
+```js
+import { application } from "controllers/application" // or equivalent
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+
+eagerLoadControllersFrom("controllers", application)
+```
+
+Or,
+
+```js
+import { application } from "controllers/application" // or equivalent
+import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
+
+lazyLoadControllersFrom("controllers", application)
+```
+
+Or,
+
+```js
+import { application } from "controllers/application" // or equivalent
+
+import HwComboboxController from "controllers/hw_combobox_controller"
+application.register("hw-combobox", HwComboboxController)
+```
+
+#### JS bundling (esbuild, rollup, etc)
+
+First, install the JS portion of HotwireCombobox from npm with one of the following:
+
+```bash
+yarn add @josefarias/hotwire_combobox
+```
+
+```bash
+npm install @josefarias/hotwire_combobox
+```
+
+Then, register the library's stimulus controller in `app/javascript/controllers/index.js` as follows:
+
+```js
+import { application } from "./application" // or equivalent
+
+import HwComboboxController from "@josefarias/hotwire_combobox"
+application.register("hw-combobox", HwComboboxController)
+```
+
+### Configuring CSS
+
+This library comes with optional default styles. Follow the instructions below to include them in your app.
+
+Read the [docs section](#Docs) for instructions on styling the combobox yourself.
+
+#### Default
+
+This approach works for all setups. Simply add the stylesheet to your layout (this would go in your document's `<head>`):
 
 ```erb
 <%= combobox_style_tag %>
 ```
 
-Or require the styles with the asset pipeline in `app/assets/stylesheets/application.css`:
+This helper accepts any of the options you can pass to `stylesheet_link_tag`.
+
+#### Sprockets
+
+Require the styles in `app/assets/stylesheets/application.css`:
 
 ```erb
 *= require hotwire_combobox
 ```
 
-Only apps that use importmaps are currently supported. Support for other JS solutions is in progress.
-
 ## Docs
 
 Visit [the docs site](https://hotwirecombobox.com/) for a demo and detailed documentation.