skip to content

Front-End Asset Builds

How Rails serves CSS, JavaScript and images: Propshaft digests and copies files, import maps load ES modules with no build, and bundling gems run a JS or CSS build. Interviewers probe the trade-offs.

part ofRuby on Railsread it →
on this pageshow

explore

questions

15

In a Rails 8.1 app using jsbundling-rails, what is app/assets/builds for, and how does a TypeScript entry point end up served to the browser?

level: juniorimportance: must knowfreq 55%

answer

  1. the hand-off folder between bundler and Propshaft
  2. package.json build script writes there
  3. git-ignored except .keep
  4. javascript_include_tag with type: "module"
  5. javascript:build runs before precompile

basics

~20 s

app/assets/builds is the hand-off folder: the package.json build script that jsbundling-rails installs writes bundled files there, and Propshaft serves them like any other asset because every app/assets subfolder is on its load path. The folder holds build output only and is git-ignored.

solid answer

~30 s

jsbundling-rails does not bundle anything itself. Its installer (`bin/rails javascript:install:esbuild`, or `rails new -j esbuild`) creates `app/assets/builds` with a `.keep`, git-ignores everything else in it, adds a `build` script to `package.json` and puts `javascript_include_tag "application", "data-turbo-track": "reload", type: "module"` in the layout. The esbuild script is `esbuild app/javascript/*.* --bundle --sourcemap --format=esm --outdir=app/assets/builds --public-path=/assets`, so an `app/javascript/application.ts` entry point compiles to `app/assets/builds/application.js`. Because `builds` sits under `app/assets`, Propshaft has it on its load path and serves the logical path `application.js`, digested in production. In development a watcher rewrites the file on every change; for deploys, `javascript:build` runs as a prerequisite of `assets:precompile`.

code

json · 10 lines
json
{
  "name": "app",
  "private": true,
  "scripts": {
    "build": "esbuild app/javascript/*.* --bundle --sourcemap --format=esm --outdir=app/assets/builds --public-path=/assets"
  },
  "devDependencies": {
    "esbuild": "*"
  }
}

go deeper

for a junior

Recall that the bundler writes into app/assets/builds, Propshaft serves from there, and the folder is git-ignored apart from .keep.

for a middle

Trace a TypeScript entry point from the package.json build script to the digested file the layout tag resolves, in development and at precompile.

for a senior

Explain why only build output is on the load path, how fresh clones and CI get their builds, and how this differs from serving sources with import maps.

for a principal

Frame app/assets/builds as the contract that keeps the bundler replaceable: any tool that writes files there works with the same pipeline.

