Skip to content

Commit

Permalink
Update installation-importmaps.html.erb
Browse files Browse the repository at this point in the history
  • Loading branch information
Sebastian Scholl authored Dec 24, 2023
1 parent 79bd787 commit 4f1b179
Showing 1 changed file with 38 additions and 28 deletions.
66 changes: 38 additions & 28 deletions app/content/pages/frameworks/rails/setup/installation-importmaps.html.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,28 +9,33 @@ framework: rails
<%= render Page::ContributeComponent.new(file: current_page.asset.path.path) %>
<% end %>

Hotwire is configured by default using import maps in the latest version of Rails 7+. This guide acknowledges and details the various files, gems, and configurations that allow this setup to work out of the box.
In Rails 7+, Hotwire is configured by default using import maps. This guide will walk you through the files, gems, and configurations essential for this setup, ensuring a smooth integration right out of the box.

## Getting Started
## Setup

Run the `rails new` command to create a fresh rails project. Once installed, open the Gemfile. Several gems are used to bundle all the required dependencies for the import maps + Hotwire setup. They are:
## 1. Creating a New Rails Project:

```rb
# Use JavaScript with ESM import maps [https://github.com/rails/importmap-rails]
gem "importmap-rails"
Begin by running the `rails new` command to generate a fresh Rails project. Once installed, delve into the Gemfile. This file includes several gems crucial for bundling the necessary dependencies for an import maps and Hotwire configuration. They include:

# Hotwire's SPA-like page accelerator [https://turbo.hotwired.dev]
gem "turbo-rails"
```rb
# Use JavaScript with ESM import maps
# [https://github.com/rails/importmap-rails]
gem "importmap-rails"

# Hotwire's modest JavaScript framework [https://stimulus.hotwired.dev]
gem "stimulus-rails"
```
# Hotwire's SPA-like page accelerator
# [https://turbo.hotwired.dev]
gem "turbo-rails"

After successfully running `bundle install`, run `rails importmap:install` to add the required configurations and files to your project.
# Hotwire's modest JavaScript framework
# [https://stimulus.hotwired.dev]
gem "stimulus-rails"
```

```sh
After executing `bundle install`, run `rails importmap:install` to integrate the required configurations and files into your project.

```sh
$ rails importmap:install
apply /path_to/gems/importmap-rails-1.2.3/lib/install/install.rb
apply /path_to/gems/importmap-rails-1.2.3/lib/install/install.rb
Add Importmap include tags in application layout
insert app/views/layouts/application.html.erb
Create application.js module as entrypoint
Expand All @@ -45,42 +50,47 @@ $ rails importmap:install
Copying binstub
create bin/importmap
run bundle install
```
```

## `javascript_importmap_tags`
## 2. `javascript_importmap_tags`

The install command will automatically update your `application.html.erb` file with an `<%= javascript_importmap_tags %>` ERB tag. The `<script>` tags that this helper generates and inserts into your page `<head>` are influenced by the configurations set in the `config/importmap.rb`.
The installation command will automatically modify your `application.html.erb` file by adding the `<%= javascript_importmap_tags %>` ERB tag. The `<script>` tags inserted in your page header will correspond to the configurations in `config/importmap.rb`.

## Pinning Imports
## 3. Pinning Imports

Conceptually speaking, your import map in rails can be thought of as servering a similar purpose to a `package.json` file in an NPM package. It's where you declare (or "pin") the local and remote dependencies to be bundled into accessible JS modules for your app. This is the role of the `config/importmap.rb` file.
Think of your import map in Rails as analogous to a `package.json` file in an NPM package. It's where you declare (or "pin") your app's local and remote JS module dependencies. Use `config/importmap.rb` for this purpose.

Pins can be added manually or using the `bin/importmap pin DEP_NAME` command. For example, pinning the `lodash` library to your import map can be done using:
Pins can be added manually or with the `bin/importmap pin DEP_NAME` command. For instance, to pin the `lodash` library:

```sh
$ bin/importmap pin lodash
Pinning "lodash" to https://ga.jspm.io/npm:lodash@4.17.21/lodash.js
```

Which updates the `config/importmap.rb` file to with:
This command updates `config/importmap.rb`:

```rb
pin "lodash", to: "https://ga.jspm.io/npm:lodash@4.17.21/lodash.js"
```

Conversly, you can remove a pin by deleting its entry in the `config/importmap.rb` file or by running `bin/importmap unpin DEP_NAME`. After removing a pin, make sure to restart your development server.
To remove a pin, either delete its entry in `config/importmap.rb` or use `bin/importmap unpin DEP_NAME`. Remember to restart your development server after any changes.

## Importing modules

After pinning an module, you're able to import it into your `app/javascript/application.js` file.
## 4. Importing Pins
Post-pinning, you can import a module into `app/javascript/application.js` or other scripts:

```js
// Configure your import map in config/importmap.rb. Read more: https://github.com/rails/importmap-rails
import _ from 'lodash';
```

## 5. Importing Turbo
Finally, import Turbo into your `app/javascript/application.js`:

_.doSomethingWithLodash
```js
import "@hotwired/turbo-rails"
```

This makes the Turbo instance globally accessible via `window.Turbo`.

## Conclusion

This is the basic
This guide provides a basic overview of setting up import maps in Rails 7. Each component discussed offers its own set of configurable options, allowing you to tailor the setup to your application's specific needs.

0 comments on commit 4f1b179

Please sign in to comment.