proscenium 0.26.0-x86_64-linux-gnu

data/README.md

@@ -0,0 +1,1020 @@
+# Proscenium - Integrated Frontend Development for Rails
+
+> 🗣️ prow · see · nee · uhm
+>
+> _noun_: **proscenium**
+>
+> - _the part of a theatre stage in front of the curtain._
+
+**_Proscenium_** treats your frontend and client-side code as first class citizens of your Rails app, and assumes a "fast by default" internet. It bundles and minifies JavaScript (+JSX), TypeScript (+TSX) and CSS in real time, on demand, and with zero configuration.
+
+**The highlights:**
+
+- Fast, real-time bundling, tree-shaking, code-splitting and minification of Javascript (.js,.jsx), Typescript (.ts,.tsx) and CSS (.css).
+- NO JavaScript runtime needed (eg. Node) - just the browser!
+- NO build step or pre-compilation.
+- NO additional process or server - Just run `rails server`!
+- Transforms newer JavaScript and CSS syntax to older syntax for older browsers.
+- Deep integration with Rails.
+- Automatically side-load JS and CSS for your layouts, views, and partials.
+- Import from NPM, URL's, and locally.
+- CSS Modules & mixins.
+- Source maps.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Installation](#installation)
+  - [Supported platforms](#supported-platforms)
+- [Client-Side Code Anywhere](#client-side-code-anywhere)
+- [Side Loading](#side-loading)
+- [Bundling](#bundling)
+  - [Import from NPM (`node_modules`)](#import-from-npm-node_modules)
+  - [RubyGem NPM dependencies](#rubygem-npm-dependencies)
+  - [Local Imports](#local-imports)
+  - [Unbundling](#unbundling)
+- [Source Maps](#source-maps)
+- [SVG](#svg)
+- [Environment Variables](#environment-variables)
+- [i18n](#i18n)
+- [JavaScript](#javascript)
+  - [Tree Shaking](#tree-shaking)
+  - [Code Splitting](#code-splitting)
+  - [`__filename` and `__dirname`](#__filename-and-__dirname)
+  - [JavaScript Caveats](#javascript-caveats)
+- [CSS](#css)
+  - [Importing CSS from JavaScript](#importing-css-from-javascript)
+  - [CSS Modules](#css-modules)
+  - [CSS Mixins](#css-mixins)
+  - [CSS Caveats](#css-caveats)
+- [Typescript](#typescript)
+  - [Typescript Caveats](#typescript-caveats)
+- [JSX](#jsx)
+- [JSON](#json)
+- [rjs is back!](#rjs-is-back)
+- [Testing your JavaScript](#testing-your-javascript)
+- [Resolution](#resolution)
+- [Aliases](#aliases)
+- [Pre-compilation](#pre-compilation)
+- [Puma `preload_app!` and Cluster Mode](#puma-preload_app-and-cluster-mode)
+- [Thanks](#thanks)
+- [Development](#development)
+
+## Getting Started
+
+Getting started obviously depends on whether you are adding Proscenium to an existing Rails app, or creating a new one. So choose the appropriate guide below:
+
+- [Getting Started with a new Rails app](docs/guides/new_rails_app.md)
+- Getting Started with an existing Rails app
+  - [Migrate from Sprockets](docs/guides/migrate_from_sprockets.md)
+- [RubyGem NPM dependencies](docs/guides/rubygem_npm_dependencies.md)
+- [Shipping NPM dependencies in a gem](docs/guides/gem_author.md)
+
+## Installation
+
+Add this line to your Rails application's Gemfile, and you're good to go:
+
+```ruby
+gem 'proscenium'
+```
+
+Please note that Proscenium is designed solely for use with Rails. It needs Ruby 3.4 or newer, and
+Rails 7.2 to 8.x.
+
+Now if you start your Rails app, you can open any front end code (JS, CSS, etc.). For example, a file at `app/assets/stylesheets/application.css` can be accessed at `https://localhost:3000/app/assets/stylesheets/application.css`, which will be transformed, bundled, and minified [in production] in real time.
+
+### Supported platforms
+
+Proscenium is a Ruby gem wrapped around a Go library, so it ships a precompiled gem per platform.
+Bundler picks the right one for you.
+
+| Platform | Gem |
+| --- | --- |
+| macOS, Apple silicon | `arm64-darwin` |
+| macOS, Intel | `x86_64-darwin` |
+| Linux glibc, arm64 | `aarch64-linux-gnu` |
+| Linux glibc, x86-64 | `x86_64-linux-gnu` |
+| Windows, x64 ([RubyInstaller](https://rubyinstaller.org/)) | `x64-mingw-ucrt` |
+
+The Linux gems need **RubyGems 3.3.22 or newer**, which is the first version able to tell
+`-gnu` from `-musl`. Older versions cannot, so they refuse the gem rather than installing one your
+machine cannot load. Ruby 3.4 already ships a newer RubyGems than this, so you are almost certainly
+fine; if not, `gem update --system`. Bundler 2.5.6 or newer resolves the platform names without
+needing anything else from you.
+
+Installing on a platform not listed here gets you the platform-less gem, which carries no compiled
+library, and Proscenium will say so by name when it loads rather than failing somewhere inside FFI.
+If your platform should be supported, please [open an
+issue](https://github.com/joelmoss/proscenium/issues).
+
+The Linux gems name their libc. Earlier releases shipped bare `x86_64-linux` and `aarch64-linux`
+names, which RubyGems matches on glibc and musl alike. If your `Gemfile.lock` is pinned to either,
+add the matching `-gnu` platform:
+
+```sh
+bundle lock --add-platform x86_64-linux-gnu   # or aarch64-linux-gnu, on ARM
+```
+
+Adding it is enough. There is no need to remove the old platform.
+
+On Windows, with a `Gemfile.lock` written on another machine: a plain `bundle install` adds the
+platform itself, but in frozen or deployment mode Bundler will not, so add it once.
+
+```sh
+bundle lock --add-platform x64-mingw-ucrt
+```
+
+### Alpine and other musl Linux distributions are not supported
+
+Use a glibc base image, such as `ruby:3.4-slim` rather than `ruby:3.4-alpine`.
+
+This is not an oversight. Proscenium's Go library is built with `-buildmode=c-shared` and loaded
+at runtime through Ruby's FFI, which uses `dlopen`. Go emits initial-exec TLS relocations into
+such libraries, and musl refuses to `dlopen` anything carrying them, by design:
+
+```
+Error relocating ...: free: initial-exec TLS resolves to dynamic definition
+```
+
+The library builds and links against musl perfectly well; it just cannot be loaded the way
+Proscenium needs to load it. This is [golang/go#54805](https://github.com/golang/go/issues/54805),
+open since 2022, and the linker flag that resolves it has not shipped as of Go 1.27. Musl gems
+will follow when it does.
+
+## Client-Side Code Anywhere
+
+Proscenium believes that your frontend code is just as important as your backend code, and is not an afterthought - they should be first class citizens of your Rails app. So instead of having to throw all your JS and CSS into a "app/assets" directory, and then requiring a separate process to compile or bundle, you can simply put them wherever you want within your app, and just run Rails!
+
+For example, if you have some JS that is required by your `app/views/users/index.html.erb` view, just create a JS file alongside it at `app/views/users/index.js`. Or if you have some CSS that is used by your entire application, put it in `app/views/layouts/application.css` and load it alongside your layout. Maybe you have a few JS utility functions, so put them in `lib/utils.js`.
+
+Simply put your JS(X) and CSS anywhere you want, and they will be served by your Rails app from the same location where you placed them.
+
+Using the examples above...
+
+- `app/views/users/index.js` => `https://localhost:3000/app/views/users/index.js`
+- `app/views/layouts/application.css` => `https://localhost:3000/app/views/layouts/application.css`
+- `lib/utils.js` => `https://localhost:3000/lib/utils.js`
+- `app/components/menu_component.jsx` => `https://localhost:3000/app/components/menu_component.jsx`
+- `config/properties.css` => `https://localhost:3000/config/properties.css`
+
+## Side Loading
+
+Proscenium is best experienced when your assets are automatically side loaded.
+
+### The Problem
+
+With Rails you would typically load your JavaScript and CSS assets declaratively using the `javascript_include_tag` and `stylesheet_link_tag` helpers.
+
+For example, you may have top-level "application" styles located in a file at `/app/assets/stylesheets/application.css`. Likewise, you may have some global JavaScript located in a file at `/app/javascript/application.js`.
+
+You would manually and declaratively include those two files in each of your layouts, something like this:
+
+```erb
+<%# /app/views/layouts/application.html.erb %>
+
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Hello World</title>
+    <%= stylesheet_link_tag 'application' %> <!-- << Your app CSS -->
+  </head>
+  <body>
+    <%= yield %>
+    <%= javascript_include_tag 'application' %> <!-- << Your app JS -->
+  </body>
+</html>
+```
+
+Now, you may have some CSS and JavaScript that is only required by a specific view and partial, so you would load that in your view (or layout), something like this:
+
+```erb
+<%# /app/views/users/index.html.erb %>
+
+<%= stylesheet_link_tag 'users' %>
+<%= javascript_include_tag 'users' %>
+
+<%# needed by the `users/_user.html.erb` partial %>
+<%= javascript_include_tag '_user' %>
+
+<% render @users %>
+```
+
+The main problem is that you have to keep track of all these assets, and make sure each is loaded by all the views that require them, but also avoid loading them when not needed. This can be a real pain, especially when you have a lot of views.
+
+### The Solution
+
+When side loading your JavaScript, Typescript and CSS with Proscenium, they are automatically included alongside your views, partials, layouts, and components, and only when needed.
+
+Side loading works by looking for a JS/TS/CSS file with the same name as your view, partial, layout or component. For example, if you have a view at `app/views/users/index.html.erb`, then Proscenium will look for a JS and CSS file at `app/views/users/index.js` (or TypeScript with a .ts extension) and `app/views/users/index.css`. If it finds one, it will automatically include it in the HTML for that view. And only for that view.
+
+This allows you to keep your assets organized alongside the views, partials, and components that use them, without having to manually track and include them. It also means only the assets that are needed are included.
+
+JSX is also supported for JavaScript and Typescript. Simply use the `.jsx` or `.tsx` extension instead of `.js` or `.ts`.
+
+### Usage
+
+Simply create a JS and/or CSS file with the same name as any view, partial or layout.
+
+Let's continue with our problem example above, where we have the following assets
+
+- `/app/assets/application.css`
+- `/app/assets/application.js`
+- `/app/assets/users.css`
+- `/app/assets/users.js`
+- `/app/assets/user.js`
+
+Your application layout is at `/app/views/layouts/application.html.erb`, and the view that needs the users assets is at `/app/views/users/index.html.erb`, so move your assets JS and CSS alongside them:
+
+- `/app/views/layouts/application.css`
+- `/app/views/layouts/application.js`
+- `/app/views/users/index.css`
+- `/app/views/users/index.js`
+- `/app/views/users/_user.js` (partial)
+
+Now, in your layout and view, replace the `javascript_include_tag` and `stylesheet_link_tag` helpers with the `include_asset` helper from Proscenium. Something like this:
+
+```erb
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Hello World</title>
+    <%= include_assets # <-- %>
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>
+```
+
+On each page request, Proscenium will check if any of your views, layouts and partials have a JS/TS/CSS file of the same name, and then include them wherever you placed the `include_assets` helper.
+
+Now you never have to remember to include your assets again. Just create them alongside your views, partials and layouts, and Proscenium will take care of the rest.
+
+Side loading is enabled by default, but you can disable it by setting `config.proscenium.side_load` to `false` in your `/config/application.rb`.
+
+There are also `include_stylesheets` and `include_javascripts` helpers to allow you to control where the CSS and JS assets are included in the HTML. These helpers should be used instead of `include_assets` if you want to control exactly where the assets are included.
+
+### Controlling side loading
+
+`sideload_assets` turns side loading off, or sets attributes on the tags it adds. In a controller, it applies to every view, layout and partial that controller renders. Each of these is an alternative:
+
+```ruby
+class UsersController < ApplicationController
+  sideload_assets false                  # side load nothing
+  sideload_assets css: false             # side load JS only
+  sideload_assets js: { defer: true }    # add attributes to each script tag
+  sideload_assets proc { !request.xhr? } # evaluated against the controller, on every request
+end
+```
+
+In a view, layout or partial, it applies to that template, for that render only:
+
+```erb
+<% sideload_assets false %>
+```
+
+Call it outside any `cache` block. A cache hit skips the block, and the call with it, so that render side loads the template's assets as though it had not been called.
+
+A partial rendered as a collection is side loaded once for the whole collection, so a `sideload_assets` call in any item applies to every item. With `cached: true`, a cache hit renders no items, so the call never runs. To control a cached collection partial, call `sideload_assets` in the controller instead.
+
+In a partial rendered with a block, as in `render 'box' do ... end`, a call in the partial applies to the partial, and a call inside the block applies to the template that passed it.
+
+## Bundling
+
+To bundle a file means to inline any imported dependencies into the file itself. This process is recursive so dependencies of dependencies (and so on) will also be inlined.
+
+Proscenium will bundle by default, and in real time. So there is no separate build step or pre-compilation.
+
+Proscenium supports importing JS, JSX, TS, TSX, CSS and SVG from NPM, by URL, your local app, and even from other Ruby Gems.
+
+Both static ([`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import)) and dynamic ([`import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)) imports are supported for JavaScript and TypeScript, and can be used to import JS, TS, JSX, TSX, JSON, CSS and SVG files.
+
+The [`@import`](https://developer.mozilla.org/en-US/docs/Web/CSS/@import) CSS at-rule is supported for CSS.
+
+### Non-analyzable imports
+
+Import paths are currently only bundled if they are a string literal or a glob pattern. Other forms of import paths are not bundled, and are instead preserved verbatim in the generated output. This is because bundling is a compile-time operation and Proscenium doesn't support all forms of run-time path resolution.
+
+Here are some examples:
+
+```js
+// Analyzable imports (will be bundled)
+import "pkg";
+import("pkg");
+import(`./locale-${foo}.json`);
+
+// Non-analyzable imports (will not be bundled)
+import(`pkg/${foo}`);
+```
+
+The way to work around non-analyzable imports is to mark the package containing this problematic code as [unbundled](#unbundling) so that it's not included in the bundle. You will then need to ensure that a copy of the external package is available to your bundled code at run-time.
+
+### Import from NPM (`node_modules`)
+
+Bare imports (imports not beginning with `./`, `/`, `https://`, `http://`) are fully supported, and will use your package manager of choice (eg, NPM, Yarn, pnpm) via the `package.json` file located at the root of your Rails app.
+
+Install the package you want to import using your package manager of choice...
+
+```
+npm install react
+```
+
+...and then import it as you would any other package.
+
+```js
+import React from "react";
+```
+
+### RubyGem NPM dependencies
+
+A gem can ship frontend code that imports npm packages, declared in a package.json of its own. Add
+the gem with Bundler, then install its NPM dependencies with your app's package manager,
+pnpm or Bun:
+
+```bash
+bundle exec proscenium install
+```
+
+That writes a small package.json for each such gem under `.proscenium/packages/`, holding only the
+gem's dependencies, registers them with your package manager, and runs its install. Commit what it
+lists. The gem's own files stay where Bundler put them. Run it again after every Gemfile change, and
+in CI run `bundle exec proscenium install --frozen`, which changes nothing you commit and fails if
+anything is out of date. When something is not working, `bundle exec proscenium doctor` (also
+`inspect`) lists every problem it finds, each with its fix. `psm` is a shorter name for the
+same command: `bundle exec psm install`.
+
+Its install covers your app's own packages too, so it replaces `pnpm install` or `bun install`
+everywhere you ran them, and `install --frozen` replaces a frozen install. It does not add, remove
+or upgrade packages: for your app's own dependencies, keep using `pnpm add`, `pnpm remove` and
+`pnpm update`, or `bun add`, `bun remove` and `bun update`.
+
+See [RubyGem NPM dependencies](docs/guides/rubygem_npm_dependencies.md) for the details,
+and the [gem author guide](docs/guides/gem_author.md) if you are writing such a gem.
+
+### Local Imports
+
+And of course you can import your own code, using relative or absolute paths (file extension is optional, and absolute paths use your Rails root as the base):
+
+```js
+import utils from "/lib/utils";
+import constants from "./constants";
+import Header from "/app/components/header";
+```
+
+```css
+@import "/lib/reset";
+```
+
+### Unbundling
+
+Sometimes you don't want to bundle an import. For example, you want to ensure that only one instance of React is loaded. In these cases, you can use the `unbundle` import attribute:
+
+```js
+import React from "react" with { unbundle: 'true' };
+```
+
+You can also unbundle entries in [`aliases`](#aliases) using an `unbundle:` prefix, which ensures that all imports of a particular path are always unbundled:
+
+```ruby
+config.proscenium.aliases = {
+  "react": "unbundle:react"
+}
+```
+
+Then just import as normal:
+
+```js
+import React from "react";
+```
+
+Or if you don't want any bundling at all, simply turn it off application-wide:
+
+```ruby
+config.proscenium.bundle = false
+```
+
+This will mean every asset and import will be loaded independently.
+
+## Source Maps
+
+Source maps can make it easier to debug your code. They encode the information necessary to translate from a line/column offset in a generated output file back to a line/column offset in the corresponding original input file. This is useful if your generated code is sufficiently different from your original code (e.g. your original code is TypeScript or you enabled minification). This is also useful if you prefer looking at individual files in your browser's developer tools instead of one big bundled file.
+
+Source map output is supported for both JavaScript and CSS. Each file is appended with the link to the source map. For example:
+
+```js
+//# sourceMappingURL=/app/views/layouts/application.js.map
+```
+
+Your browsers dev tools should pick this up and automatically load the source map when and where needed.
+
+## SVG
+
+You can import SVG from JS(X), which will bundle the SVG source code. Additionally, if importing from JSX or TSX, the SVG source code will be rendered as a JSX/TSX component.
+
+That component is compiled with esbuild's default JSX runtime, React, even when a `tsconfig.json` or `jsconfig.json` names another `jsxImportSource`, so importing an SVG from JSX needs `react` installed.
+
+When bundling, the SVG is read as markup, never as code, whether it is local or imported by URL. Its text and attribute values are kept as plain strings, so an expression such as `{proscenium.env.API_KEY}` inside an SVG stays literal text, and anything after the root element is ignored. The SVG is still rendered into the page as-is, so only import SVGs from sources you trust.
+
+## Environment Variables
+
+You can define and access any environment variable from your JavaScript and Typescript under the `proscenium.env` namespace.
+
+For performance and security reasons you must declare the environment variable names that you wish to expose in your `config/application.rb` file.
+
+```ruby
+config.proscenium.env_vars = Set['APP_VERSION', 'PUBLIC_API_URL']
+config.proscenium.env_vars << 'SENTRY_DSN'
+```
+
+> [!WARNING]
+> A declared variable's value is written as a plain string into any JavaScript that references it, both in what Proscenium serves and in what `assets:precompile` writes under `public/`. Anyone who loads the page can read it. Never declare a secret, such as an API key, password or token.
+
+This assumes that the environment variable of the same name has already been defined. If not, you will need to define it yourself either in your code using Ruby's `ENV` object, or in your shell.
+
+These declared environment variables will be replaced with constant expressions, allowing you to use this like this:
+
+```js
+console.log(proscenium.env.RAILS_ENV); // console.log("development")
+console.log(proscenium.env.RAILS_ENV === "development"); // console.log(true)
+```
+
+The `RAILS_ENV` and `NODE_ENV` environment variables will always automatically be declared for you.
+
+In addition to this, Proscenium also provides a `process.env.NODE_ENV` variable, which is set to the same value as `proscenium.env.RAILS_ENV`. It is provided to support the community's existing tooling, which often relies on this variable.
+
+Environment variables are particularly powerful in aiding [tree shaking](#tree-shaking).
+
+```js
+function start() {
+  console.log("start");
+}
+function doSomethingDangerous() {
+  console.log("resetDatabase");
+}
+
+proscenium.env.RAILS_ENV === "development" && doSomethingDangerous();
+
+start();
+```
+
+In any environment other than development, such as production, the above code will be transformed into the following code, discarding the definition of, and call to, `doSomethingDangerous()`.
+
+```js
+function start() {
+  console.log("start");
+}
+start();
+```
+
+Please note that for security reasons environment variables are not replaced in URL imports.
+
+An undefined environment variable will be replaced with `undefined`.
+
+```js
+console.log(proscenium.env.UNKNOWN); // console.log((void 0).UNKNOWN)
+```
+
+This means that code that relies on this will not be tree shaken. You can work around this by using the [optional chaining operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining):
+
+```js
+if (typeof proscenium.env?.UNKNOWN !== "undefined") {
+  // do something if UNKNOWN is defined
+}
+```
+
+## i18n
+
+Support is provided for importing your Rails locale files from `config/locales/*.yml`, exporting them as JSON.
+
+```js
+import translations from "proscenium/i18n";
+// translations.en.*
+```
+
+If you have multiple locale files, they will be merged together. into one json object.
+
+An app with no `config/locales` directory exports an empty object. A directory that exists but
+cannot be read - wrong permissions, an I/O error - fails the build instead, because the alternative
+is an app that silently ships with every translation missing.
+
+Note that because it is assumed that you will be consuming these translations in the browser, all keys are converted to camelCase, as per the JavaScript conventions.
+
+## Javascript
+
+By default, Proscenium's output will take advantage of all modern JS features from the ES2022 spec and earlier. For example, `a !== void 0 && a !== null ? a : b` will become `a ?? b` when minifying (enabled by default in production), which makes use of syntax from the ES2020 version of JavaScript. Any syntax feature that is not supported by ES2020 will be transformed into older JavaScript syntax that is more widely supported.
+
+### Tree Shaking
+
+Tree shaking is the term the JavaScript community uses for dead code elimination, a common compiler optimization that automatically removes unreachable code. Tree shaking is enabled by default in Proscenium.
+
+```javascript
+function one() {
+  console.log("one");
+}
+function two() {
+  console.log("two");
+}
+one();
+```
+
+The above code will be transformed to the following code, discarding `two()`, as it is never called.
+
+```javascript
+function one() {
+  console.log("one");
+}
+one();
+```
+
+### Code Splitting
+
+[Side loaded](#side-loading) assets are automatically code split. This means that if you have a file that is imported and used imported several times, and by different files, it will be split off into a separate file.
+
+As an example:
+
+```js
+// /lib/son.js
+import father from "./father";
+
+father() + " and Son";
+```
+
+```js
+// /lib/daughter.js
+import father from "./father";
+
+father() + " and Daughter";
+```
+
+```js
+// /lib/father.js
+export default () => "Father";
+```
+
+Both `son.js` and `daughter.js` import `father.js`, so both son and daughter would usually include a copy of father, resulting in duplicated code and larger bundle sizes.
+
+If these files are side loaded, then `father.js` will be split off into a separate file or chunk, and only downloaded once.
+
+- Code shared between multiple entry points is split off into a separate shared file that both entry points import. That way if the user first browses to one page and then to another page, they don't have to download all of the JavaScript for the second page from scratch if the shared part has already been downloaded and cached by their browser.
+
+- Code referenced through an asynchronous `import()` expression will be split off into a separate file and only loaded when that expression is evaluated. This allows you to improve the initial download time of your app by only downloading the code you need at startup, and then lazily downloading additional code if needed later.
+
+- Without code splitting, an import() expression becomes `Promise.resolve().then(() => require())` instead. This still preserves the asynchronous semantics of the expression but it means the imported code is included in the same bundle instead of being split off into a separate file.
+
+Code splitting is enabled by default. You can disable it by setting the `code_splitting` configuration option to `false` in your application's `/config/application.rb`:
+
+```ruby
+config.proscenium.code_splitting = false
+```
+
+### `__filename` and `__dirname`
+
+Proscenium provides Node.js-style `__filename` and `__dirname` constants in your JavaScript and TypeScript files. These are replaced at build time with the root-relative path of the current file and its directory respectively.
+
+```js
+// /app/views/users/index.js
+console.log(__filename); // "/app/views/users/index.js"
+console.log(__dirname); // "/app/views/users"
+```
+
+Files inside Ruby gems resolve to their `@rubygems/` scoped path:
+
+```js
+// Inside the "mygem" gem
+console.log(__filename); // "@rubygems/mygem/lib/mygem/component.js"
+console.log(__dirname); // "@rubygems/mygem/lib/mygem"
+```
+
+Note that `__filename` and `__dirname` are not injected into files within `node_modules`.
+
+### JavaScript Caveats
+
+There are a few important caveats as far as JavaScript is concerned. These are [detailed on the esbuild site](https://esbuild.github.io/content-types/#javascript-caveats).
+
+## CSS
+
+CSS is a first-class content type in Proscenium, which means it can bundle CSS files directly without needing to import your CSS from JavaScript code. You can `@import` other CSS files and reference image and font files with `url()` and Proscenium will bundle everything together.
+
+Note that by default, Proscenium's output will take advantage of all modern CSS features. For example, `color: rgba(255, 0, 0, 0.4)` will become `color: #f006` after minifying in production, which makes use of syntax from [CSS Color Module Level 4](https://drafts.csswg.org/css-color-4/#changes-from-3).
+
+The new CSS nesting syntax is supported, and transformed into non-nested CSS for older browsers.
+
+Proscenium will also automatically insert vendor prefixes so that your CSS will work in older browsers.
+
+### Importing CSS from JavaScript
+
+You can also import CSS from JavaScript. When you do this, Proscenium will automatically append each stylesheet to the document's head as a `<style>` element.
+
+If your page includes a `<meta name="csp-nonce" content="...">` tag, the injected `<style>` elements will automatically pick up the nonce value for Content Security Policy compliance.
+
+```jsx
+import "./button.css";
+
+export let Button = ({ text }) => {
+  return <div className="button">{text}</div>;
+};
+```
+
+### CSS Modules
+
+Proscenium implements a subset of [CSS Modules](https://github.com/css-modules/css-modules). It supports the `:local` and `:global` keywords, but not the `composes` property. (it is recommended that you use mixins instead of `composes`, as they will work everywhere, even in plain CSS files.)
+
+Give any CSS file a `.module.css` extension, and Proscenium will treat it as a CSS Module, transforming all class names with a suffix unique to the file.
+
+```css
+.title {
+  font-size: 20em;
+}
+```
+
+The above input produces:
+
+```css
+.title-5564cdbb {
+  font-size: 20em;
+}
+```
+
+You now have a unique class name that you can use pretty much anywhere.
+
+#### In your Views
+
+You can reference CSS modules from your Rails views, partials, and layouts using the `css_module` helper, which accepts one or more class names, and will return the equivilent CSS module names - the class name with the unique suffix appended.
+
+With [side-loading](#side-loading) setup, you can use the `css_module` helper as follows.
+
+```erb
+<div>
+  <h1 class="<%= css_module :hello_title %>">Hello World</h1>
+  <p class="<%= css_module :body, :paragraph %>">
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  </p>
+</div>
+```
+
+`css_module` accepts multiple class names, and will return a space-separated string of transformed CSS module names. Arrays of names are flattened, and `nil`, `false` and blank names are ignored, so `css_module :card, (active? && :active)` works.
+
+```ruby
+css_module :my_module_name
+# => "my_module_name-ABCD1234"
+```
+
+You can even reference a class from any CSS file by passing the URL path to the file, as a prefix to the class name. Doing so will automatically [side load](#side-loading) the stylesheet.
+
+```ruby
+css_module '/app/components/button.css@big_button'
+# => "big_button"
+```
+
+It also supports NPM packages (already installed in /node_modules):
+
+```ruby
+css_module 'mypackage/button@big_button'
+# => "big_button"
+```
+
+`css_module` also accepts a `path` keyword argument, which allows you to specify the path to the CSS
+file. Note that this will use the given path for all class names passed to that instance of `css_module`.
+
+```ruby
+css_module :my_module_name, path: Rails.root.join('app/components/button.css')
+```
+
+#### In your JavaScript
+
+Importing a CSS module from JS will automatically append the stylesheet to the document's head. And the result of the import will be an object of CSS class to module names.
+
+```js
+import styles from "./styles.module.css";
+// styles == { header: 'header-5564cdbb' }
+```
+
+It is important to note that the exported object of CSS module names is actually a JavaScript [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) object. So destructuring the object will not work. Instead, you must access the properties directly.
+
+Also, importing a CSS module into another CSS module will result in the same digest string for all classes.
+
+### CSS Mixins
+
+Proscenium provides functionality for including or "mixing in" onr or more CSS classes into another. This is similar to the `composes` property of CSS Modules, but works everywhere, and is not limited to CSS Modules.
+
+CSS mixins are supported using the `@define-mixin` and `@mixin` at-rules.
+
+A mixin is defined using the `@define-mixin` at-rule. Pass it a name, which should adhere to class name semantics, and declare your rules:
+
+```css
+// /lib/mixins.css
+@define-mixin bigText {
+  font-size: 50px;
+}
+```
+
+Use a mixin using the `@mixin` at-rule. Pass it the name of the mixin you want to use, and the url where the mixin is declared. The url is used to resolve the mixin, and can be relative, absolute, a URL, or even from an NPM packacge.
+
+```css
+// /app/views/layouts/application.css
+p {
+  @mixin bigText from url("/lib/mixins.css");
+  color: red;
+}
+```
+
+The above produce this output:
+
+```css
+p {
+  font-size: 50px;
+  color: red;
+}
+```
+
+Mixins can be declared in any CSS file. They do not need to be declared in the same file as where they are used. however, if you declare and use a mixin in the same file, you don't need to specify the URL of where the mixin is declared.
+
+```css
+@define-mixin bigText {
+  font-size: 50px;
+}
+
+p {
+  @mixin bigText;
+  color: red;
+}
+```
+
+A mixin must be defined at the root of a file. A `@define-mixin` inside a rule or an at-rule block such as `@media`, or inside another mixin, does not define anything: it is passed through as written, with a warning.
+
+One stylesheet may expand at most 100,000 mixins, inserting at most 4 MiB (4,194,304 bytes) of mixin definitions, with mixins nested at most 100 deep, so a chain of mixins that each include another more than once cannot grow without bound. Past any limit, each remaining `@mixin` is left as written, with one warning.
+
+Each stylesheet reports at most 100 warnings, plus one saying how many more were not reported and, past a limit, the mixin limit warning. A precompile sends at most 100 errors and 100 warnings in all, then one more message for each saying how many more there were, so in a build that noisy the limit warning can be one of those counted.
+
+CSS modules and Mixins works perfectly together. You can include a mixin in a CSS module.
+
+### CSS Caveats
+
+There are a few important caveats as far as CSS is concerned. These are [detailed on the esbuild site](https://esbuild.github.io/content-types/#css-caveats).
+
+## Typescript
+
+Typescript and TSX is supported out of the box, and has built-in support for parsing TypeScript syntax and discarding the type annotations. Just rename your files to `.ts` or `.tsx` and you're good to go.
+
+Please note that Proscenium does not do any type checking so you will still need to run `tsc -noEmit` in parallel with Proscenium to check types.
+
+### Typescript Caveats
+
+There are a few important caveats as far as Typescript is concerned. These are [detailed on the esbuild site](https://esbuild.github.io/content-types/#typescript-caveats).
+
+## JSX
+
+JSX needs no imports. Proscenium uses esbuild's automatic JSX runtime, which imports what each JSX file needs for you, from React's runtime (`react/jsx-runtime`) by default.
+
+To use another JSX library, such as Preact, set `jsxImportSource` in a `tsconfig.json` or `jsconfig.json`. It applies to every file in that directory and below:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact"
+  }
+}
+```
+
+Or set it for one file with a comment at the top:
+
+```jsx
+/** @jsxImportSource preact */
+export default () => <div>Hello</div>;
+```
+
+## JSON
+
+Importing .json files parses the JSON file into a JavaScript object, and exports the object as the default export. Using it looks something like this:
+
+```javascript
+import object from "./example.json";
+console.log(object);
+```
+
+In addition to the default export, there are also named exports for each top-level property in the JSON object. Importing a named export directly means Proscenium can automatically remove unused parts of the JSON file from the bundle, leaving only the named exports that you actually used. For example, this code will only include the version field when bundled:
+
+```javascript
+import { version } from "./package.json";
+console.log(version);
+```
+
+## rjs is back
+
+Proscenium brings back RJS! Any path ending in .rjs will be served from your Rails app. This allows you to import server rendered javascript.
+
+## Testing your JavaScript
+
+Your app's JavaScript can be tested with [Bun](https://bun.com), importing exactly what Proscenium
+serves - root-absolute paths, extensionless imports, aliases, `@rubygems/*`, CSS modules, SVG
+components, `proscenium/i18n`, `proscenium.env.*` and `.rjs` - with no dev server running and no
+separate build step.
+
+```bash
+rails generate proscenium:bun
+```
+
+That writes `test/proscenium.preload.js` and adds it to your `bunfig.toml` (merging into an
+existing one rather than replacing it). Then write a test that imports your app code:
+
+```jsx
+// test/js/button.test.jsx
+import { expect, test } from "bun:test";
+import Button from "/app/components/button.jsx";
+import styles from "/app/components/button.module.css";
+
+test("the button has its scoped class name", () => {
+  expect(styles.button).toEqual(Button.className);
+});
+```
+
+```bash
+bun test
+```
+
+### What you test is what you ship
+
+Every module you import is fetched through your application's own middleware stack, by a single
+`rails runner` process the preload starts for the run and talks to over a Unix socket. Not rebuilt
+with settings of the test harness's choosing - actually served, the same way a browser request is.
+So your `config.proscenium` settings apply as-is: bundling, minification, code splitting, aliases,
+externals and environment variables are whatever your app is configured to use. `.rjs` files are
+rendered by your own routes.
+
+The test file itself is the one exception, because no browser ever requests one: it is built
+directly rather than served, with its output read as a string instead of written, code splitting
+off, `bun:*`/`node:*` treated as external, and its source map inlined. Never minification, which is
+the setting that would actually change what you are testing.
+
+This matters more than it sounds. Minification decides the *shape* of a CSS module class name -
+minified you get `button_a1b2c3d4`, unminified `button_a1b2c3d4_app-…` - and your views and your
+stylesheets have to agree on which. So the harness does not get a vote: whatever your app is
+configured to do is what runs. Proscenium's own suite fails if the two ever diverge.
+
+Output is minified in production only, so a test failure names a real function on a real line
+rather than a letter at column 80. Note that "production" means a literal `production` Rails
+environment: any name Rails does not recognise - `staging`, `qa`, a per-PR environment - is
+treated as test, and so is served and precompiled unminified.
+
+### Caveats
+
+- **`mock.module` does not reach your own modules.** With bundling on - the Rails default - a
+  module's dependencies are inlined into it, so there is nothing left for a mock to substitute.
+  This catches an existing suite hard. Mock at a boundary the bundle cannot inline: `globalThis`
+  (`fetch`, a namespace a script installs), a property the code reads at call time, or a
+  test-environment `alias` pointing at a recording stub. Anything Proscenium leaves `external` -
+  `.rjs` included, since `*.rjs` is external by default - is resolved by Bun rather than inlined,
+  and a mock keyed on the specifier still will not match, because Bun resolves it to the file
+  Proscenium materialised. (`mock.module("/lib/api")` also cannot work at all: Bun only passes a
+  specifier to a plugin when it contains a `.` or a `:`.)
+- **Put this preload last, and externalise the runner's own tooling.** The plugin's load hook has
+  no namespace filter, so once registered it claims every uncached JavaScript module - including
+  `@testing-library/react` and whatever else your harness needs from node_modules. Registering it
+  after those are loaded and cached is half the answer; adding them to `config.proscenium.external`
+  in the test environment is the other, or each served test file gets its own second copy.
+- **An import map is invisible to Bun.** If bare specifiers reach the browser through
+  `<script type="importmap">`, mirror the same mapping in `compilerOptions.paths` in
+  `tsconfig.json`/`jsconfig.json`, which Bun does read. Otherwise Bun resolves them from
+  node_modules and you test a different copy than you ship - a CommonJS React, most likely, whose
+  named exports it cannot see.
+- **No cache-busting query strings.** `await import("./thing.js?t=" + Date.now())` to force a
+  fresh module cannot work under a bundler, which fixes module identity at build time. Give the
+  module no state to reset instead, or reset it explicitly.
+- **`sideEffects` in package.json is enforced.** A bare `import "./thing.js"` for its side effect
+  is dropped unless that path is listed there, exactly as in a production build.
+- **Code splitting is off, and the harness turns it off for you.** Nothing on the JavaScript side
+  can resolve a `../_asset_chunks/<name>-$HASH$.js` specifier, so the daemon disables splitting in
+  its own process rather than asking you to disable it for your whole test environment - where it
+  would also cost your system tests the chunked output production emits. The cost is that a
+  dynamic `import()` runs here against an inlined module; the chunk fetch itself is a system
+  test's job.
+- **Import statically.** Bun does not run a plugin's load hook for a dynamic `import()`, so
+  `await import("/lib/thing.js")` inside a test will not go through Proscenium.
+- **`.rjs` actions need `skip_forgery_protection`.** Rails refuses a non-XHR GET that returns
+  JavaScript, in the browser as much as under test.
+- **No DOM.** A CSS module still exports its class names, but the `<style>` element Proscenium
+  would append is skipped. Add [happy-dom](https://github.com/capricorn86/happy-dom) if you need
+  one.
+- **`config.proscenium.bundle = false` needs ESM dependencies.** Unbundled, every module is loaded
+  on its own, and a JavaScript runtime cannot load a CommonJS package that way - React 18 included.
+  The same is true in the browser.
+- **Stack traces name your functions, not your source lines.** Output is only minified in
+  production, so a failure points at a real function name and a real line of the built module.
+  It is not mapped back to the original file: a source map is embedded in everything the harness
+  builds, but Bun does not apply one to a module a plugin loaded (measured on Bun 1.3.13 and
+  1.4.2). The map costs nothing to carry, so it stays for when Bun does.
+
+- **Node, Deno and Vitest are not supported yet.** They can reuse the same daemon; see `TODOS.md`.
+
+## Resolution
+
+Proscenium will serve files ending with any of these extension: `js,mjs,ts,css,jsx,tsx` from the following directories, and their sub-directories of your Rails application's root: `/app`, `/lib`, `/config`, `/node_modules`, `/vendor`.
+
+So a file at `/app/views/users/index.js` will be served from `https://localhost:3000/app/views/users/index.js`.
+
+You can continue to access any file in the `/public` directory as you normally would. Proscenium will not process files in the `/public` directory.
+
+If requesting a file that exists in a root directory and the public directory, the file in the public directory will be served. For example, if you have a file at `/lib/foo.js` and `/public/lib/foo.js`, and you request `/lib/foo.js`, the file in the public directory (`/public/lib/foo.js`) will be served.
+
+## Aliases
+
+You can define import aliases via the `config.proscenium.aliases` config option. This allows you to create shorter or more meaningful import paths.
+
+```ruby
+config.proscenium.aliases = {
+  "utils": "/lib/utils.js",
+  "components": "/app/components"
+}
+```
+
+You can then import using the alias:
+
+```js
+import utils from "utils";
+import Header from "components/header";
+```
+
+## Pre-compilation
+
+Proscenium is designed to bundle and minify your frontend code in real time, on demand, with no build step or pre-compilation needed. However, if you want to pre-compile your assets for production deployment, you can do so using the `assets:precompile` Rake task.
+
+```bash
+rails assets:precompile
+```
+
+If any entry point fails to build, the task raises `Proscenium::Builder::CompileError` with esbuild's messages.
+
+Be sure to specify a `Set` of paths which you want to pre-compile via the `config.proscenium.precompile` configuration option. Each path should be a glob pattern that matches the files which are your entry points. Don't include paths that are not entry points. For example:
+
+```ruby
+Rails.configuration.proscenium.precompile = Set[
+  "./app/components/**/*.js",
+  "./app/components/**/*.jsx",
+  "./app/views/**/*.js",
+  "./app/views/**/*.css",
+  "./app/views/**/*.module.css"
+]
+```
+
+This will bundle, code split, tree shake, and compile all your JS, TS, JSX, TSX and CSS files and place them in the `public/assets` directory, ready to be served in production.
+
+## Puma `preload_app!` and Cluster Mode
+
+Proscenium's builder is backed by a Go shared library, and Go's runtime has a known, unfixed limitation ([golang/go#15538](https://github.com/golang/go/issues/15538)): if the Go runtime has already been initialized in a process before that process calls `fork()`, the forked child's Go runtime is left in a broken state (only the forking thread survives `fork()`; the Go scheduler and GC's other threads simply vanish) and any subsequent call into Go code in that child can hang or fail.
+
+This matters if you run Puma in cluster mode with `preload_app!` (the app, including gems, is booted once in the master process, then workers are created via `fork()` with no `exec()` afterward). Proscenium itself never triggers this - simply requiring the gem does not initialize the Go runtime, and nothing in Proscenium's own boot sequence calls into it. The Go runtime only initializes lazily, the first time something actually calls a builder method (`build_to_string`, `resolve`, or `compile`).
+
+**Do not call any `Proscenium::Builder` method (directly, or indirectly via the resolver/side-loading) from a Rails initializer or any other code that runs during application boot**, if you use `preload_app!` with `workers`. Doing so initializes the Go runtime in the master process before the fork, and every worker will inherit a broken one. There is no fix available from Go's side - this is a fundamental fork() limitation, not a bug Proscenium can work around. Asset builds and resolves triggered by actual HTTP requests (the normal case) are unaffected, since those always happen after the fork, independently in each worker.
+
+## Thanks
+
+HUGE thanks 🙏 go to [Evan Wallace](https://github.com/evanw) and his amazing [esbuild](https://esbuild.github.io/) project. Proscenium would not be possible without it, and it is esbuild that makes this so fast and efficient.
+
+Because Proscenium uses esbuild extensively, some of these docs are taken directly from the esbuild docs, with links back to the [esbuild site](https://esbuild.github.io/) where appropriate.
+
+## Development
+
+Before doing anything else, you will need compile a local version of the Go binary. This is because the Go binary is not checked into the repo. To compile the binary, run:
+
+```bash
+bundle exec rake compile:local
+```
+
+### Running tests
+
+We have tests for both Ruby and Go. To run the Ruby tests:
+
+```bash
+bin/test
+```
+
+To run the Go tests:
+
+```bash
+go test ./test ./internal/...
+```
+
+To run the JavaScript tests, which need the Go library compiled first:
+
+```bash
+cd fixtures/dummy && bun test test/js/
+```
+
+### Running Go benchmarks
+
+```bash
+go test ./test -bench=. -run="^$" -count=10 -benchmem
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/joelmoss/proscenium>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/joelmoss/proscenium/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Proscenium project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/joelmoss/proscenium/blob/master/CODE_OF_CONDUCT.md).