## The division of labour Rails 8.1 keeps two jobs apart: - A **bundler** (esbuild, Bun, rollup or webpack) turns source files — TypeScript, JSX, npm packages — into browser-ready files. - **Propshaft** finds files on its load path, digests their names and serves them. **jsbundling-rails** is the thin layer between them. It installs a bundler configuration, picks the package manager, and wires Rake tasks so the bundler runs at the right times. The meeting point is one folder: **`app/assets/builds`**. ## What the installer sets up Running `bin/rails javascript:install:esbuild` (which `rails new -j esbuild` does for you) applies a template that: 1. Creates `app/assets/builds` with a `.keep` file. 2. Appends `/app/assets/builds/*`, `!/app/assets/builds/.keep` and `/node_modules` to `.gitignore`. 3. Inserts `<%= javascript_include_tag "application", "data-turbo-track": "reload", type: "module" %>` before `</head>` in the layout. 4. Creates `app/javascript/application.js` if it is missing, and a minimal `package.json`. 5. Copies a `bin/dev` that starts foreman, and writes `Procfile.dev` with a `js: yarn build --watch` line. 6. Adds esbuild as a dev dependency and a `build` script to `package.json`. The other installers (`javascript:install:bun`, `:rollup`, `:webpack`) follow the same pattern with their own config file: `bun.config.js`, `rollup.config.js` or `webpack.config.js`. ## How a TypeScript entry point flows through For the property-management team that wants TypeScript, the default esbuild script already does most of the work: ``` esbuild app/javascript/*.* --bundle --sourcemap --format=esm --outdir=app/assets/builds --public-path=/assets ``` - `app/javascript/*.*` makes **every file directly inside `app/javascript`** an entry point, so renaming `application.js` to `application.ts` keeps it an entry point. - The bundle is written to `app/assets/builds/application.js`, with a source map beside it. - `--public-path=/assets` makes any URLs esbuild writes point at the path Propshaft serves. From there the Rails side takes over: | Stage | What happens | |---|---| | Development | the watcher from `Procfile.dev` rebuilds `builds/application.js` on save; Propshaft serves it dynamically | | Layout | `javascript_include_tag "application", type: "module"` resolves the logical path `application.js` | | Production build | `assets:precompile` first runs `javascript:build`, then Propshaft copies and digests `builds/application.js` | | Browser | loads `/assets/application-<digest>.js` as one module script | Note that `app/javascript` itself is **not** on Propshaft's load path in a bundler app — only the output is served. (importmap-rails is what adds `app/javascript` to the path, because it serves sources directly.) ## Why the folder is git-ignored The files in `app/assets/builds` are **artefacts**: regenerated by the watcher in development, by `test:prepare` before tests and by `assets:precompile` before a deploy. Committing them would invite merge conflicts on minified output and stale bundles that do not match the source. The `.keep` file is the exception, so the folder exists in a fresh clone and Propshaft can add it to its load path at boot. ## The same folder for CSS cssbundling-rails, dartsass-rails and tailwindcss-rails use the same convention: their build writes `application.css` or `tailwind.css` into `app/assets/builds`. The Rails 8.1 layout's `stylesheet_link_tag :app` links every `.css` under `app/assets`, which includes those built files. ## Common misunderstandings - **"Propshaft runs esbuild."** It does not; the bundler runs through `yarn build` (or the Bun, pnpm or npm equivalent) and Propshaft only sees the result. - **"The browser loads application.ts."** It loads the compiled `application.js` from `builds`; the TypeScript source never leaves the server. - **"builds must be committed for production."** The deploy build regenerates it because `javascript:build` is a prerequisite of `assets:precompile`. ## Choosing among the four bundlers The installer you run decides the config file and the watch command, nothing else on the Rails side: - **esbuild** — no config file; options live in the `build` script. The default for most teams because it is fast and handles TypeScript and JSX out of the box. - **Bun** — `bun.config.js` and `bun run build --watch`; requires the Bun runtime on every machine and in the image. - **rollup** — `rollup.config.js`; fits library-style builds. - **webpack** — `webpack.config.js`; the familiar choice for teams arriving from Webpacker, which jsbundling-rails replaced. Whatever the choice, the Rails contract is identical: write files into `app/assets/builds`, expose a `build` script, and let `javascript:build` call it. Switching bundlers later therefore touches `package.json`, the bundler's config file and the `js:` line in `Procfile.dev`, while the layout tag, Propshaft and the deploy stay as they are.

  • A fresh clone renders a page that raises Propshaft::MissingAssetError for application.js. Why?
    `app/assets/builds` is git-ignored, so a fresh clone has no `application.js` until the bundler runs. `javascript_include_tag "application"` then cannot resolve the logical path. Run `bin/dev` (or `yarn build`) once; tests avoid it because `test:prepare` runs `javascript:build`.
  • Why does the esbuild script pass --public-path=/assets?
    Files esbuild emits besides the bundle, such as images or fonts loaded through a file loader, are referenced from the bundle by URL. `--public-path=/assets` makes those URLs start with the prefix Propshaft serves, so they resolve once the files are copied to `public/assets`.

  • Propshaft compiles the TypeScript in app/javascript when assets are precompiled
  • app/assets/builds should be committed so production has the bundle
  • jsbundling-rails bundles the JavaScript itself without Node or Bun
  • The layout should point javascript_include_tag at app/javascript/application.ts
  • The bundle is written to public/packs, as Webpacker did
open as a page

In a Rails 8.1 campsite-booking app on importmap-rails, what does bin/importmap pin flatpickr do to config/importmap.rb and vendor/javascript?

level: juniorimportance: must knowfreq 52%

basics

~20 s

bin/importmap pin asks the JSPM API to resolve the package and its dependencies, downloads each file into vendor/javascript, and writes a pin "flatpickr" # @version line into config/importmap.rb. At runtime the app serves those vendored files itself.

open as a page

In a Rails 8.1 app on importmap-rails, how do config/importmap.rb and javascript_importmap_tags let the browser run import statements with no Node build step?

level: juniorimportance: must knowfreq 58%

basics

~20 s

config/importmap.rb pins bare module names to files on the asset load path; javascript_importmap_tags renders those pins as a script type="importmap" block of digested URLs, adds modulepreload links and imports "application", so the browser resolves every import natively.

open as a page

In Rails 8.1, what does Propshaft do with the files on config.assets.paths, and which Sprockets jobs does it leave to other tools?

level: juniorimportance: must knowfreq 62%

basics

~20 s

Propshaft gathers every file on config.assets.paths under one logical namespace, serves them in development, and on assets:precompile copies all of them into public/assets with a content digest in each name. It does no transpiling, bundling or minifying.

open as a page

In a Rails 8.1 app with jsbundling-rails and dartsass-rails, what do bin/dev and Procfile.dev run, and what goes wrong if you start only bin/rails server?

level: middleimportance: must knowfreq 47%

basics

~10 s

bin/dev runs foreman on Procfile.dev: the Rails server plus yarn build --watch and bin/rails dartsass:watch. With only bin/rails server nothing rebuilds app/assets/builds, so edits never appear and a fresh clone has no built files.

