diff --git a/README.md b/README.md index 7a318d8..13ca52e 100644 --- a/README.md +++ b/README.md @@ -11,14 +11,14 @@ ## Quickstart -Within your Ruby or Rails project, no Bun or anything like that required: +Starting with your Ruby or Rails project, no Bun or anything like that required: ```sh bundle add bundlebun rake bun:install ``` -and then +and then: ```sh > bin/bun ... @@ -32,20 +32,20 @@ Usage: bun [...flags] [...args] **Modern frontend setup is needlessly complex** and may involve a lot of maintenance. Developers need _at the very least_ a JavaScript runtime (typically, Node.js), a package manager (could be npm, yarn, or pnpm), and a build tool (Vite, Webpack, esbuild, Parcel—dozens of them). -- One way forward is to dockerize development environments, creating unnecessary headaches for the development team—both frontend and backend engineers, especially if the team is not that large and the project is not that complex. -- Another is to declare front-ops bankruptcy and pursue the "no-build" route. +- One way forward is to dockerize development environments, creating unnecessary headaches for the development team—both frontend and backend engineers (especially if the team is not that large and the project is not that complex). +- Another approach is to declare front-ops bankruptcy and pursue the "no-build" route. -**What if we can simplify?** **Bun** is a **JavaScript runtime**, optimized for speed and developer experience. Bun is _also_ a fast JavaScript **package manager**. Bun is _also_ a **build tool**. Bun is also distributed as a single executable file. +**What if we could simplify this?** **Bun** is a **JavaScript runtime**, optimized for speed and developer experience. Bun is _also_ a fast JavaScript **package manager**. Bun is _also_ a **build tool**. Bun is also distributed as a single executable file. -But Bun still requires [some installation](https://bun.sh/docs/installation), and we need to ensure everyone in the team uses the same version. +However, Bun still requires [some installation](https://bun.sh/docs/installation), and we need to make sure everyone on the team is using the same version. -How about we just pack it into a Ruby gem as a binary and allow developers to stay updated—every time a new Bun version is out—or freeze their desired version within their Ruby project. There are no setups, large READMEs with instructions, and no enforcing the Docker workflow. +So, how about we just pack it into a Ruby gem as a binary and allow developers to stay updated? Then, we'll be ready every time a new Bun version is out—or the user can freeze their desired version within their Ruby project. There are no setups, large READMEs with instructions, and no enforcing the Docker workflow. -**Meet bundlebun**. With fast JavaScript runtime and a package manager included you can even skip on the build tool and use Bun itself. +**Enter bundlebun**. With a fast JavaScript runtime and a package manager included, you can even skip the build tool and use Bun itself. ## Install -bundlebun gem releases include a binary distribution of Bun for each supported Bun platform (macOS, Linux, Windows) and architectures. +bundlebun gem releases include a binary distribution of Bun for each supported Bun platform (macOS, Linux, Windows) and architecture. First, add it to your `Gemfile`: @@ -53,20 +53,20 @@ First, add it to your `Gemfile`: gem "bundlebun" ``` -and +and: ```sh bundle install ``` -or just +(or just): ```sh bundle add bundlebun ``` -If you are seeing a message like `Could not find gems matching 'bundlebun' valid for all resolution platforms -(aarch64-linux, aarch64-linux-gnu <...> )`, this may be [a known issue with Bundler/`Gemfile.lock`](https://www.google.com/search?client=firefox-b-d&q=Could+not+find+gems+matching+all+resolution+platforms) you can fix. Open `Gemfile.lock` in your text editor, find a section called `PLATFORMS`, and alter a list of platforms you need to support. This can be a good default for most if you're targeting Linux and macOS (for Windows, also leave entries with `x64_mingw`): +If you're seeing a message like `Could not find gems matching 'bundlebun' valid for all resolution platforms +(aarch64-linux, aarch64-linux-gnu <...> )`, this may be [a known issue with Bundler/`Gemfile.lock`](https://www.google.com/search?client=firefox-b-d&q=Could+not+find+gems+matching+all+resolution+platforms) which you can fix. Open `Gemfile.lock` in your text editor, find a section called `PLATFORMS`, and alter a list of platforms you need to support. This can be a good default for most if you're targeting Linux and macOS (for Windows, also leave entries with `x64_mingw`): ``` (rest of the file here) @@ -82,17 +82,17 @@ PLATFORMS ... and try `bundle install` again. -Next, run +Next, run: ```sh rake bun:install ``` -The task will install a binstub (`bin/bun`) that you can use to run Bun commands: try running `bin/bun` or `bin/bun --version`. +The task will install a binstub (`bin/bun`) that you can use to run Bun commands; try running `bin/bun` or `bin/bun --version`. You should use `bin/bun` in your scripts, including your local runners like `Procfile.dev` or `Procfile`, and `package.json`—if you had a call to `node` or `bun` in the `scripts` section there. -Next, the Rake task will try to detect the integrations we need to install based on the classes and modules Rake can see in your project. We'll follow with integrations: +Next, the Rake task will try to detect the integrations we need to install based on the classes and modules Rake can see in your project. We'll continue with integrations. ### Integrations @@ -104,9 +104,9 @@ Alternatively, you can ensure an integration is loaded and the necessary modules [cssbundling](https://github.com/rails/cssbundling-rails) and [jsbundling](https://github.com/rails/jsbundling-rails) are Rails gems that support the traditional CSS and JS building pipeline for Ruby on Rails. -Be sure to check both gems on documentation for bootstrapping your frontend build pipeline, as bundlebun supports them instead of duplicating approaches. cssbundling, for instance, includes an excellent sample build configuration for Bun. +Be sure to check both gems for documentation on bootstrapping your frontend build pipeline (as bundlebun supports them) instead of duplicating approaches. cssbundling, for instance, includes an excellent sample build configuration for Bun. -To quote their READMEs, try +To quote their READMEs, try this for cssbundling: ```sh bundle add cssbundling-rails @@ -114,65 +114,59 @@ bin/rails css:install:[tailwind|bootstrap|bulma|postcss|sass] bin/rails css:build ``` -For cssbundling, and +and this jsbundling: ```sh bundle add jsbundling-rails bin/rails javascript:install:bun ``` -for jsbundling. - To install the bundlebun integration, run ```sh rake bun:install:rails ``` -The task ensures a `bin/bun` binstub and installs an initializer/task of sorts to ensure both build-related gems use our bundled version of Bun. +The task makes sure a `bin/bun` binstub exists and installs an initializer/task of sorts to ensure both build-related gems use our bundled version of Bun. -Alternatively, you can call +Alternatively, you can call the following in one of your project's rakefiles: ```ruby Bundlebun::Integrations::Cssbundling.bun! Bundlebun::Integrations::Jsbundling.bun! ``` -in one of your project's rakefiles. - #### vite-ruby and vite-rails [vite-ruby](https://github.com/ElMassimo/vite_ruby) and [vite-rails](https://vite-ruby.netlify.app/) are gems that make Ruby and Rails integration with [Vite](https://vite.dev/), a great JavaScript build tool and platform, seamless and easy. -The bundlebun integration would be installed automatically, or you can run +The bundlebun integration would be installed automatically, or you can run: ```sh rake bun:install:vite ``` -That will ensure that you have a `bin/bun` binstub. +That will make sure you have a `bin/bun` binstub. Next, we'll install a custom `bin/vite` binstub (otherwise, ruby-vite won't be able to sense bundlebun presence); the original file, if present, would be backed up to `bin/vite-backup`. -Finally, we'll put an initializer that forces vite-ruby to use bundlebun. Alternatively, you can call +Finally, we'll put an initializer that forces vite-ruby to use bundlebun. Alternatively, you can call this yourself: ```ruby Bundlebun::Integrations::ViteRuby.bun! ``` -yourself. - #### ExecJS -[ExecJS](https://github.com/rails/execjs) runs JavaScript code straight from Ruby. For that, it supports a bunch of runtimes it could launch—and get a result. The Bun runtime already exists for ExecJS, and we just need to ensure it uses the bundled one. +[ExecJS](https://github.com/rails/execjs) runs JavaScript code straight from Ruby. To do so, it supports a bunch of runtimes it can launch—and get a result. The Bun runtime already exists for ExecJS; we just need to ensure it uses the bundled one. -The bundlebun integration would be installed automatically, or you can run +The bundlebun integration can be installed automatically, or you can run: ```sh rake bun:install:execjs ``` -That would create an initializer that would redefine the Bun runtime for ExecJS and force its usage to be the default. Alternatively, you can call +This will create an initializer to redefine the Bun runtime for ExecJS and force its usage to be default. Alternatively, you can call: ```ruby Bundlebun::Integrations::ExecJS.bun! @@ -184,13 +178,13 @@ bundlebun is designed to be used with Bundler: installed in specific projects, a If you install the gem globally, you _won't see the `bun` executable_ as a wrapper for a Ruby-bundled Bun runtime; instead, it would be called `bundlebun`. -This is done to avoid possible conflicts in your `$PATH` if you have an independent Bun runtime installed: if the directory with Ruby gem-generated binstubs is in your `$PATH` before the directory with your Bun runtime, running `bun` will launch the bundlebun's version, causing a lot of confusion. And that is why bundlebun is _not_ greedy with the `bun` executable name. If you wish to run Bun runtime globally using this gem, a simple symlink or a wrapper script will do, but the gem won't act destructively. +This naming discrepency is to avoid possible conflicts in your `$PATH` if you have an independent Bun runtime installed: if the directory with Ruby gem-generated binstubs is in your `$PATH` before the directory with your Bun runtime, running `bun` will launch the bundlebun's version, causing a lot of confusion. And that is why bundlebun is _not_ greedy with the `bun` executable name. If you wish to run Bun runtime globally using this gem, a simple symlink or a wrapper script will do, but the gem won't act destructively. ## Usage ### Binstub -The easiest way to interact with bundled Bun is via the binstub at `bin/bun`. It will launch the bundled version of Bun with the arguments provided: +The easiest way to interact with bundled Bun is via the binstub at `bin/bun`; it will launch the bundled version of Bun with the arguments provided: ```sh > bin/bun @@ -203,7 +197,7 @@ Usage: bun [...flags] [...args] ### Return codes -Note that with this or any other option to run Bun, bundlebun will return the error code `127` if the executable is not found. +Note that with this (or any other option to run Bun), bundlebun will return the error code `127` if the executable is not found. ### Rake @@ -230,7 +224,7 @@ Bundlebun.call("outdated") # => `bun outdated` Bundlebun.call(["add", "postcss"]) # => `bun add postcss` ``` -Check out the [API documentation](https://rubydoc.info/gems/bundlebun) for `Bundlebun::Runner` for helper methods. Some of the most useful ones: +Check out the [API documentation](https://rubydoc.info/gems/bundlebun) on `Bundlebun::Runner` for helper methods. Some of the most useful ones: - `Bundlebun::Runner.binary_path`: returns the full path to the bundled Bun library. - `Bundlebun::Runner.binary_path_exist?`: checks if that binary even exists. @@ -239,13 +233,9 @@ Check out the [API documentation](https://rubydoc.info/gems/bundlebun) for `Bund ## Versioning -bundlebun uses the `#{bundlebun.version}.#{bun.version}` versioning scheme. - -Meaning: gem bundlebun version `0.1.0.1.1.38` is a distribution that includes a gem with its own code version `0.1.0` and a Bun runtime with version `1.1.38`. - -bundlebun is supposed to automatically push new gem versions when there is a new Bun release. +bundlebun uses the `#{bundlebun.version}.#{bun.version}` versioning scheme. Meaning: gem bundlebun version `0.1.0.1.1.38` is a distribution that includes a gem with its own code version `0.1.0` and a Bun runtime with version `1.1.38`. -You can lock the exact version number in your `Gemfile`, or leave the version unspecified and update it as you wish. +bundlebun is designed to automatically push new gem versions when there is a new Bun release. That said, you can lock the exact version number in your `Gemfile`, or leave the version unspecified and update it as you wish. ## Uninstall @@ -255,7 +245,7 @@ To uninstall, remove the gem: bundle remove bundlebun ``` -Or remove it from your `Gemfile`. +Or remove it from your `Gemfile` and run bundler. Next, remove the integrations you have in place: @@ -277,7 +267,7 @@ Big thanks to Jason Meller [@terracatta](https://github.com/terracatta) for his ## Contributing -Make sure you have up-to-date Ruby. Run `bin/setup`: that would install the nesessary gems, install [lefthook](https://github.com/evilmartians/lefthook) and run `rake bundlebun:download` to fetch a local version of Bun for tests. +Make sure you have up-to-date Ruby. Run `bin/setup` to install the nesessary gems, install [lefthook](https://github.com/evilmartians/lefthook) and run `rake bundlebun:download` to fetch a local version of Bun for tests. `rake rspec` to check if all tests pass.