bun_bun_bundle 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c51a065b214293e85467dfdd10f2c84bf763f65fe27d0b549b175ea7448563bf
-  data.tar.gz: f2d86b5d3650797b617fa3ecee6d3dac119d97850749bc830172bfa12cb83dfe
+  metadata.gz: 11c05e743bc0de032fa96e01847eab10641fecb9cf59151b62f14fdfb4b8384f
+  data.tar.gz: 3d6f0044f6c3afcbb38dcc847ac2250eec8616c5a09bf51c7022468fff86e766
 SHA512:
-  metadata.gz: c87530160b4f6829e32f7fc82c4f0d9180aa13b03089011fdb237d8daa4973453bd9cd074bd0402736f7fcab49e7d40c98f9b7fbb1a094aa07f718cd94ca9ac4
-  data.tar.gz: 0cbad61b7eff7af29f38cab146f09941a8f3dbd9354a1c470d36a35f94bbb36484543f7a06ef27e4810f2a1f51becb00026c7206de30e6b0049334cd224127fd
+  metadata.gz: 9063a677cbb30db62e3162e7c0b753dd1f34b3b36ecc1c076efeba45ad3d3d09b7dac00ca575c6159cd0ea9ea13066963a053a7d2928501b9ebc879e4eecb52e
+  data.tar.gz: 8e9b0d27cb3f11dadfd88ac64deb1b52c54f20b63bb738d55dbb196d40b83049a1cb1285eb68ee379cc60cffbcb9f516d15864c74b9c2a05497c4fa1713f044c

data/README.md

