feat: Add upgrade command and additionalEntrypoints setting (#116)

BREAKING CHANGE: vite_asset_path now requires an explicit path relative to the sourceCodeDir for nested directories. Example: vite_asset_path 'entrypoints/images/logo.png' BREAKING CHANGE: sourceCodeDir is now the Vite.js root BREAKING CHANGE: Manifest names are now relative to the sourceCodeDir to prevent collisions
ElMassimo · Aug 16, 2021 · 0850af2 · 0850af2
1 parent ce548ac
commit 0850af2
Show file tree

Hide file tree

Showing 117 changed files with 4,502 additions and 3,986 deletions.
diff --git a/.rubocop.yml b/.rubocop.yml
@@ -13,6 +13,7 @@ AllCops:
     - "examples/**/*"
     - "vendor/bundle"
     - "tmp/**/*"
+    - "test/mounted_app/test/dummy/bin/*"
   TargetRubyVersion: 2.5
 
 Style/IfUnlessModifier:

diff --git a/.rubocop_todo.yml b/.rubocop_todo.yml
@@ -1,12 +1,12 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2020-11-05 13:38:45 UTC using RuboCop version 0.86.0.
+# on 2021-08-16 18:41:25 UTC using RuboCop version 1.13.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 2
+# Offense count: 40
 # Cop supports --auto-correct.
 # Configuration parameters: AutoCorrect, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
 # URISchemes: http, https

diff --git a/Gemfile b/Gemfile
@@ -6,6 +6,7 @@ gem 'rails'
 
 gemspec path: './vite_ruby'
 gemspec path: './vite_rails'
+gemspec path: './vite_plugin_legacy'
 
 group :development, :test do
   gem 'benchmark-ips'

diff --git a/Gemfile.lock b/Gemfile.lock
@@ -1,14 +1,20 @@
+PATH
+  remote: vite_plugin_legacy
+  specs:
+    vite_plugin_legacy (3.0.0.beta.1)
+      vite_ruby (~> 3.0.0.beta.1)
+
 PATH
   remote: vite_rails
   specs:
-    vite_rails (2.0.13)
+    vite_rails (3.0.0.beta.2)
       railties (>= 5.1, < 8)
-      vite_ruby (~> 1.0)
+      vite_ruby (~> 3.0.0.beta.1)
 
 PATH
   remote: vite_ruby
   specs:
-    vite_ruby (1.2.20)
+    vite_ruby (3.0.0.beta.3)
       dry-cli (~> 0.7.0)
       rack-proxy (~> 0.6, >= 0.6.1)
       zeitwerk (~> 2.2)
@@ -81,7 +87,7 @@ GEM
     builder (3.2.4)
     byebug (11.1.3)
     coderay (1.1.3)
-    concurrent-ruby (1.1.8)
+    concurrent-ruby (1.1.9)
     crass (1.0.6)
     docile (1.3.5)
     dry-cli (0.7.0)
@@ -91,7 +97,7 @@ GEM
     i18n (1.8.10)
       concurrent-ruby (~> 1.0)
     json (2.5.1)
-    loofah (2.9.1)
+    loofah (2.12.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     m (1.5.1)
@@ -102,7 +108,7 @@ GEM
     marcel (1.0.1)
     method_source (1.0.0)
     mini_mime (1.0.3)
-    mini_portile2 (2.5.0)
+    mini_portile2 (2.6.1)
     minitest (5.14.4)
     minitest-reporters (1.4.3)
       ansi
@@ -111,8 +117,8 @@ GEM
       ruby-progressbar
     minitest-stub_any_instance (1.0.2)
     nio4r (2.5.7)
-    nokogiri (1.11.3)
-      mini_portile2 (~> 2.5.0)
+    nokogiri (1.12.3)
+      mini_portile2 (~> 2.6.1)
       racc (~> 1.4)
     parallel (1.20.1)
     parser (3.0.1.0)
@@ -156,7 +162,7 @@ GEM
       rake (>= 0.8.7)
       thor (~> 1.0)
     rainbow (3.0.0)
-    rake (13.0.3)
+    rake (13.0.6)
     regexp_parser (2.1.1)
     rexml (3.2.5)
     rubocop (1.13.0)
@@ -215,6 +221,7 @@ DEPENDENCIES
   rubocop-performance (~> 1.9)
   simplecov (< 0.18)
   spring (~> 2.1)
+  vite_plugin_legacy!
   vite_rails!
   vite_ruby!
 

diff --git a/bin/snapshot b/bin/snapshot
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -e
+
+cd vite-plugin-ruby
+
+pnpm install
+pnpm build
+pnpm example:build
+
+rm -Rf ../test/test_app/public/vite-production
+cp -R example/public/vite ../test/test_app/public/vite-production
diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -80,6 +80,7 @@ module.exports = {
             { text: 'Deployment', link: '/guide/deployment' },
             { text: 'Migration', link: '/guide/migration' },
             { text: 'Plugins', link: '/guide/plugins' },
+            { text: 'Advanced', link: '/guide/advanced' },
           ],
         },
         {

diff --git a/docs/config/index.md b/docs/config/index.md
@@ -5,7 +5,9 @@
 [json config]: /config/#shared-configuration-file-%F0%9F%93%84
 [sourceCodeDir]: /config/#sourcecodedir
 [autoBuild]: /config/#autobuild
+[entrypointsDir]: /config/#entrypointsDir
 [publicOutputDir]: /config/#publicoutputdir
+[additionalEntrypoints]: /config/#additionalentrypoints
 [watchAdditionalPaths]: /config/#watchadditionalpaths
 [publicDir]: /config/#publicdir
 [root]: /config/#root
@@ -14,6 +16,8 @@
 [import aliases]: /guide/development.html#import-aliases-👉
 [reference these files]: https://github.com/ElMassimo/vite_ruby/blob/main/vite-plugin-ruby/example/app/frontend/entrypoints/main.ts#L4
 [resolve.alias]: https://vitejs.dev/config/#resolve-alias
+[tag helpers]: /guide/development.html#tag-helpers-🏷
+[vite-plugin-ruby]: https://github.com/ElMassimo/vite_ruby/tree/main/vite-plugin-ruby
 
 # Configuring Vite Ruby
 
@@ -182,6 +186,26 @@ You can customize this behavior using the following options.
 
 ## Other Options
 
+### additionalEntrypoints
+
+- **Version Added:** `3.0.0`
+- **Default:** `["~/{assets,fonts,icons,images}/**/*"]`
+
+  Specify additional [entrypoints], which can be referenced using [tag helpers]
+  without having to place them inside <kbd>[entrypointsDir]</kbd>.
+
+  `~/` is an alias for the <kbd>[sourceCodeDir]</kbd>, `["~/images/**/*"]`:
+
+  ```ruby
+  vite_asset_path 'images/logo.svg' # app/frontend/images/logo.svg
+  ```
+
+  Otherwise, globs are relative to <kbd>[root]</kbd>, such as `["app/components/**/*.js"]`.
+
+  ```ruby
+  vite_asset_path '/app/components/header.js' # leading slash is required
+  ```
+
 ### assetHost
 
 - **Default:** `Rails.application.config.action_controller.asset_host`
@@ -221,6 +245,21 @@ You can customize this behavior using the following options.
 
   Specify the project root.
 
+### skipCompatibilityCheck
+
+- **Version Added:** `3.0.0`
+- **Default:** `false`
+- **Env Var:** `VITE_RUBY_SKIP_COMPATIBILITY_CHECK`
+
+  The version of <kbd>[vite-plugin-ruby]</kbd> is checked on initialization to
+  fail early if an incompatible version is suspected, as it could lead to
+  hard-to-debug errors such as missing entrypoints in the build.
+
+  Running <kbd>bin/vite upgrade</kbd> will install a compatible
+  version, which should resolve this error.
+
+  Otherwise, this setting allows to skip that check. Use it responsibly.
+
 ### viteBinPath
 
 - **Default:** `node_modules/.bin/vite`
@@ -236,7 +275,7 @@ You can customize this behavior using the following options.
 
   You may provide globs such as `["app/components/**/*"]`, paths should be relative to <kbd>[root]</kbd>.
 
-  The <kbd>[sourceCodeDir]</kbd> is included by default.
+  The <kbd>[sourceCodeDir]</kbd> and any <kbd>[additionalEntrypoints]</kbd> are included by default.
 
   <hr/>
 

diff --git a/docs/guide/advanced.md b/docs/guide/advanced.md
@@ -0,0 +1,78 @@
+[tag helpers]: /guide/rails.html#tag-helpers-%F0%9F%8F%B7
+[additionalEntrypoints]: /config/#additionalentrypoints
+[entrypointsDir]: /config/#entrypointsdir
+[sourceCodeDir]: /config/#sourcecodedir
+[watchAdditionalPaths]: /config/#watchadditionalpaths
+[entrypoints]: /guide/development.html#entrypoints-⤵%EF%B8%8F
+[tag helpers]: /guide/development.html#tag-helpers-🏷
+[CLI Command]: /guide/development.html#cli-commands-⌨%EF%B8%8F
+[vite-plugin-ruby]: https://github.com/ElMassimo/vite_ruby/tree/main/vite-plugin-ruby
+[config.json]: /config/#shared-configuration-file-📄
+[sidecar assets]: https://viewcomponent.org/guide/sidecar_assets.html
+[viewcomponent]: https://viewcomponent.org/
+[glob imports]: https://vitejs.dev/guide/features.html#glob-import
+
+# Advanced Usage
+
+This section discusses settings that most projects don't need to configure
+explicitly.
+
+## Additional Entrypoints
+
+The <kbd>[additionalEntrypoints]</kbd> setting added in `3.0.0` allows you to
+configure additional entries that are located outside the <kbd>[entrypointsDir]</kbd>.
+
+By default, it's configured to: `["~/{assets,fonts,icons,images}/**/*"]`, which
+enables bundling and referencing these files with [tag helpers]:
+
+```ruby
+vite_asset_path 'images/logo.svg' # app/frontend/images/logo.svg
+```
+
+If you would like to opt out from bundling these files, [configure it][config.json] as:
+
+```json
+    "additionalEntrypoints": []
+```
+
+## Bundling files outside sourceCodeDir
+
+When using a library such as [`ViewComponent`][viewcomponent], it can be
+convenient to group JS and CSS files within each component folder, which is called [sidecar assets].
+
+There are a few options to achieve this, each with their pros and cons.
+
+:::tip Required
+Make sure to add `app/components/**/*` to <kbd>[watchAdditionalPaths]</kbd>, to
+ensure the build is triggered when any of the component files changes.
+:::
+
+### Import every component
+
+The simplest option is to leverage [glob imports] to import all components in a
+single entrypoint, which is suitable for cases where there are few components,
+or when all components should be registered in all pages.
+
+```js
+// app/frontend/entrypoints/application.js
+import.meta.globEager('../../components/**/*_component.js')
+```
+
+Any files imported from each `.js` file will be bundled as well.
+
+### One entrypoint per component
+
+To bundle each component independently, configure <kbd>[additionalEntrypoints]</kbd>:
+
+```json
+    "additionalEntrypoints": [
+      "app/components/**/*_component.{js,ts}",
+      "~/{assets,fonts,icons,images}/**/*"
+    ]
+```
+
+and then reference them as needed in views or partials:
+
+```erb
+<%= vite_javascript_tag '/app/components/comment_component' %>
+```
diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md
@@ -79,6 +79,14 @@ The following rake tasks are available:
 You can provide `RACK_ENV=production` to simulate a production build locally.
 :::
 
+## Disabling extension of the `assets:precompile` task
+
+During complex migrations, it might be convenient that `vite:build` is not run
+along the `assets:precompile` rake task.
+
+You can disable the extension of the `assets:precompile` rake task by setting
+the `VITE_RUBY_SKIP_ASSETS_PRECOMPILE_EXTENSION` to `true`.
+
 ## Compressing Assets 📦
 
 Most CDN and edge service providers will automatically serve compressed assets,

diff --git a/docs/guide/development.md b/docs/guide/development.md
@@ -12,6 +12,7 @@
 [json config]: /config/#shared-configuration-file-%F0%9F%93%84
 [vite config]: /config/#configuring-vite-%E2%9A%A1
 [sourceCodeDir]: /config/#sourcecodedir
+[additionalEntrypoints]: /config/#additionalentrypoints
 [autoBuild]: /config/#autobuild
 [entrypoints]: https://vitejs.dev/guide/build.html#multi-page-app
 [vite_client_tag]: https://github.com/ElMassimo/vite_ruby/blob/main/lib/vite_rails/helper.rb#L13-L17
@@ -24,6 +25,7 @@
 [watchAdditionalPaths]: /config/#watchadditionalpaths
 [aliased]: https://github.com/rollup/plugins/tree/master/packages/alias
 [jekyll-vite]: https://jekyll-vite.netlify.app/posts/tag-helpers/
+[Advanced Usage]: /guide/advanced
 
 # Developing with Vite
 
@@ -60,11 +62,14 @@ will be considered [entries][entrypoints] to your application (SPAs or pages).
 </pre>
 </div>
 
-These files will be automatically detected and passed on to Vite, all [configuration][entrypoints] is done
-for you.
+These files will be automatically detected and passed on to Vite, all [configuration][entrypoints] is done for you.
 
 You can add them to your HTML layouts or views using the provided [tag helpers].
 
+:::tip New in v3
+<kbd>[additionalEntrypoints]</kbd> allows to configure entrypoints. See _[Advanced Usage]_.
+:::
+
 ## Import Aliases 👉
 
 For convenience, `~/` and `@/` are [aliased] to your <kbd>[sourceCodeDir]</kbd>,
@@ -106,6 +111,9 @@ For information about the CLI options run <kbd>bin/vite <b>command</b> --help</k
 - <kbd>bin/vite build</kbd>:
   Makes a production bundle with Vite using Rollup behind the scenes
 
+- <kbd>bin/vite upgrade</kbd>:
+  Updates Vite Ruby gems and npm packages to compatible versions
+
 - <kbd>bin/vite info</kbd>:
   Provide information on _Vite Ruby_ and related libraries
 

diff --git a/docs/guide/hanami.md b/docs/guide/hanami.md
@@ -56,6 +56,14 @@ For other types of assets, you can use <kbd>[vite_asset_path][helpers]</kbd> and
 <link rel="prefetch" href="<%= vite_asset_path 'typography.css' %>" />
 ```
 
+All helpers resolve names to the <kbd>[entrypointsDir]</kbd>
+unless the path includes a directory:
+
+```ruby
+vite_asset_path 'logo.svg'        # app/frontend/entrypoints/logo.svg
+vite_asset_path 'images/logo.svg' # app/frontend/images/logo.svg
+```
+
 ### Enabling Hot Module Reload 🔥
 
 Use the following helpers to enable HMR in development: