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?
answer
- the hand-off folder between bundler and Propshaft
- package.json build script writes there
- git-ignored except .keep
- javascript_include_tag with type: "module"
- javascript:build runs before precompile
basics
~20 sapp/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 sjsbundling-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{
"name": "app",
"private": true,
"scripts": {
"build": "esbuild app/javascript/*.* --bundle --sourcemap --format=esm --outdir=app/assets/builds --public-path=/assets"
},
"devDependencies": {
"esbuild": "*"
}
}go deeper
Recall that the bundler writes into app/assets/builds, Propshaft serves from there, and the folder is git-ignored apart from .keep.
Trace a TypeScript entry point from the package.json build script to the digested file the layout tag resolves, in development and at precompile.
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.
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