@@ -1,9 +1,9 @@
-# BunBunBundle
+# Bun, Bun, Bundle
 
 A self-contained asset bundler for Ruby powered by [Bun](https://bun.sh). No
-development dependencies, no complex configuration. Fast builds with CSS
-hot-reloading, fingerprinting, live reload, and a flexible plugin system. Works
-with Rails, Hanami, or any Rack app.
+development dependencies, no complex configuration. Lightning fast builds with
+CSS hot-reloading, fingerprinting, live reload, and a flexible plugin system.
+Works with Rails, Hanami, or any Rack app.
 
 ## Why use BunBunBundle?
 
@@ -28,18 +28,18 @@ browsers always fetch the right version.
 
 Development and production builds go through the exact same pipeline. The only
 differences are fingerprinting and minification being enabled in production,
-but nothing is holding you back form them in development as well.
+but nothing is holding you back from enabling them in development as well.
 
 ### Extensible plugin system
 
-Comes with built-in plugins for CSS glob imports, root aliases, and JS glob
-imports. Plugins are simple, plain JS files, so you can create your own JS/CSS
-transformers, and raw Bun plugins are supported as well.
+BunBunBundle comes with built-in plugins for root aliases, CSS glob imports,
+and JS glob imports. Plugins are simple, plain JS files, so you can create your
+own JS/CSS transformers, and raw Bun plugins are supported as well.
 
 ### Just one dependency: Bun
 
-The bundler ships with the gem. Bun is the only external requirement, so there
-are zero dev dependencies.
+The bundler ships with the gem. Bun is the only external requirement, so other
+than that, there are no dev dependencies.
 
 ## Installation
 
@@ -59,6 +59,18 @@ are zero dev dependencies.
 
 ## Usage with Rails
 
+BunBunBundle completely bypasses the Rails asset pipeline. If you're adding it
+to an existing app, you can remove Sprockets/Propshaft:
+
+- Remove `gem 'sprockets-rails'` or `gem 'propshaft'` from your `Gemfile`
+- Delete `config/initializers/assets.rb` if present
+
+For new apps, generate them without the asset pipeline:
+
+```sh
+rails new myapp --minimal --skip-asset-pipeline --skip-javascript
+```
+
 The gem auto-configures itself through a Railtie. All helpers are available in
 your views immediately:
 
@@ -81,7 +93,13 @@ stale asset caching.
 
 ## Usage with Hanami
 
-1. Require the Hanami integration:
+Hanami ships with its own esbuild-based asset pipeline. Since BunBunBundle
+replaces it entirely, you can clean up the default setup:
+
+- Remove `gem 'hanami-assets'` from your `Gemfile`
+- Delete `config/assets.js`, `package.json`, and `node_modules/`
+
+1. Set up the Hanami integration:
 
    ```ruby
    # config/app.rb
@@ -90,12 +108,15 @@ stale asset caching.
 
    module MyApp
      class App < Hanami::App
-       BunBunBundle.setup(root: root)
-       config.middleware.use BunBunBundle::DevCacheMiddleware if Hanami.env?(:development)
+       BunBunBundle.setup(root: root, hanami: config)
      end
    end
    ```
 
+   This loads the manifest, and in development automatically registers the
+   cache-busting middleware and configures the CSP to allow the live reload
+   script and WebSocket connection.
+
 2. Include the helpers in your views:
 
    ```ruby
@@ -111,7 +132,7 @@ stale asset caching.
    end
    ```
 
-4. Use them in your templates:
+3. Use them in your templates:
 
    ```erb
    <%= bun_css_tag('css/app.css') %>
@@ -132,7 +153,8 @@ BunBunBundle.asset_host = 'https://cdn.example.com'
 
 ## Helpers
 
-All helpers are prefixed with `bun_` to avoid conflicts with framework helpers:
+All helpers are prefixed with `bun_` to avoid conflicts with existing framework
+helpers:
 
 | Helper                           | Description                                      |
 | -------------------------------- | ------------------------------------------------ |
@@ -185,46 +207,144 @@ Place a `config/bun.json` in your project root:
     "secure": false
   },
   "plugins": {
-    "css": ["cssAliases", "cssGlobs"],
-    "js": ["jsGlobs"]
+    "css": ["aliases", "cssGlobs"],
+    "js": ["aliases", "jsGlobs"]
   }
 }
 ```
 
-All values shown above are defaults, you only need to specify what you want to
+All values shown above are defaults. You only need to specify what you want to
 override.
 
 ## Plugins
 
-Three plugins are included out of the box:
+Three plugins are included out of the box.
+
+### `aliases`
+
+Resolves `$/` root aliases to absolute paths in both CSS and JS files. This
+lets you reference assets and modules from the project root without worrying
+about relative paths.
+
+In CSS:
+
+```css
+@import '$/app/assets/css/reset.css';
+
+.logo {
+  background: url('$/app/assets/images/logo.png');
+}
+```
+
+In JS:
+
+```javascript
+import utils from '$/lib/utils.js'
+```
+
+All `$/` references are resolved to your project root.
+
+### `cssGlobs`
+
+Expands glob patterns in CSS `@import` statements. Instead of manually listing
+every file, you can import an entire directory at once:
+
+```css
+@import './components/**/*.css';
+```
 
-| Plugin       | Description                                                      |
-| ------------ | ---------------------------------------------------------------- |
-| `cssAliases` | Resolves `$/` root aliases in CSS `url()` references             |
-| `cssGlobs`   | Expands glob patterns in `@import` statements                    |
-| `jsGlobs`    | Compiles `import x from 'glob:./path/*.js'` into object mappings |
+This will be expanded into individual `@import` lines for each matching file,
+sorted alphabetically.
+
+> [!NOTE]
+> A warning is logged if the pattern matches no files.
+
+### `jsGlobs`
+
+Compiles glob imports into an object that maps file paths to their default
+exports. Use the special `glob:` prefix in an import statement:
+
+```javascript
+import components from 'glob:./components/**/*.js'
+```
+
+This will generate individual imports and builds an object mapping. For
+example:
+
+```javascript
+import _glob_components_theme from './components/theme.js'
+import _glob_components_shared_tooltip from './components/shared/tooltip.js'
+const components = {
+  'components/theme': _glob_components_theme,
+  'components/shared/tooltip': _glob_components_shared_tooltip
+}
+```
+
+> [!NOTE]
+> If no files match the pattern, an empty object is assigned.
 
 ### Custom plugins
 
-Create a JS file that exports a factory function:
+Custom plugins are JS files referenced by their path in the config. Each file
+must export a factory function that receives a context object with `root`
+(project root path) and `prod` (boolean indicating production mode). What the
+factory returns determines the plugin type.
+
+#### Simple transform plugins
+
+A simple transform plugin returns a function that receives the file content as
+a string and an `args` object with the file's `path`. It should return the
+transformed content. The transform can be synchronous or asynchronous.
+
+Transforms are chained in the order they appear in the config, so each
+transform receives the output of the previous one.
 
 ```javascript
 // config/bun/banner.js
 
-export default function banner({ prod }) {
-  return (content) => {
-    const stamp = prod ? "" : ` (dev build ${new Date().toISOString()})`;
-    return `/* My App${stamp} */\n${content}`;
-  };
+export default function banner({prod}) {
+  return content => {
+    const stamp = prod ? '' : ` (dev build ${new Date().toISOString()})`
+    return `/* My App${stamp} */\n${content}`
+  }
+}
+```
+
+#### Raw Bun plugins
+
+If the factory returns an object with a `setup` method instead of a function,
+it is treated as a raw
+[Bun plugin](https://bun.sh/docs/bundler/plugins). This gives you full access
+to Bun's plugin API, including `onLoad`, `onResolve`, and custom loaders.
+
+```javascript
+// config/bun/svg.js
+
+export default function svg() {
+  return {
+    name: 'svg-loader',
+    setup(build) {
+      build.onLoad({filter: /\.svg$/}, async args => {
+        const text = await Bun.file(args.path).text()
+        return {
+          contents: `export default ${JSON.stringify(text)}`,
+          loader: 'js'
+        }
+      })
+    }
+  }
 }
 ```
 
-Then reference it in your config:
+#### Registering custom plugins
+
+Reference custom plugins by their file path in your config:
 
 ```json
 {
   "plugins": {
-    "css": ["cssAliases", "cssGlobs", "config/bun/banner.js"]
+    "css": ["aliases", "cssGlobs", "config/bun/banner.js"],
+    "js": ["aliases", "jsGlobs", "config/bun/svg.js"]
   }
 }
 ```
@@ -252,8 +372,8 @@ your-app/
 
 BunBunBundle was originally built for [Fluck](https://fluck.site), a
 self-hostable website builder using [Lucky
-Framework](https://luckyframework.org/). I wanted to have a fast, comprehensive
-asset bundler that would not require too much maintenance in the long term.
+Framework](https://luckyframework.org/). I wanted to have a fast and modern
+asset bundler that would require minimal maintenance in the long term.
 
 Bun was the natural choice because it does almost everything:
 
@@ -265,10 +385,10 @@ Bun was the natural choice because it does almost everything:
 - Extendability with simple plugins
 
 It's also fast and reliable. We use this setup heavily in two Lucky apps and it
-is rock solid, and it has since been adopted by Lucky as the default builder.
+is rock solid. It has since been adopted by Lucky as the default builder.
 
-I wanted to have the same setup in my Ruby apps as well, that's when this Gem
-was born. I hope you enjoy it too!
+This Gem was born because I wanted to have the same setup in my Ruby apps as
+well. I hope you enjoy it too!
 
 ## Contributing
 

data/lib/bun/bun_bundle.js

@@ -42,7 +42,7 @@ export default {
   loadConfig() {
     const defaults = {
       entryPoints: {js: ['app/assets/js/app.js'], css: ['app/assets/css/app.css']},
-      plugins: {css: ['cssAliases', 'cssGlobs'], js: ['jsGlobs']},
+      plugins: {css: ['aliases', 'cssGlobs'], js: ['aliases', 'jsGlobs']},
       staticDirs: ['app/assets/images', 'app/assets/fonts'],
       outDir: 'public/assets',
       publicPath: '/assets',

data/lib/bun/plugins/aliases.js

@@ -0,0 +1,9 @@
+const REGEX = /(url\(\s*['"]?|(?<!\w)['"])\$\//g
+
+// Resolves `$/` root aliases in CSS url() references and JS/CSS imports.
+// e.g. url('$/app/assets/images/foo.png') → url('/absolute/root/app/assets/images/foo.png')
+//      import x from '$/lib/utils.js' → import x from '/absolute/root/lib/utils.js'
+//      @import '$/app/assets/css/reset.css' → @import '/absolute/root/app/assets/css/reset.css'
+export default function aliases({root}) {
+  return content => content.replace(REGEX, `$1${root}/`)
+}

data/lib/bun/plugins/index.js

@@ -1,9 +1,9 @@
 import {join} from 'path'
-import cssAliases from './cssAliases.js'
+import aliases from './aliases.js'
 import cssGlobs from './cssGlobs.js'
 import jsGlobs from './jsGlobs.js'
 
-const builtins = {cssAliases, cssGlobs, jsGlobs}
+const builtins = {aliases, cssGlobs, jsGlobs}
 const TYPE_REGEXES = {
   css: /\.css$/,
   js: /\.(js|ts|jsx|tsx)$/

data/lib/bun_bun_bundle/hanami.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'bun_bun_bundle'
+
 module BunBunBundle
   # Hanami integration for BunBunBundle.
   #
@@ -9,8 +11,7 @@ module BunBunBundle
   #
   #   module MyApp
   #     class App < Hanami::App
-  #       BunBunBundle.setup(root: root)
-  #       config.middleware.use BunBunBundle::DevCacheMiddleware if Hanami.env?(:development)
+  #       BunBunBundle.setup(root: root, hanami: config)
   #     end
   #   end
   #

data/lib/bun_bun_bundle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BunBunBundle
-  VERSION = '0.1.2'
+  VERSION = '0.3.0'
 end

data/lib/bun_bun_bundle.rb

@@ -38,10 +38,15 @@ module BunBunBundle
 
     # Loads config and manifest. Call this from Hanami's config/app.rb or
     # any Rack app's startup.
-    def setup(root: Dir.pwd)
+    #
+    # Pass `hanami: config` from within a Hanami::App class body to
+    # automatically register middleware and configure CSP for development.
+    def setup(root: Dir.pwd, hanami: nil)
       self.config = Config.load(root: root.to_s)
       options = development? ? {} : { retries: 1, delay: 0 }
       self.manifest = Manifest.load(root: root.to_s, **options)
+
+      configure_hanami(hanami) if hanami
     end
 
     # Returns the path to the bundled JS files shipped with the gem.
@@ -56,6 +61,16 @@ module BunBunBundle
       @asset_host = nil
       @environment = nil
     end
+
+    private
+
+    def configure_hanami(hanami_config)
+      return unless development?
+
+      hanami_config.middleware.use DevCacheMiddleware
+      hanami_config.actions.content_security_policy[:script_src] += " 'unsafe-inline'"
+      hanami_config.actions.content_security_policy[:connect_src] += " #{config.dev_server.ws_url}"
+    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bun_bun_bundle
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Wout Fierens
@@ -36,7 +36,7 @@ files:
 - exe/bun_bun_bundle
 - lib/bun/bake.js
 - lib/bun/bun_bundle.js
-- lib/bun/plugins/cssAliases.js
+- lib/bun/plugins/aliases.js
 - lib/bun/plugins/cssGlobs.js
 - lib/bun/plugins/index.js
 - lib/bun/plugins/jsGlobs.js

data/lib/bun/plugins/cssAliases.js

@@ -1,10 +0,0 @@
-import {join} from 'path'
-
-const REGEX = /url\(\s*['"]?\$\//g
-
-// Resolves `$` root aliases in CSS url() references.
-// e.g. url('$/images/foo.png') → url('/absolute/src/images/foo.png')
-export default function cssAliases({root}) {
-  const srcDir = join(root, 'src')
-  return content => content.replace(REGEX, `url('${srcDir}/`)
-}