asset_mapper 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17c6f6cc96968980eed2e68d911811f865b5934f09e97bc34cc90cef9065feca
-  data.tar.gz: f0958e155e9a4aa41f81b1151299f33ebe7d56955678808a4d2de3a4f777d41a
+  metadata.gz: 70001032fe042a996e8cd5be6001be5c578328b9284b299e86d6ba1514e1a068
+  data.tar.gz: d81ac7eb6cdb92334b11e8033304d1404919ce7c460e4d27e2c05c460dc3f439
 SHA512:
-  metadata.gz: e8b3b2fcb513edc9431b250ce4551895e54e4b0bf80f5fd189e87a57ed2bb22b544ac2f3a7d77c7549bce8910b0e3812b427d94e2ce28bd91bba0e7e6bb873cf
-  data.tar.gz: 87cef292a5174b1eb7854bda3691f75568e6d175c81a67c08d0d49b61ca6bbd66152c2900ce39333d9cf105a128d9e05fd435ba5d6f399866eca8c42b8a85ea6
+  metadata.gz: 79c421afd329f21c8eb68636fd4379eee07d0c80b162308dca9171b3cb53de135909937d1278758ff4eee94178408b924814667ccedd17cab9429a55cf8aaa49
+  data.tar.gz: 8cd97df7a9501aa77a12c29e9f01037e198550416d6b0416d04bbccb6176182f105a9aece09f98566d0e5f2b56a89934e5da36c9b849f85bf43b860d13afc572

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    asset_mapper (0.0.1)
-      dry-configurable (~> 0.13.0)
-      dry-files (~> 0.1.0)
+    asset_mapper (1.0.0)
+      dry-configurable (~> 1.0)
+      dry-files (~> 1.0)
       dry-initializer (~> 3.0)
       dry-types (~> 1.5)
       rake (>= 10)
@@ -13,58 +13,63 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
-    concurrent-ruby (1.1.9)
-    dry-configurable (0.13.0)
+    concurrent-ruby (1.1.10)
+    dry-configurable (1.0.1)
+      dry-core (~> 1.0, < 2)
+      zeitwerk (~> 2.6)
+    dry-core (1.0.0)
       concurrent-ruby (~> 1.0)
-      dry-core (~> 0.6)
-    dry-container (0.9.0)
+      zeitwerk (~> 2.6)
+    dry-files (1.0.1)
+    dry-inflector (1.0.0)
+    dry-initializer (3.1.1)
+    dry-logic (1.5.0)
       concurrent-ruby (~> 1.0)
-      dry-configurable (~> 0.13, >= 0.13.0)
-    dry-core (0.7.1)
+      dry-core (~> 1.0, < 2)
+      zeitwerk (~> 2.6)
+    dry-types (1.7.0)
       concurrent-ruby (~> 1.0)
-    dry-files (0.1.0)
-    dry-inflector (0.2.1)
-    dry-initializer (3.0.4)
-    dry-logic (1.2.0)
-      concurrent-ruby (~> 1.0)
-      dry-core (~> 0.5, >= 0.5)
-    dry-types (1.5.1)
-      concurrent-ruby (~> 1.0)
-      dry-container (~> 0.3)
-      dry-core (~> 0.5, >= 0.5)
-      dry-inflector (~> 0.1, >= 0.1.2)
-      dry-logic (~> 1.0, >= 1.0.2)
-    minitest (5.14.4)
-    parallel (1.21.0)
-    parser (3.0.2.0)
+      dry-core (~> 1.0, < 2)
+      dry-inflector (~> 1.0, < 2)
+      dry-logic (>= 1.4, < 2)
+      zeitwerk (~> 2.6)
+    json (2.6.3)
+    language_server-protocol (3.17.0.2)
+    minitest (5.16.3)
+    parallel (1.22.1)
+    parser (3.1.3.0)
       ast (~> 2.4.1)
-    rainbow (3.0.0)
+    rainbow (3.1.1)
     rake (13.0.6)
-    regexp_parser (2.1.1)
+    regexp_parser (2.6.1)
     rexml (3.2.5)
