Module: Shakapacker

Extended by:
Shakapacker
Included in:
Shakapacker
Defined in:
lib/shakapacker.rb,
lib/shakapacker/doctor.rb,
lib/shakapacker/runner.rb,
lib/shakapacker/version.rb,
lib/shakapacker/utils/misc.rb,
lib/shakapacker/install/env.rb,
lib/shakapacker/swc_migrator.rb,
lib/shakapacker/base_strategy.rb,
lib/shakapacker/rspack_runner.rb,
lib/shakapacker/utils/manager.rb,
lib/shakapacker/mtime_strategy.rb,
lib/shakapacker/webpack_runner.rb,
lib/shakapacker/digest_strategy.rb,
lib/shakapacker/version_checker.rb,
lib/shakapacker/bundler_switcher.rb,
lib/shakapacker/compiler_strategy.rb,
lib/shakapacker/dev_server_runner.rb,
lib/shakapacker/deprecation_helper.rb,
lib/shakapacker/build_config_loader.rb,
lib/shakapacker/utils/version_syntax_converter.rb

Overview

Shakapacker

Shakapacker is a Ruby gem that integrates webpack and rspack with Rails applications, providing a modern asset pipeline for JavaScript, CSS, and other web assets.

The main Shakapacker module provides singleton-style access to configuration, compilation, and asset manifest functionality. Most methods delegate to a shared Instance object.

Basic Usage

# Access configuration
Shakapacker.config.source_path
#=> Pathname("/path/to/app/packs")

# Check if dev server is running
Shakapacker.dev_server.running?
#=> true

# Look up compiled assets
Shakapacker.manifest.lookup("application.js")
#=> "/packs/application-abc123.js"

# Compile assets
Shakapacker.compile

Configuration

Configuration is loaded from config/shakapacker.yml and can be accessed via #config. The configuration determines the source paths, output paths, compilation settings, and dev server options.

See Also:

Defined Under Namespace

Modules: Helper, Install, Utils Classes: BaseStrategy, BuildConfigLoader, BundlerSwitcher, Commands, Compiler, CompilerStrategy, Configuration, DevServer, DevServerProxy, DevServerRunner, DigestStrategy, Doctor, Engine, Env, Instance, Manifest, MtimeStrategy, RspackRunner, Runner, SwcMigrator, VersionChecker, WebpackRunner

Constant Summary collapse

DEFAULT_ENV =

Default environment when RAILS_ENV is not set

"development".freeze
DEV_ENVS =

Environments that use “development” for NODE_ENV All other environments (production, staging, etc.) use “production” for webpack optimizations Note: Both development and test RAILS_ENV use NODE_ENV=development because webpack/rspack only recognize “development” and “production” values for NODE_ENV. Using “test” causes DefinePlugin conflicts with optimization.nodeEnv.

%w[development test].freeze
VERSION =

Change the version in package.json too, please!

"10.1.0.rc.0".freeze
SHELL = 
Thor::Shell::Color.new

Instance Method Summary collapse

Instance Method Details

#bootstrap ⇒ void

This method returns an undefined value.

Creates the default configuration files and directory structure

See Also:



194
 
# File 'lib/shakapacker.rb', line 194

delegate :bootstrap, :clean, :clobber, :compile, to: :commands

#clean(count = nil, age = nil) ⇒ void

This method returns an undefined value.

Removes old compiled packs, keeping the most recent versions

Parameters:

  • count (Integer, nil) (defaults to: nil) —

    number of versions to keep per entry

  • age (Integer, nil) (defaults to: nil) —

    maximum age in seconds for packs to keep

See Also:



194
 
# File 'lib/shakapacker.rb', line 194

delegate :bootstrap, :clean, :clobber, :compile, to: :commands

#clobber ⇒ void

This method returns an undefined value.

Removes all compiled packs

See Also:



194
 
# File 'lib/shakapacker.rb', line 194

delegate :bootstrap, :clean, :clobber, :compile, to: :commands

#commands ⇒ Shakapacker::Commands

Returns the commands instance for build operations

Returns:

See Also:



174
 
# File 'lib/shakapacker.rb', line 174

delegate :config, :compiler, :manifest, :commands, :dev_server, to: :instance

#compile ⇒ Boolean

Compiles all webpack/rspack packs

Returns:

  • (Boolean) —

    true if compilation succeeded

See Also:



194
 
# File 'lib/shakapacker.rb', line 194

delegate :bootstrap, :clean, :clobber, :compile, to: :commands

#compiler ⇒ Shakapacker::Compiler

Returns the compiler instance for compiling assets

Returns:

See Also:



174
 
# File 'lib/shakapacker.rb', line 174

delegate :config, :compiler, :manifest, :commands, :dev_server, to: :instance

#config ⇒ Shakapacker::Configuration

Returns the Shakapacker configuration object

Returns:

See Also:



174
 
# File 'lib/shakapacker.rb', line 174

delegate :config, :compiler, :manifest, :commands, :dev_server, to: :instance

