proscenium 0.25.3 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9b8a9a1d58d4345c62b41f8903e0515cc93f205b40ea91c8316702b8cf682b7
-  data.tar.gz: '0947a3b0b28e96d348a90a086b41266830613ff3f8786bcaf75ddabaa203705a'
+  metadata.gz: 2c5911cfff78cd611fec6681fe3bbda4890a72da2c7d25b226facbfb0c77a7a3
+  data.tar.gz: afdf60be93b068941e2f0496bba05a2be1af3389d9a98f4e010b1027da86b72b
 SHA512:
-  metadata.gz: 8ed1775133d82c9be954930a924f075ca3b3ebf1fe0f427444b02f4603eb3ad74ab9856661839f431d0311a762a53c8d22a7d7b8139ce8347e3281acaa8757f5
-  data.tar.gz: 5fd429b60fc41e5eb18f5147a965c4ca221f46e2d59e5091ba4e06325f539a3be79117e1bfde943db36885f895461d99dd4c8c9416bff1e2fded18724d5a0651
+  metadata.gz: 8da40b3b94f126ad0565e2bed0fefbe18d268fd43a4b185c0328c18163dec3cb6a385f6a7ae235482f6c6e30deb7d189b980cfa1a96f9d10b5808f4bb3a2765f
+  data.tar.gz: 5852c1d9b9d307b5a0072ab1669413822aafb33b211f33720787f2b554426860de9d751a4423e6e25dece3634e40ccb62e2bd4b4725d341b1cfc4b5430584917

data/README.md

