proscenium 0.16.0-x86_64-darwin → 0.17.0-x86_64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 479d3b5ead246fb0f02afc95f9b274cf45eda3e8cf36dd2d9da25e9204e39433
-  data.tar.gz: a95291f48d2f582f9781f7a504ee35317ff5ac5c6b12b7cedf5a7b3f1934e971
+  metadata.gz: cac05c7b04ae00a23bc5fdc756e2f84d0d4ab609e31ca778220a3eba54cfd70b
+  data.tar.gz: 966043dd74d150e12197bced913b99a321610e5ec83e841a0798c603965eb8a5
 SHA512:
-  metadata.gz: a9b5ab728976d9d3b80435e9ae5a9103fde26d1926ca0bf30cf49853f34cfc50e7aad197ee8e842e08c874d0c4dfc8a5c4a2113ca1fd6350df291c25700117ff
-  data.tar.gz: f3f75fec50b5324ff608e40ec683c21212bf3d4495d8a81eb87db86fc8008bd6be857d09a85643c757b26caf68cb5ce8bc7614ac4c20a2b3138d66d51daef985
+  metadata.gz: 185036c0585134b3552865161c064c6bfb585c6183e3563c66c865b84c98013a8cd829ea5dddc43d57980bf4c84153d38c6582b08ee32130e3cacd76a021e27d
+  data.tar.gz: 5419b3db81eb4bdbe31ea330dcb87580aa9d695b0d5bcb7f924833cf6801e1420f36bef3b0d79a548f901fc926b93ebf00861efe4c73275c46ce2a343103f740

data/README.md

@@ -1,13 +1,20 @@
-# Proscenium - Modern client-side development for Rails
+# Proscenium - Integrated Frontend Development for Rails
 
-Proscenium treats your client-side code as first class citizens of your Rails app, and assumes a "fast by default" internet. It bundles your JavaScript and CSS in real time, on demand, and with zero configuration.
+> 🗣️ 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 - just the browser!
+- 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!
+- NO additional process or server - Just run `rails s`!
+- Transforms newer JavaScript and CSS syntax to older syntax for older browsers.
 - Deep integration with Rails.
 - Automatically side-load your layouts, views, and partials.
 - Import from NPM, URL's, and locally.
