# Hanami 2 assets (esbuild)

**URL:** <https://discourse.hanakai.org/t/hanami-2-assets-esbuild/683>\
**Category:** proposals\
**Created:** [February 25, 2022, 3:44pm UTC](https://discourse.hanakai.org/t/hanami-2-assets-esbuild/683 "2022-02-25T15:44:03Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![jodosha](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.hanakai.org/jodosha/32/710_2.png) [@jodosha](https://discourse.hanakai.org/u/jodosha)\
**Post date:** [February 25, 2022, 3:44pm UTC](https://discourse.hanakai.org/t/hanami-2-assets-esbuild/683/1 "2022-02-25T15:44:03Z")

</div>

# Hanami Assets 2.0 (esbuild)

**👉 This is a proposal to make Hanami 2.0 work with `esbuild` and to imagine how the integration would look like. This is NOT a decision to go with `esbuild`, we’re evaluating other options like Webpack or Vite. 👈**

## General principles

- Don’t build a single bundle for the entire app (e.g. `app.{js,css}` ) **[BREAKING]**
- Bundle entry points: **[NEW FEATURE]**
  - Default entry points are `index.{js,ts,jsx,tsx}` of each slice
    - Example: `slices/main/assets/index.tsx`

  - Convention: each `index.*` file is an entry point, that will generate its own bundle
    - Example: `slices/main/assets/login/index.tsx`

- Minify assets **[1.0 FEATURE]**
- Source maps **[NEW FEATURE]**
- Remove pre-processors **[BREAKING]**
  - Don’t allow Ruby to interpolate values in assets
  - Example: Don’t support `foo.js.erb` anymore

- Remove `compile` mode **[BREAKING]** [V1.3: Overview | Hanami Guides](https://guides.hanamirb.org/v1.3/assets/overview/#compile-mode)
  - No longer necessary

- Use `esbuild` **[NEW FEATURE]**
- View helpers: **[1.0 FEATURE, BREAKING Ruby API]**[V1.3: Assets | Hanami Guides](https://guides.hanamirb.org/v1.3/helpers/assets/)
  - `assets["index.js"]` resolve an asset Path/URL for the current slice
    - Example:
      - Relative path: `/main/assets/index.js`
      - File path: `[app-root]/public/main/assets/index.js`

  - `assets.javascript(“index.js”)` generates a `<script>` tag
    - aliased as `assets.js()`

  - `assets.stylesheet` generates a `<link>` tag.
    - aliased as `assets.css()`

  - `assets.image("logo.png")` generates an `<img>` tag
  - `assets.favicon(“favicon.ico”)` generates a `<link>` tag
  - Other helpers:
    - `assets.video`
    - `assets.audio`
    - `assets.path` (forces relative path)
    - `assets.url` (forces absolute path)

- Fingerprint mode: **[1.0 FEATURE]** [V1.3: Overview | Hanami Guides](https://guides.hanamirb.org/v1.3/assets/overview/#fingerprint-mode)
  - Use a JSON manifest to resolve helpers path (e.g. `assets.javascript(“index.js”)`) to real path (e.g. `/main/assets/index-abc123.js` , where `abc123` is the file hashing)

- Subresource Integrity **[1.0 FEATURE]** [V1.3: Content Delivery Network (CDN) | Hanami Guides](https://guides.hanamirb.org/v1.3/assets/content-delivery-network/#subresource-integrity)
- CDN: **[1.0 FEATURE]** [V1.3: Content Delivery Network (CDN) | Hanami Guides](https://guides.hanamirb.org/v1.3/assets/content-delivery-network/#content-delivery-network-cdn)
  - Configure a CDN base URL. Example: Assuming `base_url = "https://123.cloudfront.net"`, `assets.javascript(“index.js”)` will be resolved as `"https://123.cloudfront.net/main/assets/index.js"`
  - When working in combination with Fingerprint mode the above URL would be resolved as `"https://123.cloudfront.net/main/assets/index-abc123.js"`

* * *

## Environments

### Development

- Watch the source directories (`slices/assets/**/*`) and output in `public`
- Use a Rack middleware to statically serve those assets **[1.0 FEATURE]**

### Test (and CI)

- Before test suite precompile the assets in `public` directory
- Use a Rack middleware to statically serve those assets **[1.0 FEATURE]**

### Production

- Precompile assets at deploy time in `public` directory **[1.0 FEATURE]**
  - Write a JSON manifest **[1.0 FEATURE]**

- Use NGINX or CDN to statically serve assets **[1.0 FEATURE]**

* * *

## CLI

- `bundle exec hanami assets precompile`**[1.0 FEATURE]** [V1.3: Assets | Hanami Guides](https://guides.hanamirb.org/v1.3/command-line/assets/#precompile)
  - Precompile assets for test/production
  - Aliased as `bundle exec rake assets:precompile` [V1.3: Rake Tasks | Hanami Guides](https://guides.hanamirb.org/v1.3/projects/rake/#ruby-server-hosting-ecosystem-compatibility)

- `bundle exec hanami assets watch` **[NEW FEATURE]**
  - For development purposes only