bun_bun_bundle 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74f92b0b7b6bf9ae9cba639bcd548cf447e89ac55d14a121b55926677a75658b
-  data.tar.gz: d50ffe4d0477df3390702c9ee1c7797a63e4d3ab32cd4e885db340f12516973f
+  metadata.gz: 11c05e743bc0de032fa96e01847eab10641fecb9cf59151b62f14fdfb4b8384f
+  data.tar.gz: 3d6f0044f6c3afcbb38dcc847ac2250eec8616c5a09bf51c7022468fff86e766
 SHA512:
-  metadata.gz: 1b34424077d7ffb800d89c0a1790278524a5c1ea2640c38eefd5f9c6a4c2f7c7fa6e42a06ee08a4082889cb9f524b0ae7594e0da5914d9e29d7d19085c79e194
-  data.tar.gz: c7d5c0f4b24c2025c12ad3f1c33a7933f8806bc13a3a0f7e1f6d3b2c3b31fd048237ad5dbb1b07b3686f2d1e196808ddbb99fc08ae9e7552f01826bb211c7eaf
+  metadata.gz: 9063a677cbb30db62e3162e7c0b753dd1f34b3b36ecc1c076efeba45ad3d3d09b7dac00ca575c6159cd0ea9ea13066963a053a7d2928501b9ebc879e4eecb52e
+  data.tar.gz: 8e9b0d27cb3f11dadfd88ac64deb1b52c54f20b63bb738d55dbb196d40b83049a1cb1285eb68ee379cc60cffbcb9f516d15864c74b9c2a05497c4fa1713f044c

data/README.md

@@ -32,7 +32,7 @@ but nothing is holding you back from enabling them in development as well.
 
 ### Extensible plugin system
 
-BunBunBundle comes with built-in plugins for CSS glob imports, root aliases,
+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.
 
@@ -207,8 +207,8 @@ Place a `config/bun.json` in your project root:
     "secure": false
   },
   "plugins": {
-    "css": ["cssAliases", "cssGlobs"],
-    "js": ["jsGlobs"]
+    "css": ["aliases", "cssGlobs"],
+    "js": ["aliases", "jsGlobs"]
   }
 }
 ```
@@ -218,35 +218,133 @@ override.
 
 ## Plugins
 
-Three plugins are included out of the box:
+Three plugins are included out of the box.
 
-| 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 |
+### `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';
+```
+
+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"]
   }
 }
 ```

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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bun_bun_bundle
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  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}/`)
-}