From cca490b4aabefb1e8cb15ceaa87f60a7928597c3 Mon Sep 17 00:00:00 2001
From: "Kit (OpenClaw)" <kit@openclaw.ai>
Date: Wed, 4 Mar 2026 19:07:49 -0500
Subject: [PATCH] WA-RAILS7-019: Document Webpacker removal strategy

---
 docs/rails7-migration-patterns/README.md      |  10 +
 .../jsbundling-rails-esbuild.md               | 113 +++++++++++
 .../webpacker-to-sprockets-4.md               | 176 ++++++++++++++++++
 docs/source/articles/create-a-new-app.html.md |   2 +-
 docs/source/articles/create-a-plugin.html.md  |   2 +-
 plugin_template.rb                            |   2 +-
 6 files changed, 302 insertions(+), 3 deletions(-)
 create mode 100644 docs/rails7-migration-patterns/README.md
 create mode 100644 docs/rails7-migration-patterns/jsbundling-rails-esbuild.md
 create mode 100644 docs/rails7-migration-patterns/webpacker-to-sprockets-4.md

diff --git a/docs/rails7-migration-patterns/README.md b/docs/rails7-migration-patterns/README.md
new file mode 100644
index 0000000000..37d62a0722
--- /dev/null
+++ b/docs/rails7-migration-patterns/README.md
@@ -0,0 +1,10 @@
+# Rails 7 Migration Patterns
+
+This directory contains **opinionated, field-tested patterns** for upgrading Workarea applications to Rails 7.
+
+These documents are primarily for downstream Workarea client applications.
+
+## Patterns
+
+- **[Webpacker → Sprockets 4](./webpacker-to-sprockets-4.md)** (recommended default)
+- **[Optional: jsbundling-rails (esbuild) + Sprockets](./jsbundling-rails-esbuild.md)** (for apps that need modern JS tooling)
diff --git a/docs/rails7-migration-patterns/jsbundling-rails-esbuild.md b/docs/rails7-migration-patterns/jsbundling-rails-esbuild.md
new file mode 100644
index 0000000000..c4fea029b8
--- /dev/null
+++ b/docs/rails7-migration-patterns/jsbundling-rails-esbuild.md
@@ -0,0 +1,113 @@
+# Optional: jsbundling-rails (esbuild) + Sprockets (WA-RAILS7-019)
+
+Some Workarea host applications used Webpacker because they needed modern JS tooling:
+
+- ES modules (`import`/`export`)
+- npm packages
+- TypeScript
+- React/Vue/Svelte toolchains
+- tree-shaking / minification / code splitting
+
+For those applications, a pragmatic Rails 7 path is:
+
+- **Sprockets 4** for Workarea engine assets + images/fonts + (optionally) CSS
+- **jsbundling-rails + esbuild** for application-specific JavaScript bundling
+
+This keeps the Workarea engines on the asset pipeline while giving the host app a modern
+bundler.
+
+---
+
+## High-level approach
+
+1. Add `jsbundling-rails` and choose `esbuild`.
+2. Output the built bundle(s) into `app/assets/builds`.
+3. Have Sprockets serve those compiled outputs by linking `app/assets/builds` in the
+   Sprockets manifest.
+
+---
+
+## Setup steps (host application)
+
+### 1) Add the gem
+
+```ruby
+# Gemfile
+gem 'jsbundling-rails'
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+### 2) Install jsbundling-rails for esbuild
+
+```bash
+bin/rails javascript:install:esbuild
+```
+
+This typically:
+
+- adds `esbuild` to `package.json`
+- adds build scripts
+- creates `app/javascript/application.js`
+- configures output into `app/assets/builds`
+
+### 3) Link builds in the Sprockets manifest
+
+Ensure your host app has `app/assets/config/manifest.js` and that it links the builds
+directory:
+
+```js
+// app/assets/config/manifest.js
+//= link_tree ../images
+//= link_tree ../builds
+
+//= link application.css
+
+// Workarea engine entrypoints
+//= link workarea-admin
+//= link workarea-storefront
+```
+
+### 4) Use Sprockets tags that point at the built output
+
+When using jsbundling-rails, you typically include the compiled output (which Sprockets
+now knows about via `link_tree ../builds`).
+
+```erb
+<%= javascript_include_tag 'application', 'data-turbo-track': 'reload' %>
+```
+
+Note: depending on the installer and your scripts, the compiled file may be named
+`application.js` (served from `app/assets/builds/application.js`).
+
+### 5) Ensure build runs in CI / production
+
+In production deploys, you need both:
+
+- `yarn build` (or `npm run build`)
+- `bin/rails assets:precompile`
+
+Many Rails deployments wire this automatically, but if your pipeline previously relied
+on Webpacker’s compilation step, you may need to add a build step explicitly.
+
+---
+
+## Notes for Workarea apps
+
+- Workarea’s admin/storefront JS is still Sprockets-managed.
+- Your host app’s custom JS can be bundled and delivered via `app/assets/builds`.
+- If you also want modern CSS tooling, consider `cssbundling-rails` similarly, but keep
+  the surface area small during the Rails 7 upgrade.
+
+---
+
+## When *not* to use this
+
+If your JS customizations are relatively small and don’t require npm/transpilation,
+prefer the simpler **Sprockets-only** approach:
+
+- [`Webpacker → Sprockets 4`](./webpacker-to-sprockets-4.md)
diff --git a/docs/rails7-migration-patterns/webpacker-to-sprockets-4.md b/docs/rails7-migration-patterns/webpacker-to-sprockets-4.md
new file mode 100644
index 0000000000..9d216e73ef
--- /dev/null
+++ b/docs/rails7-migration-patterns/webpacker-to-sprockets-4.md
@@ -0,0 +1,176 @@
+# Webpacker → Sprockets 4 (WA-RAILS7-019)
+
+Rails 7 removed Webpacker from the default stack. Workarea’s Rails 7 upgrade path uses
+**Sprockets 4** (see the Sprockets 4 work that landed in PR #740).
+
+This guide documents a practical migration path for **host applications** that historically
+used Webpacker alongside Workarea.
+
+---
+
+## Summary / Recommendation
+
+For most Workarea storefronts and admin customizations:
+
+- Keep using the **asset pipeline (Sprockets 4)**
+- Remove Webpacker
+- Move your `app/javascript/packs/*` entrypoints into Sprockets-managed assets
+
+If your application relies on modern JS bundling features (ESM, tree-shaking, TypeScript,
+React/Vue build chains, etc.), see the optional guide:
+
+- [`jsbundling-rails` (esbuild) + Sprockets](./jsbundling-rails-esbuild.md)
+
+---
+
+## Audit (core/admin/storefront)
+
+As of this change, `core/`, `admin/`, and `storefront/` do **not** reference Webpacker.
+Any remaining Webpacker references are limited to documentation and templates.
+
+---
+
+## Migration Steps
+
+### 1) Remove Webpacker from the host app
+
+In your host application:
+
+1. Remove the gem:
+
+   ```ruby
+   # Gemfile
+   # gem 'webpacker'
+   ```
+
+2. Remove Webpacker config and bins (if present):
+
+   ```
+   config/webpacker.yml
+   config/webpack/*
+   bin/webpack
+   bin/webpack-dev-server
+   ```
+
+3. Remove the pack output directory (common paths):
+
+   ```
+   public/packs
+   public/packs-test
+   ```
+
+4. If you were using `javascript_pack_tag` / `stylesheet_pack_tag`, you’ll replace those in a later step.
+
+### 2) Ensure Sprockets 4 manifest exists
+
+Sprockets 4 expects an explicit manifest file.
+
+In the host application, add `app/assets/config/manifest.js` if it doesn’t already exist:
+
+```js
+// app/assets/config/manifest.js
+//= link_tree ../images
+//= link application.css
+//= link application.js
+
+// Workarea engine entrypoints
+//= link workarea-admin
+//= link workarea-storefront
+```
+
+Notes:
+
+- If your app has additional entrypoints, add them here (see step 4).
+- Workarea engines provide their own manifests; the host manifest is still the place
+  where you declare what the host app compiles.
+
+### 3) Replace Webpacker tags in layouts/views
+
+Replace pack helper tags with Sprockets tags.
+
+Typical Webpacker usage:
+
+```erb
+<%= javascript_pack_tag 'application', 'data-turbo-track': 'reload' %>
+<%= stylesheet_pack_tag 'application', 'data-turbo-track': 'reload' %>
+```
+
+Becomes:
+
+```erb
+<%= javascript_include_tag 'application', 'data-turbo-track': 'reload' %>
+<%= stylesheet_link_tag 'application', 'data-turbo-track': 'reload' %>
+```
+
+If you referenced multiple packs, those typically become additional Sprockets entrypoints
+(e.g. `checkout.js`, `account.js`, etc.) that you link via `javascript_include_tag`.
+
+### 4) Move `packs/` entrypoints into Sprockets entrypoints
+
+Webpacker conventionally uses `app/javascript/packs/*.js` as entry files.
+
+For Sprockets, the conventional location is `app/assets/javascripts/`.
+
+Example mapping:
+
+- `app/javascript/packs/application.js` → `app/assets/javascripts/application.js`
+- `app/javascript/packs/application.scss` → `app/assets/stylesheets/application.scss`
+
+If you had multiple pack entrypoints, create corresponding Sprockets files:
+
+- `app/javascript/packs/checkout.js` → `app/assets/javascripts/checkout.js`
+
+And link them in `app/assets/config/manifest.js`:
+
+```js
+//= link checkout.js
+```
+
+### 5) Update import / require style
+
+Sprockets does not handle ESM imports the same way Webpacker did.
+
+Common changes:
+
+- Replace `import ... from ...` (Webpacker) with Sprockets directives when using
+  classic asset-pipeline libraries:
+
+  ```js
+  //= require jquery
+  //= require workarea/storefront
+  ```
+
+- If you need modern `import` semantics (ESM, NPM packages, transpilation), strongly
+  consider using `jsbundling-rails` (see the optional guide).
+
+### 6) Add additional assets to precompile (if needed)
+
+If you add new top-level assets that aren’t linked in `manifest.js`, you may need to
+add them to `config/initializers/assets.rb`:
+
+```ruby
+Rails.application.config.assets.precompile += %w[
+  checkout.js
+  checkout.css
+]
+```
+
+Prefer the manifest approach in Sprockets 4 where possible.
+
+### 7) Verify locally and in CI
+
+- `bin/rails assets:clobber`
+- `bin/rails assets:precompile`
+- Boot the app and verify:
+  - Storefront loads and behaves normally
+  - Admin loads and behaves normally
+  - No missing asset errors in logs
+
+---
+
+## Common pitfalls
+
+- **Missing `manifest.js`**: Sprockets 4 will not behave like Sprockets 3 without it.
+- **Assuming ESM works in Sprockets**: it generally won’t; use a bundler if you need it.
+- **Forgetting Workarea entrypoints**: ensure `workarea-admin` and `workarea-storefront`
+  are linked (typically via the host manifest).
diff --git a/docs/source/articles/create-a-new-app.html.md b/docs/source/articles/create-a-new-app.html.md
index 1c77f57171..fbbaa19f84 100644
--- a/docs/source/articles/create-a-new-app.html.md
+++ b/docs/source/articles/create-a-new-app.html.md
@@ -57,7 +57,7 @@ bundle exec rails new ./ --force \
 --skip-bootsnap \
 --skip-yarn \
 --skip-bundle \
---skip-webpack-install
+--skip-javascript
 ```
 
 ## Add the Workarea gem
diff --git a/docs/source/articles/create-a-plugin.html.md b/docs/source/articles/create-a-plugin.html.md
index b4bc979785..7b4d75bca8 100644
--- a/docs/source/articles/create-a-plugin.html.md
+++ b/docs/source/articles/create-a-plugin.html.md
@@ -20,7 +20,7 @@ rails plugin new path/to/my_plugin \
   --skip-turbolinks \
   --skip-bootsnap \
   --skip-yarn \
-  --skip-webpack-install
+  --skip-javascript
 ```
 
 This template can be found in the [workarea repository](https://github.com/workarea-commerce/workarea) at [https://github.com/workarea-commerce/workarea/blob/master/plugin_template.rb](https://github.com/workarea-commerce/workarea/blob/master/plugin_template.rb).
diff --git a/plugin_template.rb b/plugin_template.rb
index 99dbc0ec02..4fe3e3cc91 100644
--- a/plugin_template.rb
+++ b/plugin_template.rb
@@ -12,7 +12,7 @@
   --skip-turbolinks \
   --skip-bootsnap \
   --skip-yarn \
-  --skip-webpack-install
+  --skip-javascript
 =end
 
 #