@@ -22,7 +29,6 @@ Proscenium treats your client-side code as first class citizens of your Rails ap
 - [Client-Side Code Anywhere](#client-side-code-anywhere)
 - [Side Loading](#side-loading)
 - [Importing](#importing-assets)
-  - [URL Imports](#url-imports)
   - [Local Imports](#local-imports)
 - [Import Maps](#import-maps)
 - [Source Maps](#source-maps)
@@ -70,7 +76,9 @@ 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, so will not work - at least out of the box - anywhere else.
+Please note that Proscenium is designed solely for use with Rails.
+
+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 bundled, transformed, and minified [in production] in real time.
 
 ## Client-Side Code Anywhere
 
@@ -82,23 +90,21 @@ Simply put your JS(X) and CSS anywhere you want, and they will be served by your
 
 Using the examples above...
 
-- `app/views/users/index.js` => `https://yourapp.com/app/views/users/index.js`
-- `app/views/layouts/application.css` => `https://yourapp.com/app/views/layouts/application.css`
-- `lib/utils.js` => `https://yourapp.com/lib/utils.js`
-- `app/components/menu_component.jsx` => `https://yourapp.com/app/components/menu_component.jsx`
-- `config/properties.css` => `https://yourapp.com/config/properties.css`
+- `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
 
-> Prior to **0.10.0**, only assets with the extension `.js`, `.ts` and `.css` were side loaded. From 0.10.0, all assets are side loaded, including `.jsx`, `.tsx`, and `.module.css`. Also partials were not side loaded prior to 0.10.0.
-
-Proscenium is best experienced when you side load your assets.
+Proscenium is best experienced when your assets are automtically side loaded.
 
 ### The Problem
 
 With Rails you would typically declaratively load your JavaScript and CSS assets using the `javascript_include_tag` and `stylesheet_link_tag` helpers.
 
-For example, you may have top-level "application" CSS located in a file at `/app/assets/application.css`. Likewise, you may have some global JavaScript located in a file at `/app/assets/application.js`.
+For example, you may have top-level "application" CSS 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 your application layout, something like this:
 
@@ -177,45 +183,55 @@ 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 your 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.
 
-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.
+## Bundling
 
-Side loading is enabled by default, but you can disable it by setting `config.proscenium.side_load`
-to `false` in your `/config/application.rb`.
+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.
 
-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.
+Proscenium will bundle by default, and in real time. So there is no separate build step or pre-compilation.
 
-## Importing Assets
+Proscenium supports importing JS, JSX, TS, TSX, CSS and SVG from NPM, by URL, your local app, and even from other Ruby Gems.
 
-Proscenium supports importing JS, JSX, TS, TSX, CSS and SVG from NPM, by URL, your local app, and even from 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.
 
-Imported files are bundled together in real time. So no build step or pre-compilation is needed.
+The [`@import`](https://developer.mozilla.org/en-US/docs/Web/CSS/@import) CSS at-rule is supported for CSS.
 
-Imports are assumed to be JS files, so there is no need to specify the file extesnion in such cases. But you can if you like. All other file types must be specified using their full file name and extension.
+### Non-analyzable imports
 
-### URL 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.
 
-Any import beginning with `http://` or `https://` will be fetched from the URL provided. For example:
+Here are some examples:
 
 ```js
-import React from "https://esm.sh/react";
-```
+// Analyzable imports (will be bundled)
+import "pkg";
+import("pkg");
+import(`./locale-${foo}.json`);
 
-```css
-@import "https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/css/bootstrap.min.css";
+// Non-analyzable imports (will not be bundled)
+import(`pkg/${foo}`);
 ```
 
-URL imports are cached, so that each import is only fetched once per server restart.
+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:
+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";
@@ -223,26 +239,18 @@ import React from "react";
 
 ### Local Imports
 
-And of course you can import your own code, using relative or absolute paths (file extension is optional):
+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 /app/views/layouts/application.js
+```js
 import utils from "/lib/utils";
-```
-
-```js /lib/utils.js
 import constants from "./constants";
+import Header from "/app/components/header";
 ```
 
-```css /app/views/layouts/application.css
+```css
 @import "/lib/reset";
 ```
 
-```css /lib/reset.css
-body {
-  /* some styles... */
-}
-```
-
 ### 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 this cases, you can use the `unbundle` prefix
@@ -253,7 +261,7 @@ import React from "unbundle:react";
 
 This only works any bare and local imports.
 
-You can also use the `unbundle` prefix in your import map, which ensures that all imports of a particular path is always unbundled:
+You can also use the `unbundle` prefix in your [import map](#import-maps), which ensures that all imports of a particular path is always unbundled:
 
 ```json
 {
@@ -411,7 +419,7 @@ import translations from "@proscenium/i18n";
 
 ## Javascript
 
-By default, Proscenium's output will take advantage of all modern JS features. 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.
+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
 
@@ -491,6 +499,8 @@ Note that by default, Proscenium's output will take advantage of all modern CSS
 
 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 `<link>` element.
@@ -835,7 +845,7 @@ Proscenium brings back RJS! Any path ending in .rjs will be served from your Rai
 
 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://yourapp.com/app/views/users/index.js`.
+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.
 

data/lib/proscenium/helper.rb

@@ -15,10 +15,18 @@ module Proscenium
     # building with Proscenium. It's important to note that `include_assets` will not call this, as
     # those asset paths all begin with a slash, which the Rails asset helpers do not pass through to
     # here.
+    #
+    # If the given `path` is a bare path (does not start with `/` or `./` or `../`), then we use
+    # Rails default conventions, and serve CSS from /app/assets/stylesheets and JS from
+    # /app/javascript.
     def compute_asset_path(path, options = {})
       if %i[javascript stylesheet].include?(options[:type])
+        if !path.start_with?("./", "../")
+          path.prepend DEFAULT_RAILS_ASSET_PATHS[options[:type]]
+        end
+
         result = Proscenium::Builder.build_to_path(path, base_url: request.base_url)
-        return result.split('::').last.delete_prefix 'public'
+        return result.split("::").last.delete_prefix "public"
       end
 
       super

data/lib/proscenium/middleware.rb

@@ -11,7 +11,6 @@ module Proscenium
     autoload :Esbuild
     autoload :Engines
     autoload :Runtime
-    autoload :Url
 
     def initialize(app)
       @app = app
@@ -41,7 +40,6 @@ module Proscenium
     end
 
     def find_type(request)
-      return Url if request.path.match?(%r{^/https?%3A%2F%2F})
       return Runtime if request.path.match?(%r{^/@proscenium/})
       return Esbuild if Pathname.new(request.path).fnmatch?(app_path_glob, File::FNM_EXTGLOB)
 

data/lib/proscenium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Proscenium
-  VERSION = '0.16.0'
+  VERSION = '0.17.0'
 end

data/lib/proscenium.rb

@@ -8,6 +8,13 @@ module Proscenium
   FILE_EXTENSIONS = ['js', 'mjs', 'ts', 'jsx', 'tsx', 'css', 'js.map', 'mjs.map', 'jsx.map',
                      'ts.map', 'tsx.map', 'css.map'].freeze
 
+  # Default paths for Rails assets. Used by the `compute_asset_path` helper to maintain Rails
+  # default conventions of where JS and CSS files are located.
+  DEFAULT_RAILS_ASSET_PATHS = {
+    stylesheet: 'app/assets/stylesheets/',
+    javascript: 'app/javascript/'
+  }.freeze
+
   ALLOWED_DIRECTORIES = 'app,lib,config,vendor,node_modules'
 
   # Environment variables that should always be passed to the builder.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: proscenium
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: x86_64-darwin
 authors:
 - Joel Moss
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-11 00:00:00.000000000 Z
+date: 2024-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -171,7 +171,6 @@ files:
 - lib/proscenium/middleware/engines.rb
 - lib/proscenium/middleware/esbuild.rb
 - lib/proscenium/middleware/runtime.rb
-- lib/proscenium/middleware/url.rb
 - lib/proscenium/monkey.rb
 - lib/proscenium/phlex.rb
 - lib/proscenium/phlex/asset_inclusions.rb

data/lib/proscenium/middleware/url.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module Proscenium
-  class Middleware
-    # Handles requests for URL encoded URL's.
-    class Url < Esbuild
-      private
-
-      # @override [Esbuild] It's a URL, so always assume it is renderable (we won't actually know
-      #   until it's downloaded).
-      def renderable?
-        true
-      end
-    end
-  end
-end