diff --git a/Gemfile.lock b/Gemfile.lock
index 3bcb83aed..d6e428861 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -3,7 +3,7 @@ PATH
specs:
view_component (3.21.0)
activesupport (>= 5.2.0, < 8.1)
- concurrent-ruby (~> 1.0)
+ concurrent-ruby (= 1.3.4)
method_source (~> 1.0)
GEM
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 25475738c..6ae2a2a32 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -10,6 +10,10 @@ nav_order: 5
## main
+* Remove JS and CSS docs as they proved difficult to maintain and lacked consensus.
+
+ *Joel Hawksley*
+
* Do not prefix release tags with `v`, per recommendation from @bkuhlmann.
*Joel Hawksley*
diff --git a/docs/guide/javascript_and_css.md b/docs/guide/javascript_and_css.md
deleted file mode 100644
index 9ccb39a7d..000000000
--- a/docs/guide/javascript_and_css.md
+++ /dev/null
@@ -1,168 +0,0 @@
----
-layout: default
-title: JavaScript and CSS
-parent: How-to guide
----
-
-# JavaScript and CSS
-
-While ViewComponent doesn't provide any built-in tooling to do so, it’s possible to include JavaScript and CSS alongside components.
-
-To use the Webpacker gem to compile assets located in `app/components`:
-
-1. In `config/webpacker.yml`, add `"app/components"` to the `additional_paths` array (for example `additional_paths: ["app/components"]`).
-2. In the Webpack entry file (often `app/javascript/packs/application.js`), add an import statement to a helper file, and in the helper file, import the components' JavaScript:
-
-```js
-import "../components"
-```
-
-Then, in `app/javascript/components.js`, add:
-
-```js
-function importAll(r) {
- r.keys().forEach(r)
-}
-
-importAll(require.context("../components", true, /[_\/]component\.js$/))
-```
-
-Any file with the `_component.js` suffix (such as `app/components/widget_component.js`) will be compiled into the Webpack bundle. If that file itself imports another file, for example `app/components/widget_component.css`, it will also be compiled and bundled into Webpack's output stylesheet if Webpack is being used for styles.
-
-## Encapsulating assets
-
-Ideally, JavaScript and CSS should be scoped to the associated component.
-
-One approach is to use Web Components which contain all JavaScript functionality, internal markup, and styles within the shadow root of the Web Component.
-
-For example:
-
-```ruby
-# app/components/comment_component.rb
-class CommentComponent < ViewComponent::Base
- def initialize(comment:)
- @comment = comment
- end
-
- def commenter
- @comment.user
- end
-
- def commenter_name
- commenter.name
- end
-
- def avatar
- commenter.avatar_image_url
- end
-
- def formatted_body
- simple_format(@comment.body)
- end
-
- private
-
- attr_reader :comment
-end
-```
-
-```erb
-<%# app/components/comment_component.html.erb %>
-
-
-
-
- `
- }
-}
-customElements.define('my-comment', Comment)
-```
-
-## Stimulus
-
-In Stimulus, create a 1:1 mapping between a Stimulus controller and a component. To load in Stimulus controllers from the `app/components` tree, amend the Stimulus boot code in `app/javascript/controllers/index.js`:
-
-```js
-import { Application } from "stimulus"
-import { definitionsFromContext } from "stimulus/webpack-helpers"
-
-const application = Application.start()
-const context = require.context("controllers", true, /\.js$/)
-const contextComponents = require.context("../../components", true, /_controller\.js$/)
-application.load(
- definitionsFromContext(context).concat(
- definitionsFromContext(contextComponents)
- )
-)
-```
-
-This enables the creation of files such as `app/components/widget_controller.js`, where the controller identifier matches the `data-controller` attribute in the component's HTML template.
-
-After configuring Webpack to load Stimulus controller files from the `components` directory, add the path to `additional_paths` in `config/webpacker.yml`:
-
-```yml
- additional_paths: ["app/components"]
-```
-
-When placing a Stimulus controller inside a sidecar directory, be aware that when referencing the controller [each forward slash in a namespaced controller file’s path becomes two dashes in its identifier](
-https://stimulusjs.org/handbook/installing#controller-filenames-map-to-identifiers):
-
-```console
-app/components
-├── ...
-├── example
-| ├── component.rb
-| ├── component.css
-| ├── component.html.erb
-| └── component_controller.js
-├── ...
-```
-
-`component_controller.js`'s Stimulus identifier becomes: `example--component`:
-
-```erb
-