Rails Glossary > link_tree

link_tree

A Sprockets directive that recursively links all files in a directory tree for compilation and public availability, making them accessible as separate assets without bundling their contents into the current file.

Recursive asset linking in Sprockets manifests

What does link_tree do in Sprockets? The link_tree directive recursively links all files in a directory and its subdirectories, making them compilation targets that are written to disk and available to be served, without including their contents in the current file.

The link_tree directive is a fundamental Sprockets manifest command that enables recursive asset discovery and compilation across entire directory structures. It works like link_directory, but operates recursively to link all files in all subdirectories of the directory specified by path, making it essential for managing complex asset hierarchies in Rails applications.

Unlike bundling directives that combine files, link_tree preserves individual files as separate assets while ensuring they're compiled and made publicly available. This approach aligns with modern web performance strategies that leverage HTTP/2 multiplexing for efficient delivery of multiple small files.

How link_tree works in practice

The directive //= link_tree ../images says to go through every file in the images directory tree and generate it as an asset. The path argument is relative to the manifest file location, typically app/assets/config/manifest.js, using standard relative path notation like ../ to navigate up directories.

Recursive processing means link_tree descends into all subdirectories, processing every discoverable file. For an images directory containing app/assets/images/icons/search.png and app/assets/images/backgrounds/hero.jpg, both files become individually accessible assets after compilation.

File type filtering can be applied using an optional second argument. You can specify a second argument separated by a space so any extra files not matching the content-type specified will be ignored: //= link_tree ./path/to/folder text/javascript or //= link_tree ./path/to/other_folder .js.

Common usage patterns in Rails

Image asset management represents the most common link_tree use case. The default manifest.js created by rails new looks like: //= link_tree ../images, ensuring all images in app/assets/images/ and subdirectories become accessible through Rails' asset helpers.

Font directory processing works similarly, with //= link_tree ../fonts making all font files in subdirectories available for CSS font-face declarations and asset pipeline serving.

JavaScript file compilation can use link_tree when you need individual JavaScript files rather than bundled output: //= link_tree ../javascripts .js compiles each .js file separately instead of combining them.

Comparison with link_directory

The key difference is that link_directory links all files inside the directory specified by the path, but files in subdirectories will not be linked (Compare to link_tree).

link_directory processes only the immediate directory level:

  • app/assets/stylesheets/application.css ✓ included
  • app/assets/stylesheets/admin/dashboard.css ✗ not included

link_tree processes all directory levels:

  • app/assets/stylesheets/application.css ✓ included
  • app/assets/stylesheets/admin/dashboard.css ✓ included
  • app/assets/stylesheets/admin/users/index.css ✓ included

Sprockets 4 manifest.js integration

The manifest.js file is meant to specify which files to use as a top-level target using sprockets methods link, linkdirectory, and linktree. This replaced the older Rails.application.config.assets.precompile configuration array, providing more explicit control over asset compilation.

Rails applications using Sprockets 4 require the manifest.js file in app/assets/config/manifest.js. Here is an example of a manifest.js that links JS, CSS, fonts, and images: //= link_directory ../javascripts .js, //= link_directory ../stylesheets .css, //= link_tree ../fonts, //= link_tree ../images.

Performance and caching considerations

HTTP/2 optimization makes link_tree's individual file approach more viable than in HTTP/1.1 environments. Modern browsers efficiently handle parallel requests for multiple small assets, often outperforming large bundled files in caching scenarios.

Asset fingerprinting applies to each linked file individually, enabling granular cache invalidation. When one image changes, only that specific asset's cache invalidates, while other images maintain their cached versions.

Development vs production behavior remains consistent with link_tree, as the directive focuses on making files available rather than optimizing delivery. Additional optimization layers can be applied through CDNs or other caching strategies.

Migration and troubleshooting

When upgrading to Sprockets 4, you might find some files that were currently compiled by sprockets for delivery to browser no longer are. Adding appropriate link_tree directives to your manifest.js resolves these issues.

Path resolution errors commonly occur when relative paths don't match actual directory structures. The first argument to linkdirectory and linktree is a file path relative to the manifest.js itself (does not use "asset load path"), requiring careful attention to relative path navigation.

The link_tree directive provides essential functionality for Rails applications requiring comprehensive asset compilation while maintaining the flexibility of individual file serving, making it a cornerstone of modern Rails asset pipeline management.

Try Avo for free