-    rubocop (1.22.3)
+    rubocop (1.39.0)
+      json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 3.0.0.0)
+      parser (>= 3.1.2.1)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.12.0, < 2.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.13.0)
-      parser (>= 3.0.1.1)
-    rubocop-performance (1.11.5)
+    rubocop-ast (1.24.0)
+      parser (>= 3.1.1.0)
+    rubocop-performance (1.15.1)
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.11.0)
-    standard (1.4.0)
-      rubocop (= 1.22.3)
-      rubocop-performance (= 1.11.5)
-    unicode-display_width (2.1.0)
-    zeitwerk (2.5.1)
+    standard (1.19.1)
+      language_server-protocol (~> 3.17.0.2)
+      rubocop (= 1.39.0)
+      rubocop-performance (= 1.15.1)
+    unicode-display_width (2.3.0)
+    zeitwerk (2.6.6)
 
 PLATFORMS
+  arm64-darwin-21
   x86_64-darwin-20
+  x86_64-linux
 
 DEPENDENCIES
   asset_mapper!
@@ -73,4 +78,4 @@ DEPENDENCIES
   standard (~> 1.3)
 
 BUNDLED WITH
-   2.2.31
+   2.3.5

data/README.md

@@ -20,7 +20,7 @@ bridge between frontend and backend.
 
 ## How does AssetMapper work?
 
-AssetMapper expects to be given a path to a JSON file that
+AssetMapper expects to be given a path to a JSON file(s) that
 is in a specific schema. To generate these schemas,
 generally a plugin needs to be made for your bundler of
 choice that complies with the AssetMapper schema. Then, for
@@ -39,49 +39,200 @@ more than I would like it to. It does things like:
 
 ## Roadmap
 
-- [ ] - Create a pluggable DevServer thats Rack compatible
-that can be injected as middleware.
-- [ ] - Create a gem and plugin for Parcel 2.
-- [ ] - Create a gem and plugin for Vite.
-- [ ] - Create a gem and plugin for ESBuild.
+- [ ] - Create a file hasher for bundle-less setups.
+- [ ] - Create a file watcher for development to auto-update the manifest.
+- [x] - Create a plugin for ESBuild.
+- [ ] - Create a plugin for Parcel 2.
+- [ ] - Create a plugin for Vite.
+- [ ] - Create a pluggable DevServer thats Rack compatible that can be injected as middleware.
+- [ ] - Create Rails view helpers.
 
 ## For Developers
 
 If you're interested in making a plugin for a bundler that is AssetMapper compatible
 here is the JSON schema expected:
 