open as a page

With Propshaft in Rails 8.1, how is a digested name like application-1a2b3c4d.css computed, and how do asset helpers find it through .manifest.json?

level: middleimportance: must knowfreq 48%

basics

~20 s

Propshaft hashes the file's content, the content of assets it references and config.assets.version with SHA1, keeps 8 hex characters and inserts them before the extension. Helpers translate logical paths through public/assets/.manifest.json when it exists, or compute digests live from the load path otherwise.

open as a page

In a Rails 8.1 app, when would you pick dartsass-rails, tailwindcss-rails or cssbundling-rails, and what does each need at build time?

level: middleimportance: should knowfreq 38%

basics

~20 s

dartsass-rails and tailwindcss-rails run standalone binaries shipped as gems, so they need no Node; cssbundling-rails runs a package.json build:css script through Node or Bun and supports Sass, Tailwind, PostCSS, Bootstrap and Bulma. Choose by whether the app already has a JavaScript toolchain.

open as a page

How do importmap-rails' bin/importmap outdated, audit and update keep vendored pins current, and what does update do with a package first pinned --from jsdelivr?

level: middleimportance: should knowfreq 28%

basics

~20 s

outdated compares each pin's # @version comment with the npm registry's latest, audit checks those versions against npm advisories, and both exit 1 on findings. update re-pins outdated packages but always resolves through JSPM, whatever --from was used originally.

open as a page

In importmap-rails, what does the preload: option on pin and pin_all_from control, what is its default, and when would you change it?

level: middleimportance: should knowfreq 36%

basics

~20 s

preload: decides whether javascript_importmap_tags emits a modulepreload link for a pin. It defaults to true, preloading every pin on every page; false defers a module until imported; an entry-point name preloads it only for that entry point.

open as a page

With Propshaft, why does url("croissant.jpg") in app/assets/stylesheets/menu/specials.css 404 when the image lives in app/assets/images, and how do you fix it?

level: middleimportance: should knowfreq 40%

basics

~20 s

Propshaft resolves a url() without a leading slash relative to the stylesheet's own logical folder, so it looks for menu/croissant.jpg, fails, logs a warning and leaves the URL undigested. Write url("/croissant.jpg"): a leading slash means the load-path root.

open as a page

Under Propshaft, why do CSS edits stop appearing in development after a local bin/rails assets:precompile, and how do assets:clobber and assets:clean differ?

level: middleimportance: should knowfreq 33%

basics

~20 s

Precompiling writes public/assets/.manifest.json, and while that file exists Propshaft resolves through it instead of the source files, so edits are ignored. assets:clobber deletes the whole output directory; assets:clean only prunes old digested versions, keeping the two newest of each asset by default plus anything under an hour old.

open as a page

How do jsbundling-rails, cssbundling-rails, dartsass-rails and tailwindcss-rails hook into bin/rails assets:precompile and test:prepare, and what do SKIP_JS_BUILD and SKIP_CSS_BUILD change?

level: seniorimportance: should knowfreq 32%

basics

~20 s

Each gem calls Rake's enhance to make its build task a prerequisite of assets:precompile and test:prepare, so the build runs first and a failure aborts the task. SKIP_JS_BUILD and SKIP_CSS_BUILD stop jsbundling, cssbundling and dartsass from attaching; tailwindcss-rails always attaches.

open as a page

When does importmap-rails stop fitting a Rails 8.1 app, for instance once the team wants TypeScript, JSX or packages that only ship CommonJS, and what signals tell you to switch to a bundler?

level: seniorimportance: should knowfreq 34%

basics

~20 s

importmap-rails serves files exactly as written, so it fits only code the browser can run directly: plain ES modules and packages with browser ESM builds. TypeScript, JSX, CommonJS-only packages, CSS imported from JavaScript or a need for tree-shaking point to jsbundling-rails.

open as a page

When moving a Rails 7 app from Sprockets to Propshaft ahead of Rails 8.1, what breaks, and what do you change in the Gemfile, config and stylesheets?

level: seniorimportance: should knowfreq 30%

basics

~10 s

Swap sprockets, sprockets-rails and sass-rails for propshaft, delete app/assets/config/manifest.js, rewrite image_url() calls in CSS as url('/...'), and move Sass, require-directive concatenation and minification to a build gem, because Propshaft only digests and serves files.

open as a page

In a Rails 8.1 app with jsbundling-rails (esbuild) and cssbundling-rails, the Sass theme intermittently vanishes after a TypeScript file starts importing a CSS file; why, and how do you fix it?

level: seniorimportance: nice to knowfreq 18%

basics

~20 s

When an esbuild entry point imports CSS, esbuild writes a CSS file named after that entry point, app/assets/builds/application.css, which is the same file cssbundling-rails' Sass build writes. The two builds overwrite each other; rename one output in package.json.

open as a page