#dev_server ⇒ Shakapacker::DevServer

Returns the dev server instance for querying server status

Returns:

See Also:



174
 
# File 'lib/shakapacker.rb', line 174

delegate :config, :compiler, :manifest, :commands, :dev_server, to: :instance

#ensure_log_goes_to_stdout { ... } ⇒ Object

Temporarily redirects Shakapacker logging to STDOUT

This is useful for debugging or when you want to see compilation output in the console instead of the Rails log.

Examples:

Shakapacker.ensure_log_goes_to_stdout do
  Shakapacker.compile
end

Yields:

  • the block to execute with STDOUT logging

Returns:

  • (Object) —

    the return value of the block



127
128
129
130
131
132
133
 
# File 'lib/shakapacker.rb', line 127

def ensure_log_goes_to_stdout
  old_logger = Shakapacker.logger
  Shakapacker.logger = Logger.new(STDOUT)
  yield
ensure
  Shakapacker.logger = old_logger
end

#ensure_node_env! ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Sets NODE_ENV based on RAILS_ENV if not already set

Environment mapping:

  • development and test environments use “development” for NODE_ENV

  • All other environments (production, staging, etc.) use “production” for webpack optimizations

Note: We always use “development” (not “test”) for test environments because webpack/rspack only recognize “development” and “production” as valid NODE_ENV values. Using “test” causes DefinePlugin conflicts with optimization.nodeEnv.

This method is typically called automatically during Rails initialization.

Returns:

  • (String) —

    the NODE_ENV value that was set



111
112
113
 
# File 'lib/shakapacker.rb', line 111

def ensure_node_env!
  ENV["NODE_ENV"] ||= DEV_ENVS.include?(ENV["RAILS_ENV"]) ? "development" : "production"
end

#env ⇒ ActiveSupport::StringInquirer

Returns the current Rails environment as an ActiveSupport::StringInquirer

Returns:

  • (ActiveSupport::StringInquirer) —

    the environment

See Also:



152
 
# File 'lib/shakapacker.rb', line 152

delegate :logger, :logger=, :env, :inlining_css?, to: :instance

#inlining_css? ⇒ Boolean

Returns whether CSS inlining is enabled

Returns:

  • (Boolean) —

    true if CSS should be inlined

See Also:



152
 
# File 'lib/shakapacker.rb', line 152

delegate :logger, :logger=, :env, :inlining_css?, to: :instance

#instance ⇒ Shakapacker::Instance

Returns the shared Shakapacker instance

This instance is used by all module-level delegate methods. It provides access to configuration, compilation, manifest lookup, and more.

Returns:



71
72
73
 
# File 'lib/shakapacker.rb', line 71

def instance
  @instance ||= Shakapacker::Instance.new
end

#instance=(instance) ⇒ Shakapacker::Instance

Sets the shared Shakapacker instance

This is primarily used for testing or advanced customization scenarios. In most applications, the default instance is sufficient.

Parameters:

Returns:



60
61
62
 
# File 'lib/shakapacker.rb', line 60

def instance=(instance)
  @instance = instance
end

#logger ⇒ Logger

Returns the logger instance used by Shakapacker

Returns:

  • (Logger) —

    the logger instance

See Also:



152
 
# File 'lib/shakapacker.rb', line 152

delegate :logger, :logger=, :env, :inlining_css?, to: :instance

#logger=(logger) ⇒ Logger

Sets the logger instance used by Shakapacker

Parameters:

  • logger (Logger) —

    the logger to use

Returns:

  • (Logger) —

    the logger that was set

See Also:

  • Shakapacker::Instance#logger=


152
 
# File 'lib/shakapacker.rb', line 152

delegate :logger, :logger=, :env, :inlining_css?, to: :instance

#manifest ⇒ Shakapacker::Manifest

Returns the manifest instance for looking up compiled assets

Returns:

See Also:



174
 
# File 'lib/shakapacker.rb', line 174

delegate :config, :compiler, :manifest, :commands, :dev_server, to: :instance

#puts_deprecation_message(message) ⇒ Object 



6
7
8
 
# File 'lib/shakapacker/deprecation_helper.rb', line 6

def puts_deprecation_message(message)
  SHELL.say "\n#{message}\n", :yellow
end

#with_node_env(env) { ... } ⇒ Object

Temporarily overrides NODE_ENV for the duration of the block

This is useful when you need to perform operations with a specific NODE_ENV value without permanently changing the environment.

Examples:

Shakapacker.with_node_env("production") do
  # This code runs with NODE_ENV=production
  Shakapacker.compile
end

Parameters:

  • env (String) —

    the NODE_ENV value to use temporarily

Yields:

  • the block to execute with the temporary NODE_ENV

Returns:

  • (Object) —

    the return value of the block



89
90
91
92
93
94
95
 
# File 'lib/shakapacker.rb', line 89

def with_node_env(env)
  original = ENV["NODE_ENV"]
  ENV["NODE_ENV"] = env
  yield
ensure
  ENV["NODE_ENV"] = original
end