+### Schema
+
 ```json
 {
-  "entrypoints": {
-    "path/before/transform.js": "path/after/transform.js"
-  },
-  "path/before/transform.js": "path/after/transform.js"
+  "<unhashed-path>": {
+    "asset_path": "<shortened-hashed-path>"
+    "file_path": "<full-hashed-path>"
+  }
 }
 ```
 
 ## Programmatic Usage
 
 ```rb
-AssetMapper.configure do |config|
-  config.manifest_path = "public/asset_manifest.json"
-  config.assets_path = "public/assets"
-  config.entrypoints_path = "#{config.asset_path}/entrypoints"
+# Create an AssetMapper::Configuration instance
+asset_mapper = AssetMapper.new.configure do |config|
+  # Where the manifest files can be found on the host machine
+  config.manifest_files = ["public/builds/asset-mapper-manifest.json"]
+
+  # The URL or path prefix for the files.
+  config.asset_host = "/builds"
+
+  # Do not cache the manifest in testing or in development.
+  config.cache_manifest = !(Rails.env.development? || Rails.env.testing?)
 end
 
-manifest = AssetMapper.manifest
+manifest = asset_mapper.manifest
 # =>
 #   {
-#     "entrypoints" => {
-#        "public/assets/entrypoints/application.js" => "public/assets/entrypoints/application.123.js"
-#     },
-#     "public/assets/icon.svg" => "public/assets/icon.123.svg"
+#     "files": {
+#       "entrypoints/application.js" => {
+#          "asset_path" => "entrypoints/application-[hash].js",
+#          "file_path" => "public/assets/entrypoints/application-[hash].js",
+#       }
+#     }
 #   }
 
-manifest.find_entrypoint("application.js")
-# => "public/assets/entrypoints/application.123.js"
+manifest.find("entrypoints/application.js")
+# => "/builds/entrypoints/application-[hash].js"
+
+manifest.find("assets/icon.svg")
+# => "/builds/assets/icon-[hash].svg"
+```
+
+## Supported bundlers
+
+- [x] [ESBuild](/docs/esbuild)
+- [ ] [Parcel 2](/docs/parcel2)
+- [ ] [Rollup](/docs/rollup)
+- [ ] [Vite](/docs/vite/)
+
+## Rails usage
+
+Create an initializer to initialize AssetMapper at `config/initializers/asset_mapper.rb`.
+
+```rb
+# config/initializers/asset_mapper.rb
+
+asset_mapper = AssetMapper.new.configure do |config|
+  # Where the manifest files can be found on the host machine
+  config.manifest_files = ["public/esbuild-builds/asset-mapper-manifest.json"]
+
+  # prepends "/builds" to all URLs
+  config.asset_host = "/builds"
+
+  # Do not cache the manifest in testing or in development.
+  config.cache_manifest = !(Rails.env.development? || Rails.env.testing?)
+end
+
+Rails.application.config.asset_mapper = asset_mapper
+```
+
+AssetMapper is now available under: `Rails.application.config.asset_mapper`. This is pretty
+verbose to use in your views you can create a helper for it.
+
+### Usage in Rails views
+
+```rb
+# app/helpers/application_helper.rb
+module ApplicationHelper
+  def asset_mapper
+    Rails.application.config.asset_mapper
+  end
+end
+```
+
+## Hanami setup
+
+The first step is to create a "provider" for asset_mapper.
+
+```rb
+# config/providers/asset_mapper.rb
+
+Hanami.app.register_provider(:asset_mapper) do
+  prepare do
+    require "asset_mapper"
+  end
+
+  start do
+    files = Dry::Files.new
+    asset_mapper = AssetMapper.new.configure do |config|
+      # The URL or path prefix for the files.
+      config.asset_host = "/assets"
+
+      # Do not cache the manifest in testing or in development, only production.
+      config.cache_manifest = Hanami.env?(:production)
+
+      # Files to watch
+      config.asset_files = ["app/assets/media/**/*.*"]
+
+      # Where to dump the assets
+      config.assets_output_path = files.join("public/assets")
+
+      # Where to write the manifest to.
+      config.manifest_output_path = files.join(config.assets_output_path, "asset-mapper-manifest.json")
+
+      # top level directory of assets. Used for relative short paths.
+      config.assets_root = files.join("app/assets")
+
+      # Where the manifest files can be found on the host machine
+      config.manifest_files = [
+        "public/assets/esbuild-manifest.json",
+        config.manifest_output_path
+      ]
+    end
+
+    register "asset_mapper", asset_mapper
+  end
+end
+
+```
+
+### Add a static rack server
+
+Next, we need to add a setting to `./config.ru` for when we write to the `public/` folder.
+
+```rb
+# config.ru
+
+require "hanami/boot"
+
+run Hanami.app
+
+#### Everything above here is provided by default
+
+#### Add the below call
+use Rack::Static, :urls => [""], :root => "public", cascade: true
+```
+
+Finally, to use in your views, do the following:
+
+```rb
+# app/context.rb
+module Main # <- Replace this with your slice or application name
+  class Context < Hanami::View::Context
+    include Deps["asset_mapper"]
+
+    def asset_path(asset_name)
+      asset_mapper.find(asset_name)
+    end
+  end
+end
+
+# app/view.rb
+module Main # <- Replace this with your slice or application name
+  class View < Hanami::View
+    config.default_context = Context.new
+  end
+end
 
-manifest.find("icon.svg")
-# => "public/assets/icon.123.svg"
+```erb
+# app/views/application.erb
+<html>
+  <head>
+    <title>Bookshelf</title>
+    <script src="<%= asset_path("javascript/entrypoints/application.js") %>" type="module">
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>
 ```
 
 ## Development

data/Rakefile

@@ -6,7 +6,7 @@ require "rake/testtask"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.test_files = FileList["test/*_test.rb"]
 end
 
 require "standard/rake"

data/asset_mapper.gemspec

@@ -5,19 +5,19 @@ require_relative "lib/asset_mapper/version"
 Gem::Specification.new do |spec|
   spec.name = "asset_mapper"
   spec.version = AssetMapper::VERSION
-  spec.authors = ["ParamagicDev"]
+  spec.authors = ["KonnorRogers"]
   spec.email = ["konnor5456@gmail.com"]
 
   spec.summary = "A tightly scoped directory parser and json file generator. "
-  spec.homepage = "https://github.com/ParamagicDev/asset_mapper"
+  spec.homepage = "https://github.com/KonnorRogers/asset_mapper"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 2.6.0"
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/ParamagicDev/asset_mapper"
-  spec.metadata["changelog_uri"] = "https://github.com/ParamagicDev/asset_mapper/blob/main/CHANGELOG.md"
+  spec.metadata["source_code_uri"] = "https://github.com/KonnorRogers/asset_mapper"
+  spec.metadata["changelog_uri"] = "https://github.com/KonnorRogers/asset_mapper/blob/main/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -32,8 +32,8 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency "rake", ">= 10"
   spec.add_runtime_dependency "zeitwerk", "~> 2.5"
-  spec.add_runtime_dependency "dry-configurable", "~> 0.13.0"
-  spec.add_runtime_dependency "dry-files", "~> 0.1.0"
+  spec.add_runtime_dependency "dry-configurable", "~> 1.0"
+  spec.add_runtime_dependency "dry-files", "~> 1.0"
   spec.add_runtime_dependency "dry-initializer", "~> 3.0"
   spec.add_runtime_dependency "dry-types", "~> 1.5"
 end

data/bin/setup

@@ -6,3 +6,28 @@ set -vx
 bundle install
 
 # Do any other automated setup that you need to do here
+
+# ESbuild plugin setup
+cd packages/asset-mapper-esbuild
+npx pnpm install
+npx pnpm build
+
+cd -
+
+# Rails setup
+cd test/rails/asset-mapper-app
+bundle install
+yarn install
+yarn run build
+
+cd -
+
+# Hanami setup
+cd test/hanami
+bundle install
+yarn install
+yarn run build
+
+cd -
+
+echo "Setup complete. Checkout 'test/rails/asset-mapper-app' or 'test/hanami for more!'"

data/docs/parcel2.md

@@ -0,0 +1,137 @@
+# Parcel 2
+
+To get started with Parcel 2, if you haven't already, create a `package.json`.
+
+```bash
+yarn init
+```
+
+In our `package.json`, lets add a `build` command as well
+as specify our `"sources"`.
+
+```json
+// package.json
+{
+  "targets": {
+    "default": {
+      "source": "app/javascript/entrypoints",
+      "isLibrary": false,
+      "distDir": "./public/parcels"
+    }
+  },
+  "scripts": {
+    "watch": "parcel watch",
+    "build": "parcel build"
+  }
+}
+```
+
+This means all of our "entrypoints" should be located under
+`app/javascript/entrypoints`
+
+For example, you may have a
+`app/javascript/entrypoints/application.js`
+
+This file will be the file that is referenced when using a
+`<script>` tag.
+
+Next, we need to install the proper node dependencies.
+
+```bash
+yarn add -D parcel @parcel/config-default parcel-reporter-bundle-manifest
+```
+
+Then, create a `.parcelrc` file in the root of your
+project.
+
+```bash
+touch .parcelrc
+```
+
+And then add the following contents:
+
+```json
+{
+  "extends": "@parcel/config-default",
+  "reporters": ["...", "parcel-reporter-bundle-manifest"]
+}
+```
+
+## Setting up the server.
+
+If you're using Rails, create a file called `asset_mapper.rb` in
+your `config/initializers` folder. If you're not using
+Rails, in whatever file initializes your app, add the
+following code:
+
+```rb
+// config/initializers/asset_mapper.rb
+
+AssetMapper.configure do |config|
+  # Prefix before all file paths
+  config.asset_host = "/"
+
+  # Where to find your manifest files. (Most people have only 1)
+  config.manifest_files = %w[public/parcels/parcel-manifest.json]
+end
+```
+
+## Adding to our HTML
+
+To add your script and stylesheet tags to your build, you
+can do the following:
+
+```erb
+<link href="<%= AssetMapper.find('entrypoints/application.css') %>" rel="stylesheet">
+<script src="<%= AssetMapper.find('entrypoints/application.js') %>" type="module">
+```
+
+## Additional Optimizations
+
+### Compression
+
+First, install the compression plugins:
+
+```bash
+yarn add -D @parcel/compressor-gzip @parcel/compressor-brotli
+```
+
+If you would like to add gzipping / brotli compression,
+make your `.parcelrc` look like the following:
+
+```json
+{
+  "extends": "@parcel/config-default",
+  "reporters": ["...", "parcel-reporter-bundle-manifest"]
+  "compressors": {
+    "*.{html,css,js,svg,map}": [
+      "...",
+      "@parcel/compressor-gzip",
+      "@parcel/compressor-brotli"
+    ]
+  }
+}
+```
+
+This will gzip / brotli compress any .html, .css, .js, .svg,
+and .map files so that your web server doesn't have to.
+
+### Specifying a build target
+
+Build targets are a way of specifying "what version of
+javascript to ship", IE: ES6, ES2018, ESNext, etc.
+
+Parcel has a whole section dedicated to [specifying targets]()
+
+The easiest to set in your `package.json` is the following:
+
+```json
+// package.json
+ {
+  "browserslist": "> 0.5%, last 2 versions, not dead"
+ }
+```
+
+### Usage with static files
+
+https://www.npmjs.com/package/parcel-reporter-multiple-static-file-copier

data/lib/asset_mapper/configuration.rb

@@ -0,0 +1,67 @@
+require "dry/configurable"
+require "forwardable"
+require "digest"
+
+module AssetMapper
+  # Configuration object for asset mapper. This is the top level API.
+  class Configuration
+    extend ::Forwardable
+    include ::Dry::Configurable
+
+    # Where to find the json mapping of your asset files.
+    # @return [String[]]
+    setting :manifest_files, default: []
+
+    # In case you server off of a CDN, you may want to prepend urls.
+    setting :asset_host, default: "/"
+
+    # Whether or not to cache the manifest.
+    # @return [Boolean]
+    setting :cache_manifest, constructor: lambda { |value| !!value }
+
+    # Raise an error if the file can't be found. Useful in development.
+    # @return [Boolean]
+    setting :raise_on_missing_file, default: false
+
+    # Raise an error if the same key is found twice across the same or multiple manifests.
+    # @return [Boolean]
+    setting :raise_on_duplicate_key, default: false
+
+    # Files for AssetMapper to watch for changes and generate hashes for.
+    # Accepts glob patterns like Dir["*"].
+    # @return [Array<String>]
+    setting :asset_files, default: []
+
+    # Override the default file watcher.
+    setting :file_watcher
+
+    # Append hashes to the end of files.
+    setting :fingerprint, default: true
+
+    # Use MD5 hashes. They're fast, and don't need to be secure.
+    setting :fingerprint_method, default: lambda { |str| Digest::MD5.hexdigest(str) }
+
+    # root of your assets, used for short paths.
+    setting :assets_root
+
+    # Where to dump the assets
+    setting :assets_output_path
+
+    # Where to write the manifest to.
+    setting :manifest_output_path
+
+    def_delegators :manifest, :find
+
+    # Returns an instance of the manifest.
+    # @return [AssetMapper::Manifest]
+    def manifest
+      @manifest ||= Manifest.new(config)
+    end
+
+    # Returns an instance of a manifest generator. This is for files that are watched by asset_mapper.
+    # @return [AssetMapper::ManifestGenerator]
+    def manifest_generator
+      @manifest_generator ||= ManifestGenerator.new(config)
+    end
+  end
+end