@@ -25,10 +25,14 @@
 
 - [Getting Started](#getting-started)
 - [Installation](#installation)
+  - [Supported platforms](#supported-platforms)
 - [Client-Side Code Anywhere](#client-side-code-anywhere)
 - [Side Loading](#side-loading)
-- [Importing](#importing-assets)
+- [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)
@@ -51,7 +55,7 @@
 - [Testing your JavaScript](#testing-your-javascript)
 - [Resolution](#resolution)
 - [Aliases](#aliases)
-- [Pre-compilation](#precompilation)
+- [Pre-compilation](#pre-compilation)
 - [Puma `preload_app!` and Cluster Mode](#puma-preload_app-and-cluster-mode)
 - [Thanks](#thanks)
 - [Development](#development)
@@ -63,7 +67,8 @@ Getting started obviously depends on whether you are adding Proscenium to an exi
 - [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)
-- [Render a React component with Proscenium](docs/guides/basic_react.md)
+- [RubyGem NPM dependencies](docs/guides/rubygem_npm_dependencies.md)
+- [Shipping NPM dependencies in a gem](docs/guides/gem_author.md)
 
 ## Installation
 
@@ -73,10 +78,69 @@ Add this line to your Rails application's Gemfile, and you're good to go:
 gem 'proscenium'
 ```
 
-Please note that Proscenium is designed solely for use with Rails.
+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!
@@ -182,7 +246,7 @@ Now, in your layout and view, replace the `javascript_include_tag` and `styleshe
 </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 your placed the `include_assets` helper.
+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.
 
@@ -190,6 +254,31 @@ Side loading is enabled by default, but you can disable it by setting `config.pr
 
 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.
@@ -218,7 +307,7 @@ import(`./locale-${foo}.json`);
 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.
+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`)
 
@@ -236,6 +325,32 @@ npm install react
 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):
@@ -296,6 +411,10 @@ Your browsers dev tools should pick this up and automatically load the source ma
 
 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.
@@ -303,10 +422,13 @@ You can define and access any environment variable from your JavaScript and Type
 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['API_KEY', 'SOME_SECRET_VARIABLE']
-config.proscenium.env_vars << 'ANOTHER_API_KEY'
+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:
@@ -335,7 +457,7 @@ proscenium.env.RAILS_ENV === "development" && doSomethingDangerous();
 start();
 ```
 
-In development the above code will be transformed into the following code, discarding the definition, and call to`doSomethingDangerous()`.
+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() {
@@ -371,6 +493,10 @@ import translations from "proscenium/i18n";
 
 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
@@ -520,13 +646,13 @@ With [side-loading](#side-loading) setup, you can use the `css_module` helper as
 ```erb
 <div>
   <h1 class="<%= css_module :hello_title %>">Hello World</h1>
-  <p class="<%= css_module :body, paragraph: %>">
+  <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.
+`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
@@ -614,6 +740,12 @@ p {
 }
 ```
 
+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
@@ -632,18 +764,25 @@ There are a few important caveats as far as Typescript is concerned. These are [
 
 ## JSX
 
-Using JSX syntax usually requires you to manually import the JSX library you are using. For example, if you are using React, by default you will need to import React into each JSX file like this:
+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.
 
-```javascript
-import * as React from "react";
-render(<div />);
-```
+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:
 
-This is because the JSX transform turns JSX syntax into a call to `React.createElement` but it does not itself import anything, so the React variable is not automatically present.
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact"
+  }
+}
+```
 
-Proscenium generates these import statements for you. Keep in mind that this also completely changes how the JSX transform works, so it may break your code if you are using a JSX library that is not React.
+Or set it for one file with a comment at the top:
 
-In the [not too distant] future, you will be able to configure Proscenium to use a different JSX library, or to disable this auto-import completely.
+```jsx
+/** @jsxImportSource preact */
+export default () => <div>Hello</div>;
+```
 
 ## JSON
 
@@ -763,8 +902,8 @@ treated as test, and so is served and precompiled unminified.
 - **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). The map
-  costs nothing to carry, so it stays for when Bun does.
+  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`.
 
@@ -804,6 +943,8 @@ Proscenium is designed to bundle and minify your frontend code in real time, on
 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
@@ -851,13 +992,19 @@ bin/test
 To run the Go tests:
 
 ```bash
-go test ./test
+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 ./internal/builder -bench=. -run="^$" -count=10 -benchmem
+go test ./test -bench=. -run="^$" -count=10 -benchmem
 ```
 
 ## Contributing

data/exe/proscenium

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run as `bundle exec proscenium`. Loads the CLI alone: never `proscenium` itself, Rails, FFI or
+# the engine library (see lib/proscenium/cli.rb).
+# When the CLI started loading, for the timings install reports (C40).
+PROSCENIUM_STARTED = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+# Every file the CLI reads (package.json, contexts, pnpm-workspace.yaml) is UTF-8, whatever the
+# locale: under LANG=C, as minimal Docker and CI images run, Ruby would read them as US-ASCII.
+# Ruby warns of the setting, which is meant for this process alone.
+verbose = $VERBOSE
+$VERBOSE = nil
+Encoding.default_external = Encoding::UTF_8
+$VERBOSE = verbose
+
+require 'proscenium/cli'
+
+exit Proscenium::CLI.start(ARGV)

data/exe/psm

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# `bundle exec psm`: a shorter name for `bundle exec proscenium`, which it runs as is.
+load File.expand_path('proscenium', __dir__)

data/lib/proscenium/app_package.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Proscenium
+  # What the app's own package.json says that the context map needs (#154). Like ContextMap, which
+  # it reads JSON through, it loads nothing the `proscenium` CLI may not.
+  module AppPackage
+    LOCAL_SPECS = %w[link: file: workspace: portal:].freeze
+
+    module_function
+
+    # The names of the app's own `link:`, `file:` and workspace dependencies, peers included, as
+    # pnpm installs those too, and in a Bun app any workspace member it depends on by version,
+    # which Bun links. They keep their link paths once dependency contexts make other packages
+    # real-path.
+    def local_packages(root)
+      package = read(root) or return []
+
+      members = bun?(root, package) ? workspace_members(root, package['workspaces']) : []
+      %w[dependencies devDependencies optionalDependencies peerDependencies].flat_map do |field|
+        deps = package[field]
+        next [] unless deps.is_a?(Hash)
+
+        deps.select { |name, spec| spec.to_s.start_with?(*LOCAL_SPECS) || members.include?(name) }
+            .keys
+      end.uniq.sort
+    end
+
+    # Whether Bun installs the app: packageManager names it, or else its lockfile is there.
+    def bun?(root, package)
+      named = package['packageManager']
+      return named.split('@').first == 'bun' if named.is_a?(String)
+
+      %w[bun.lock bun.lockb].any? { File.exist?(File.join(root, it)) }
+    end
+
+    # The names of the packages `workspaces` (an array, or an object's `packages`) takes in, less
+    # those a `!` pattern leaves out, read as Bun's glob does: braces and `**` included.
+    def workspace_members(root, workspaces)
+      patterns = Array(workspaces.is_a?(Hash) ? workspaces['packages'] : workspaces).grep(String)
+      excluded, included = patterns.map { it.delete_prefix('./').chomp('/') }
+                                   .partition { it.start_with?('!') }
+      dirs = included.flat_map { Dir.glob(it, File::FNM_EXTGLOB, base: root) }.uniq
+      dirs.reject { |dir| excluded.any? { File.fnmatch?(it[1..], dir, File::FNM_EXTGLOB) } }
+          .filter_map { read(File.join(root, it))&.dig('name') }
+    end
+
+    # Whether package.json's text, for a file JSON.parse refuses, registers the contexts in its
+    # `workspaces`, decoding JSON's `\/` and `\uXXXX`
+    # escapes in the key and the pattern, as Bun does.
+    def workspaces?(text) = unescape(text).match?(WORKSPACES)
+
+    # JSON text with its `\uXXXX` and `\/` escapes decoded, as Bun reads them, for matching a file
+    # JSON.parse refuses.
+    # A surrogate pair is one character; a lone half, which JSON allows, becomes U+FFFD rather
+    # than raising.
+    def unescape(text)
+      text.gsub(ESCAPE) do
+        high, low, single = ::Regexp.last_match.captures
+        if high then (0x10000 + ((high.hex - 0xD800) << 10) + (low.hex - 0xDC00)).chr(Encoding::UTF_8)
+        elsif single then SURROGATES.cover?(single.hex) ? "\uFFFD" : single.hex.chr(Encoding::UTF_8)
+        else '/'
+        end
+      end
+    end
+
+    ESCAPE = %r{\\u([dD][89abAB]\h{2})\\u([dD][c-fC-F]\h{2})|\\u(\h{4})|\\/}
+    SURROGATES = (0xD800..0xDFFF)
+
+    # The pattern inside package.json's `workspaces`, an array or an object's `packages`.
+    WORKSPACES = /"workspaces"\s*:\s*(?:\{[^}]*"packages"\s*:\s*)?\[[^\]]*
+                  "\.proscenium\/packages\/\*"/x
+
+    # The manager `packageManager` names, or nil.
+    def package_manager(root)
+      field = read(root)&.dig('packageManager')
+      field.split('@').first if field.is_a?(String)
+    end
+
+    # The app's package.json as an object, or nil when it is missing or not one.
+    def read(root)
+      path = File.join(root, 'package.json')
+      package = File.exist?(path) && ContextMap.read_json(path)
+      package if package.is_a?(Hash)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end